snappy 3.2__cp313-cp313-macosx_11_0_arm64.whl

snappy/doc/_sources/index.rst.txt

@@ -0,0 +1,182 @@
+.. SnapPy documentation master file
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+======
+SnapPy
+======
+
+What is SnapPy?
+===============
+
+..  image:: images/SnapPy-196.png
+    :align: right
+    :alt: SnapPy logo
+
+
+SnapPy is a program for studying the topology and geometry of
+3-manifolds, with a focus on hyperbolic structures.  It runs on Mac OS
+X, Linux, and Windows, and combines a link editor and 3D-graphics for
+Dirichlet domains and cusp neighborhoods with a powerful command-line
+interface based on the Python_ programming language. You can see it
+:doc:`in action<screenshots>`, learn how to :doc:`install<installing>`
+it, and watch the :doc:`tutorial<tutorial>`.
+
+.. _Python: http://python.org
+
+News
+====
+
+* Version 3.2 (January 2025):
+
+  - An alternative implementation of the length spectrum. It supports verified
+    computations and is significantly faster in some cases. See
+    :meth:`length_spectrum_alt <snappy.Manifold.length_spectrum_alt>`
+    and
+    :meth:`length_spectrum_alt_gen <snappy.Manifold.length_spectrum_alt_gen>`.
+
+  - :meth:`isometry_signature <snappy.Manifold.isometry_signature>` now also
+    works for closed manifolds.
+
+  - A paper plane or eye ball in the
+    :meth:`inside_view <snappy.Manifold.inside_view>` showing the position
+    and bearing of the user in the hyperbolic manifold. By default, we now show
+    the paper plane instead of the edges of the triangulation so that the view
+    is intrinsic to the manifold. The geodesics window now also features a
+    button to put the camera onto a geodesic. Here are some examples:
+
+    .. list-table::
+       :width: 100%
+       :class: borderless
+
+       * - .. image:: images/o9_00000_systole_paper_plane.jpg
+              :width: 90%
+              :align: center
+              :alt: Paper plane near shortest geodesic of o9_00000
+         - .. image:: images/o9_00000_systole_paper_plane_closer.jpg
+              :width: 90%
+              :align: center
+              :alt: Paper plane very near shortest geodesic of o9_00000
+         - .. image:: images/m004_paper_plane_on_systole.jpg
+              :width: 90%
+              :align: center
+              :alt: Paper plane on shortest geodesic of m004
+         - .. image:: images/m125_paper_plane.jpg
+              :width: 90%
+              :align: center
+              :alt: Paper plane coming out of a cusp of m125
+
+  - A faster and more robust algorithm to the compute maximal cusp area matrix.
+    The new algorithm is now the default for
+    :meth:`~snappy.Manifold.cusp_area_matrix`,
+    :meth:`~snappy.Manifold.cusp_areas`,
+    :meth:`~snappy.Manifold.short_slopes` and
+    :meth:`~snappy.Manifold.cusp_translations`.
+
+  - New options ``ignore_curves`` and ``ignore_filling_orientations``
+    for :meth:`~snappy.Triangulation.triangulation_isosig`. Also
+    fixing a subtle bug where the filling coefficients returned by
+    :meth:`triangulation_isosig <snappy.Triangulation.triangulation_isosig>` were
+    not canonical when ``ignore_curve_orientations = True``.
+
+  - :meth:`~snappy.Manifold.canonical_retriangulation`
+    and
+    :meth:`~snappy.Manifold.isometry_signature` fail with
+    exceptions rather than silently returning ``None``. In particular, it now
+    safe to compare isometry signatures (without further checks) to determine
+    whether M and N are isometric hyperbolic manifolds::
+
+        >>> M.isometry_signature(verified=True) == N.isometry_signature(verified=True)
+
+  - Bug fix to :meth:`slice_obstruction_HKL
+    <snappy.Manifold.slice_obstruction_HKL>`: earlier versions
+    incorrectly allowed looking at mod 2 homology of the branched
+    cover, where the theory does not directly apply.
+
+  - New self-contained SnapPy application for Linux. 
+  
+  - Support for Python 3.13 and SageMath 10.5.
+
+    
+* Versions 3.1 (May 2023) and 3.1.1 (June 2023):
+
+  - A method :meth:`exterior_to_link <snappy.Manifold.exterior_to_link>`
+    for going from a link exterior to a link diagram taken from
+    `Dunfield-Obeidin-Rudd <https://arxiv.org/abs/2112.03251>`_.
+
+  - Covers now computed by the stand-alone `low_index
+    <https://pypi.org/project/low-index/>`_ module, which uses
+    multiple processor cores and is typically much faster than the old
+    code.  In some cases, it is dramatically faster than even GAP or
+    Magma.
+
+  - Added geodesics to the :meth:`inside_view
+    <snappy.Manifold.inside_view>`.  Here are some intersecting tubes
+    about closed geodesics in the manifold ``v3539(5,1)``:
+
+    .. image:: images/geodesics.jpg
+       :width: 50%
+       :align: center
+       :alt: Geodesic tubes for v3539(5,1)
+
+  - Added drilling any simple geodesic with :meth:`drill_word
+    <snappy.Manifold.drill_word>` and :meth:`drill_words
+    <snappy.Manifold.drill_words>`, not just those that are
+    :meth:`combinatorially simple <snappy.Manifold.dual_curves>`.
+
+  - Added `ignore_orientation` flag to :meth:`triangulation_isosig
+    <snappy.Triangulation.triangulation_isosig>`.
+
+  - Added `include_words` flag to :meth:`length_spectrum
+    <snappy.Manifold.length_spectrum>` for getting the word
+    corresponding to a geodesic which can be given to
+    :meth:`drill_word <snappy.Manifold.drill_word>`.
+
+  - Support for Python 3.11 and SageMath 10.0.
+
+  - Modernized styling of the documentation.
+
+* :doc:`Complete version history <news>`.
+
+Documentation
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   installing
+   screenshots
+   tutorial
+   snappy
+   plink
+   spherogram
+   snap
+   verify
+   other
+   news
+   credits
+   bugs
+   todo
+   development
+
+Credits
+=======
+
+Written by `Marc Culler <http://www.math.uic.edu/~culler>`_, `Nathan
+Dunfield <http://dunfield.info>`_, and `Matthias Goerner
+<http://www.unhyperbolic.org/>`_ using the SnapPea kernel written by
+`Jeff Weeks <http://www.geometrygames.org>`_, with contributions from
+:doc:`many others <credits>`.  If you use SnapPy in your work, please
+:ref:`cite it as described here <credits:Citing SnapPy>`.  If you
+encounter problems with SnapPy, :doc:`please report them <bugs>`.
+
+Released under the terms of the `GNU General Public License
+<http://www.gnu.org/licenses/gpl-2.0.txt>`_, version 2 or later.
+
+The development of SnapPy was partially supported by grants from the
+National Science Foundation, including DMS-0707136, DMS-0906155,
+DMS-1105476, DMS-1510204, DMS-1811156, and the Institute for
+Computational and Experimental Research in Mathematics. Any opinions,
+findings, and conclusions or recommendations expressed on this site
+are those of the authors and do not necessarily reflect the views of
+the National Science Foundation.

snappy/doc/_sources/installing.rst.txt

@@ -0,0 +1,247 @@
+.. Installing SnapPy
+
+Installing SnapPy
+=================
+
+Here are detailed instructions on how to get SnapPy working on a
+variety of platforms.  The current version is |release| which was released
+on |release_date|.  If you encounter any problems installing SnapPy,
+:doc:`please let us know <bugs>`.
+
+macOS
+-----
+
+Simply download `SnapPy.dmg
+<https://github.com/3-manifolds/SnapPy/releases/latest/download/SnapPy.dmg>`_
+and copy SnapPy.app to the Applications folder.  Double-click to start
+it, just like any other application.  The current version works with macOS 10.14 and
+newer and earlier releases `can be found here
+<https://github.com/3-manifolds/SnapPy/releases/>`_.
+
+Windows
+-------
+
+Simply download and run `InstallSnapPy.exe
+<https://github.com/3-manifolds/SnapPy/releases/latest/download/InstallSnapPy.exe>`_.
+Earlier releases `can be found here
+<https://github.com/3-manifolds/SnapPy/releases/>`_.
+
+
+Linux app
+---------
+
+Starting with SnapPy 3.2, a completely self-contained SnapPy `AppImage
+<https://docs.appimage.org/introduction/quickstart.html#ref-quickstart>`_
+is available that should work on any Linux system from the last 5
+years.  This AppImage contains its own private copy of Python, so if
+you plan to use SnapPy in your own Python programs, skip ahead to
+`Python Modules for Linux`_.  Here is the recipe for installing the
+AppImage in ``~/bin`` after you have downloaded the file
+`SnapPy-x86_64.AppImage
+<https://github.com/3-manifolds/SnapPy/releases/latest/download/SnapPy-x86_64.AppImage.>`_::
+
+  mkdir -p ~/bin
+  mv ~/Downloads/SnapPy-x86_64.AppImage ~/bin
+  chmod +x ~/bin/SnapPy-x86_64.AppImage
+  ln -s -f ~/bin/SnapPy-x86_64.AppImage ~/bin/SnapPy
+  ~/bin/SnapPy-x86_64.AppImage --install
+
+The last command registers the SnapPy app with your desktop system and
+starts it.  Next time, you can start SnapPy by using the desktop
+search tool with GNOME or the main menu with KDE. You can pin also the icon
+to your dash or task bar for easy access.  From a terminal window, you
+can also start the app by typing ``SnapPy`` provided ``~/bin`` is in
+your `$PATH <https://opensource.com/article/17/6/set-path-linux>`_.
+
+
+Python Modules for macOS or Windows
+-----------------------------------
+
+If you write Python programs on macOS or Windows, you may wish to
+install SnapPy as a Python module into your own copy of Python.  We
+support Python 3.9 and up.  (On macOS, use a Python downloaded from
+`Python.org <http://python.org>`_ and not the one provided by Apple.)
+After installing Python, you may install a SnapPy module from your
+Terminal application or Command Prompt with the command::
+
+    python3 -m pip install --upgrade --user snappy snappy_15_knots
+
+If you do not want the larger version of HTLinkExteriors that includes
+the 15 crossing knots (it uses 110M of disk space), omit
+``snappy_15_knots`` from the command.
+
+
+Python Modules for Linux
+------------------------
+
+You can also use SnapPy with your Linux system's version of Python,
+for example if you want to incorporate SnapPy in your own Python
+scripts.  These instructions assume you have system administrator
+(superuser) privileges to install software packages from your Linux
+distribution.  (If you're not a superuser, use either the
+`Linux app`_ or `conda`_.)
+
+The first step is to install Python and other requirements; here's how
+to do that on the most popular Linux distributions:
+
++ **Ubuntu/Debian/Mint/MX Linux/Elementary:** Tested on Ubuntu 24.04::
+
+    sudo apt install python3-pip python3-tk
+
++ **Fedora**: Tested on Fedora 41::
+
+    sudo dnf install python3-pip python3-tkinter
+
++ **Arch/Manjaro/EndeavourOS**: Install via::
+
+    sudo pacman -Sy python-pip tk
+
++ **openSUSE**: For Tumbleweed::
+
+    sudo zypper install python3-pip python3-tk
+
+  For Leap, as of version 15.6 you need to ask for a recent version of
+  Python or it will give you Python 3.6 which is too old for SnapPy::
+
+    sudo zypper install python312-pip python312-tk
+
+  You will need to replace ``python3`` by ``python3.12`` in subsequent
+  steps.
+
++ **Red Hat Enterprise Linux/CentOS/Rocky Linux/AlmaLinux:**: These instructions
+  are for version 8 or later; tested on AlmaLinux 8 and 9::
+
+    sudo dnf install python3.11-pip python3.11-tkinter
+
+  You will also need to replace ``python3`` by ``python3.11`` in subsequent
+  steps.
+
+
+Next, you need to install the SnapPy Python modules. For this, you can
+either use a *virtual environment* (``python -m venv``) or do a *user
+install* (``pip install --user``).  The former will work on any
+version of Linux, whereas the latter is now strongly discouraged on
+many systems (e.g. Ubuntu 24.04).  If you have not previously
+installed SnapPy on this computer, we recommend using a virtual
+environment, but suggest a user install if you are upgrading an
+existing version of SnapPy that was installed in that manner.
+
+Virtual environment
+  Here is the `official tutorial
+  <https://docs.python.org/3/tutorial/venv.html>`_ on using virtual
+  environments in Python and an `in-depth article
+  <https://realpython.com/python-virtual-environments-a-primer/>`_.  A
+  recipe is::
+
+    python3 -m venv snappy_venv
+    # Switch to snappy_venv's Python
+    source snappy_venv/bin/activate
+    pip install snappy snappy_15_knots
+    # Start the SnapPy app!
+    SnapPy
+    # Return to system Python
+    deactivate
+
+  If you always want to use the ``snappy_venv`` Python, adjust your
+  `$PATH <https://opensource.com/article/17/6/set-path-linux>`_ to
+  **start** with ``snappy_venv/bin``.
+
+User install
+  To do a user install with pip, try::
+
+    # Note no "sudo" below!
+    python3 -m pip install --upgrade --user snappy snappy_15_knots
+
+  If you get a long error message that starts::
+
+    error: externally-managed-environment
+
+  you should probably use a virtual environment; however,
+  you can force pip to do a user install via::
+
+    # Note no "sudo" below!
+    python3 -m pip install --upgrade --user --break-system-packages snappy snappy_15_knots
+
+  Despite the scary name, provided you don't use ``sudo``, this will
+  not actually modify the system packages, but rather install
+  ``snappy`` into the subdirectory
+  ``~/.local/share/python3.*/site-packages`` of your home directory.
+
+  After a user install, you run the following command to start
+  the app::
+
+    ~/.local/bin/SnapPy
+
+  So that you can start SnapPy with just the command ``SnapPy``, make
+  sure ``~/.local/bin`` is in `in your path
+  <https://opensource.com/article/17/6/set-path-linux>`_.
+
+
+SageMath
+--------
+
+SnapPy has some special features when used within `SageMath
+<http://sagemath.org>`_, the universal mathematics software based on
+Python.  This section describes how to install SnapPy into your
+existing copy of SageMath::
+
+  sage -pip install --upgrade snappy snappy_15_knots
+
+Alternatively, SageMath on `CoCalc <https://cocalc.com/>`_ (formerly
+the SageMathCloud) also has SnapPy preinstalled, and the graphics
+features even work via the `X11 interface
+<http://blog.sagemath.com/cocalc/2018/11/05/x11.html>`_, see the
+bottom of that page for more.
+
+The graphical features may or may not work, depending on how Tkinter
+was configured within Sage.  (There is no problem on macOS if you use
+this `SageMath binary
+<https://github.com/3-manifolds/Sage_macOS/releases>`_.)  If the
+graphical features seem to "hang" when you try to start them, type
+``%gui tk`` at the Sage prompt; please note that doing so may break
+Sage's "attach" feature.
+
+
+Kitchen sink
+------------
+
+SnapPy gains extra features when used in `SageMath`_ and one can use
+Sage's Python to interact not just with SnapPy but a range of other
+computational tools in low-dimensional topology including
+`Regina <http://regina-normal.github.io/>`_,
+`snap <http://snap-pari.sourceforge.net>`_,
+`heegaard <https://github.com/3-manifolds/heegaard>`_,
+`gridlink <https://github.com/3-manifolds/gridlink>`_,
+and `flipper <http://flipper.readthedocs.io>`_.
+We offer a `prepackaged Docker image
+<https://hub.docker.com/r/computop/sage/>`_ with all of the above tools
+and many more; using this is sometimes the easiest way to get a
+working setup for such multifaceted computations, especially on Windows.  For more, watch
+`this demonstration <https://icerm.brown.edu/video_archive/?play=1992>`_.
+
+
+Conda
+-----
+
+Conda can be used to install Python on all platforms and is a
+particularly good choice to use SnapPy on the older Linux systems
+often found on high-performance clusters.  Here is a recipe for
+installing SnapPy into a new conda environment on macOS or Linux::
+
+  source ~/miniforge3/bin/activate
+  mamba create --name snappy_env python=3.12
+  conda activate snappy_env
+  pip install snappy
+  python -m snappy.app
+
+
+Source code
+-----------
+
+The complete source code for all platforms: |tarball|_
+
+You can also browse our `source code repository
+<https://github.com/3-manifolds/SnapPy>`_ or clone it using `git
+<https://git-scm.com/>`_ via::
+
+  git clone https://github.com/3-manifolds/SnapPy.git

snappy/doc/_sources/manifold.rst.txt

@@ -0,0 +1,6 @@
+Manifold: the main class
+========================
+
+..   autoclass:: snappy.Manifold
+     :members:
+     :inherited-members:

snappy/doc/_sources/manifoldhp.rst.txt

@@ -0,0 +1,46 @@
+ManifoldHP: High-precision variant
+==================================================
+
+A ManifoldHP is a variant of :class:`Manifold <snappy.Manifold>` which
+does all floating-point calculations in `quad-double precision
+<http://web.mit.edu/tabbott/Public/quaddouble-debian/qd-2.3.4-old/docs/qd.pdf>`_,
+which has four times as many significant digits as the ordinary
+`double precision numbers
+<http://en.wikipedia.org/wiki/Double_precision_floating-point_format>`_
+used by Manifold.  More precisely, numbers used in ManifoldHP have 212
+bits for the mantissa/significand (roughly 63 decimal digits) versus
+53 bits with Manifold.
+
+To the user, the only difference between Manifold and ManifoldHP is the extra precision::
+
+   >>> L = Manifold('m004')
+   >>> L.volume()
+   2.02988321282
+   >>> H = ManifoldHP('m004')
+   >>> H.volume()
+   2.029883212819307250042405108549040571883378615060599584034978214
+
+and it is easy to go back and forth between the two types::
+
+    >>> D = H.low_precision()
+    >>> D.volume(), type(D)
+    (2.02988321282, <class 'snappy.Manifold'>)
+    >>> U = L.high_precision()
+    >>> type(U)
+    <class 'snappy.ManifoldHP'>
+
+FAQ
+---
+
+Q. How does this differ from the program `Snap <http://snap-pari.sourceforge.net/>`_ or the :doc:`corresponding features <snap>` of SnapPy? 
+
+A. Snap computes hyperbolic structures to whatever precision you specify, not just 212 bits.  However, only some aspects of that structure can be accessed at the higher precision.  In contrast, with ManifoldHP every part of the SnapPea kernel uses the high-precision structure.  Eventually, we hope to add a ManifoldAP which allows for arbitrary precision throughout the kernel.  
+
+Q. Are there any negatives to using ManifoldHP over Manifold?
+
+A. Yes, ManifoldHP is generally slower by a factor of 10 to 100.  Multiplying two quad-double numbers requires at least 10 ordinary double multiplications, so some of this is inevitable.  
+
+Q. What is one place where the extra precision really helps?  
+
+A. Computing Dirichlet domains and subsidiary things like the length spectrum. A ManifoldHP can find the Dirichlet domain of a typically 15 crossing knot exterior but Manifold can't.  
+