snappy 3.0.3__cp38-cp38-macosx_11_0_arm64.whl → 3.2__cp38-cp38-macosx_11_0_arm64.whl

snappy/doc/_sources/installing.rst.txt

@@ -5,8 +5,8 @@ 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,
-:doc:`please let us know <bugs>`. 
+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
-    
-+ **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::
+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`_.)
 
-    sudo yum install epel-release
+The first step is to install Python and other requirements; here's how
+to do that on the most popular Linux distributions:
 
-  Now install via::
-    
-    sudo yum install python36-tkinter python36-pip
-    # Note no "sudo" on the next one!
-    python36 -m pip install --upgrade --user snappy
++ **Ubuntu/Debian/Mint/MX Linux/Elementary:** Tested on Ubuntu 24.04::
 
-+ **Arch/Manjaro**: Install via::
+    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
-    # 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.
 
-    ~/.local/bin/SnapPy
++ **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 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>`_.
+  You will also need to replace ``python3`` by ``python3.11`` in subsequent
+  steps.
 
 
-Python Modules for Macintosh or Windows
----------------------------------------
+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.
 
-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::
+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 pip install --upgrade --user snappy
+    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 want the larger version of HTLinkExteriors that includes the 15
-crossing knots (uses 110M of disk space), do::
+  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_15_knots
+User install
+  To do a user install with pip, try::
 
-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/>`_.
+    # 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
@@ -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.
-
-
-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:
+Conda
+-----
 
-- `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