snappy 3.1.1__cp311-cp311-macosx_11_0_arm64.whl → 3.2__cp311-cp311-macosx_11_0_arm64.whl

snappy/doc/_sources/installing.rst.txt

@@ -5,7 +5,7 @@ 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 problems installing SnapPy,
+on |release_date|.  If you encounter any problems installing SnapPy,
 :doc:`please let us know <bugs>`.
 
 macOS
@@ -14,8 +14,8 @@ 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.  Works with macOS/OS X 10.9 and
-newer.  Earlier releases `can be found here
+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
@@ -27,102 +27,154 @@ Earlier releases `can be found here
 <https://github.com/3-manifolds/SnapPy/releases/>`_.
 
 
-Linux
------
+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>`_.
+
 
-Here are short recipes which work on most Linux systems, specifically
-those that run a 64-bit kernel and have Python 3.6 or newer. These
-instructions assume you have system administrator (superuser)
-privileges to install software packages from your Linux distribution
-but want to install SnapPy (and its various Python dependencies) just
-in your own user directory, specifically ``~/.local``.  For other
-Linux systems, try the one closest to yours below, and if that fails,
-follow the instructions for `generic Unix`_.
+Python Modules for macOS or Windows
+-----------------------------------
 
-+ **Ubuntu/Debian/Mint**: Tested on Ubuntu 20.04::
+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::
 
-    sudo apt-get install python3-tk python3-pip
-    # Note no "sudo" on the next one!
-    python3 -m pip install --upgrade --user snappy
+    python3 -m pip install --upgrade --user snappy snappy_15_knots
 
-  Users of Ubuntu 18.04 or older should do::
+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.
 
-    sudo apt-get install python3-tk python3-pip
-    # Note no "sudo" on the next two
-    python3 -m pip install --upgrade --user pip wheel
-    python3 -m pip install --upgrade --user snappy
 
-+ **Fedora**: Tested on Fedora 30::
+Python Modules for Linux
+------------------------
 
-    sudo yum install python3-tkinter python3-pip
-    # Note no "sudo" on the next one!
-    python3 -m pip install --upgrade --user snappy
+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`_.)
 
-+ **Red Hat Enterprise Linux/CentOS/SciLinux**: These instructions
-  are for version 7 or later, and you need to have the `EPEL packages
-  available
-  <https://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F>`_.
-  For CentOS and SciLinux, you can access EPEL packages by doing::
+The first step is to install Python and other requirements; here's how
+to do that on the most popular Linux distributions:
 
-    sudo yum install epel-release
++ **Ubuntu/Debian/Mint/MX Linux/Elementary:** Tested on Ubuntu 24.04::
 
-  Now install via::
+    sudo apt install python3-pip python3-tk
 
-    sudo yum install python36-tkinter python36-pip
-    # Note no "sudo" on the next one!
-    python36 -m pip install --upgrade --user snappy
++ **Fedora**: Tested on Fedora 41::
 
-+ **Arch/Manjaro**: Install via::
+    sudo dnf install python3-pip python3-tkinter
+
++ **Arch/Manjaro/EndeavourOS**: Install via::
 
     sudo pacman -Sy python-pip tk
-    # Note no "sudo" on the next one!
-    python -m pip install --upgrade --user snappy
 
-+ **openSUSE**: Install via::
++ **openSUSE**: For Tumbleweed::
 
-    sudo zypper install -y python3-tk python3-pip
-    # Note no "sudo" on the next one!
-    python3 -m pip install --upgrade --user snappy
+    sudo zypper install python3-pip python3-tk
 
-If you want the larger version of HTLinkExteriors that includes the 15
-crossing knots (uses 110M of disk space), also install the Python
-package ``snappy_15_knots``, e.g. on Ubuntu do::
+  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::
 
-  python3 -m pip install --upgrade --user snappy_15_knots
+    sudo zypper install python312-pip python312-tk
 
-Once you have installed SnapPy, do the following to start it::
+  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.
 
-    ~/.local/bin/SnapPy
 
-You may get a message about creating a ".ipython" directory; this is
-normal, just hit return to continue.  There should also now be a
-command "SnapPy" which does the same thing.  To make it 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>`_.
+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::
 
-Python Modules for Macintosh or Windows
----------------------------------------
+    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 write Python programs on a Macintosh or Windows system, you may
-wish to install SnapPy as a Python module into your own copy of
-Python.  We support Python 3.6 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
-commands::
+  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``.
 
-    python3 -m pip install --upgrade --user snappy
+User install
+  To do a user install with pip, try::
 
-If you want the larger version of HTLinkExteriors that includes the 15
-crossing knots (uses 110M of disk space), do::
+    # Note no "sudo" below!
+    python3 -m pip install --upgrade --user snappy snappy_15_knots
 
-    python3 -m pip install --upgrade --user snappy_15_knots
+  If you get a long error message that starts::
 
-If you use Python 2 rather than Python 3, replace ``python3`` with
-``python`` in the above.  If your Python lacks the pip module, `get it
-here <https://pip.pypa.io/en/stable/installing/>`_.
+    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
@@ -131,15 +183,9 @@ 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, but you may find it easier to use the
-`kitchen sink`_ approach instead.  You can install it as a Sage
-optional package via the following if using Sage 6.4 or newer::
-
-  sage -pip install snappy
-  sage -pip install snappy_15_knots  # Larger version of HTLinkExteriors
+existing copy of SageMath::
 
-If you are on macOS, we recommend use `this binary
-<https://github.com/3-manifolds/Sage_macOS/releases>`_.
+  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
@@ -147,17 +193,13 @@ 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.
 
-If you previously installed SnapPy into SageMath and want to upgrade
-SnapPy to the latest version, do::
-
-  sage -pip install --upgrade snappy
-
-If it has trouble when compiling CyOpenGL, you are probably missing
-the `"gl.h" headers <openglmesa>`.  The graphical features may or may
-not work, depending on how Tkinter was configured within Sage, and may
-seem to "hang" when you try to start them.  To deal with the latter
-issue type "%gui tk" at the Sage prompt; please note that doing so may
-break Sage's "attach" feature.
+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
@@ -173,83 +215,24 @@ computational tools in low-dimensional topology including
 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 frequently the easiest way to get a
-working setup for such multifaceted computations.  For more, watch
+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>`_.
 
-We also offer `conda environments
-<https://github.com/unhyperbolic/condaForSnapPy>`_ with SnapPy and
-optionally Sage (only on Mac OS and Linux). While it has none of the
-other aforementioned tools, it has the advantage that the GUI elements
-such as the link editor and the browser can be used directly.
 
+Conda
+-----
 
-Generic Unix
-------------
-
-If you use a Unix other than OS X or Linux, or if the prebuilt
-packages don't work for you, you'll need to build SnapPy from source.
-Here are some detailed instructions.
-
-Things you'll need:
-
-- Python 3 with Tkinter: You'll need to have `Python
-  <http://python.org>`_ (version 3.6 or newer) and `Tk
-  <http://tcl.tk>`_ (at least version 8.5) with `Tkinter
-  <http://wiki.python.org/moin/TkInter>`_ to connect them, including
-  the header files.  For instance, on Debian or Ubuntu, install the
-  packages "python3-tk", "python3-pip", and "python3-dev". On Fedora,
-  you'll want e.g. "python3-tkinter", "python3-pip", and
-  "python3-devel", and "python3-wheel".
-
-- Test that Python is in order by installing PLink from source::
-
-      python3 -m pip install --user plink
-      python3 -m plink.app  # Should start the link editor!
-
-.. _openglmesa:
-
-- Support for OpenGL (3D graphics): This is built in on OS X and the
-  most installations of Fedora and Ubuntu.  But you'll need the `MESA
-  <http://www.mesa3d.org/>`_ header files "gl.h" and "glu.h" to compile
-  SnapPy.  On Debian and Ubuntu, install "libglu1-mesa-dev"; On Fedora install
-  "mesa-libGLU-devel".
-
-- `Cython <http://cython.org>`_, which you can install via::
-
-    python3 -m pip install --user cython
-
-- The gcc C++ compiler, g++.
-
-- `CyPari <https://pypi.python.org/pypi/cypari/>`_: a stand-alone version of
-  `Sage's <http://sagemath.org>`_ Python interface to the
-  `PARI <http://pari.math.u-bordeaux.fr/PARI>`_ number theory
-  library.  Usually, you can install this with::
-
-     python3 -m pip install --user cypari
-
-Now download the `source code`_ listed below, for instance
-
-.. parsed-literal::
-
-   wget https://pypi.python.org/packages/source/s/snappy/|tarball|
-   tar xfz |tarball|; cd snappy-*
-
-There is one more dependency that may need to be dealt with:
-
-- `Togl <http://togl.sf.net>`_: a 3d widget for Tk. For OS X and
-  Linux, there are pre-built binaries of this in the snappy
-  subdirectory, e.g. snappy/linux2-tk8.4.  For Linux these are built
-  for 64-bit kernels, and should work on most systems.  If they don't,
-  you'll need to edit or follow "build_togl.sh" to build Togl directly.
-
-Finally, compile and install the SnapPy module (which will install
-certain other dependencies) and test::
+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::
 
-  python3 setup.py build
-  python3 -m pip install --user .
-  python3 -m snappy.test
-  python3 -m snappy.app
+  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

snappy/doc/_sources/news.rst.txt

@@ -4,7 +4,79 @@
 News
 ====
 
-* Version 3.1 (May 2023):
+
+* 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

snappy/doc/_sources/ptolemy_examples1.rst.txt

@@ -146,7 +146,7 @@ Compute the matrices for a representation
 
 **Remark:** Requires SnapPy 2.3 or later.
 
-Given a solution as above, we can take a word in the fundamental group and get its image under the representation using ``evaluate_word``. Here, we do it for the two generators::
+Given a solution as above, we can take a word in the fundamental group and get its image under the representation using :py:meth:`~snappy.ptolemy.coordinates.PtolemyCoordinates.evaluate_word`. Here, we do it for the two generators::
 
     >>> M = Manifold("m003")
     >>> sol = M.ptolemy_variety(2).retrieve_solutions()[0]
@@ -156,16 +156,17 @@ Given a solution as above, we can take a word in the fundamental group and get i
     [[Mod(x, x^2 - x - 1), Mod(x, x^2 - x - 1)],
     [Mod(-x, x^2 - x - 1), Mod(-1, x^2 - x - 1)]]
 
-By default, this word is with respect to the presentation of the fundamental group that SnapPy computes when given no further arguments. Thus, we expect the identity matrix when we evaluate a relator (for PSL(*N*, **C**) the diagonal element will be an *N*-th root of unity)::
+By default, this word is with respect to the unsimplified presentation of the fundamental group. Thus, we expect the identity matrix when we evaluate a relator (for PSL(*N*, **C**) the diagonal element will be an *N*-th root of unity)::
 
-    >>> M.fundamental_group()
+    >>> M.fundamental_group(simplify_presentation=False)
     Generators:
-       a,b
+       a,b,c
     Relators:
-       abAAbabbb
-    >>> sol.evaluate_word('abAAbabbb')
+       BCaC
+       AbCbA
+    >>> sol.evaluate_word('BCaC')
     [[Mod(1, x^2 - x - 1), 0], [0, Mod(1, x^2 - x - 1)]]
-    
+
 We revisit computing the matrices :ref:`here <ptolemy-detailed-example-matrices>` to explain how to use a different presentation of the fundamental group.
 
 **Remark:** The matrices are currently returned as a list of list of pari ``POLMOD`` objects. In the future, the ptolemy module should return the matrices as sage matrices over a `sage NumberField <http://doc.sagemath.org/html/en/reference/number_fields/sage/rings/number_field/number_field.html>`_.

snappy/doc/_sources/ptolemy_examples3.rst.txt

@@ -101,7 +101,7 @@ And here the same example retrieving solutions from the database::
 Computing the matrices for a different presentation
 ---------------------------------------------------
 
-The ``fundamental_group`` method of a SnapPy triangulation can yield different presentations by supplying  optional arguments such as ``simplify_presentation`` and ``minimize_number_of_generators``. If we have a word in one of these presentations and want to evaluate its image under the representation, we need to supply the presentation as follows::
+The :py:meth:`~snappy.Triangulation.fundamental_group` method of a SnapPy triangulation can yield different presentations by supplying  optional arguments such as ``simplify_presentation`` and ``minimize_number_of_generators``. If we have a word in one of these presentations and want to evaluate its image under the representation, we need to supply the presentation as follows::
 
     >>> M=Manifold("m003")
     >>> sol = M.ptolemy_variety(2).retrieve_solutions()[0]
@@ -129,7 +129,7 @@ Again, we can check that the representation actually assigns the identity to all
 Computing the images of the peripheral curves for a representation
 ------------------------------------------------------------------
 
-The object returned by ``fundamental_group`` also contains words for the peripheral curves of a manifold. We can compute the corresponding matrices::
+The object returned by :py:meth:`~snappy.Triangulation.fundamental_group` also contains words for the peripheral curves of a manifold. We can compute the corresponding matrices::
 
     >>> M = Manifold("m003")
     >>> G = M.fundamental_group()

snappy/doc/_sources/triangulation.rst.txt

@@ -3,8 +3,8 @@
 Triangulation
 =================
 
-The main snappy class, namely Manifold, is derived from more
-basic class below.  
+The main snappy class, namely Manifold, is derived from the more
+basic class below.
 
 ..   autoclass:: snappy.Triangulation
      :members: