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

snappy/__init__.py

@@ -1,17 +1,20 @@
-#from __future__ import print_function
 # import the SnapPy bindings
-#import logging
-#logging.basicConfig(filename='example.log',level=logging.DEBUG)
-#logging.debug('This message should go to the log file')
+# import logging
+# logging.basicConfig(filename='example.log',level=logging.DEBUG)
+# logging.debug('This message should go to the log file')
 import sys
-from .SnapPy import (AbelianGroup, HolonomyGroup, FundamentalGroup,
-                     DirichletDomain, CuspNeighborhood, SymmetryGroup,
-                     AlternatingKnotExteriors, NonalternatingKnotExteriors,
+from .SnapPy import (AbelianGroup,
+                     FundamentalGroup,
+                     SymmetryGroup,
+                     Isometry,
+                     AlternatingKnotExteriors,
+                     NonalternatingKnotExteriors,
                      pari)
-from .exceptions import SnapPeaFatalError
 from .SnapPy import DirichletDomain
 from .SnapPyHP import DirichletDomain as DirichletDomainHP
+from .SnapPy import CuspNeighborhood
 from .SnapPyHP import CuspNeighborhood as CuspNeighborhoodHP
+from .SnapPy import HolonomyGroup
 from .SnapPyHP import HolonomyGroup as HolonomyGroupHP
 
 from .SnapPy import Triangulation as _TriangulationLP
@@ -24,14 +27,56 @@ import time
 from .SnapPy import set_rand_seed
 set_rand_seed(int(time.time()))
 
+from .exceptions import (SnapPeaFatalError,
+                         InsufficientPrecisionError,
+                         NonorientableManifoldError)
+
+from typing import Union, Tuple, List, Optional
+
+# Subclass to be able to monkey-patch
 class Triangulation(_TriangulationLP):
     __doc__ = _TriangulationLP.__doc__
-    
+
+# Subclass to be able to monkey-patch
 class TriangulationHP(_TriangulationHP):
     __doc__ = _TriangulationHP.__doc__
 
-class Manifold(_ManifoldLP):
+# We want Manifold to be a subclass of Triangulation.
+# Unfortunately, that introduces a diamond pattern here.
+# Luckily, the python resolves methods and bases classes
+# in the presence of a diamond pattern seem to work just
+# fine. In particular, we do not double allocate the underlying
+# C structures.
+class Manifold(_ManifoldLP, Triangulation):
     __doc__ = _ManifoldLP.__doc__
+
+    def identify(self, extends_to_link=False):
+        """
+        Looks for the manifold in all of the SnapPy databases.
+        For hyperbolic manifolds this is done by searching for isometries:
+
+        >>> M = Manifold('m125')
+        >>> M.identify()
+        [m125(0,0)(0,0), L13n5885(0,0)(0,0), ooct01_00000(0,0)(0,0)]
+
+        By default, there is no restriction on the isometries. One can
+        require that the isometry take meridians to meridians. This
+        might return fewer results:
+
+        >>> M.identify(extends_to_link=True)
+        [m125(0,0)(0,0), ooct01_00000(0,0)(0,0)]
+
+        For closed manifolds, extends_to_link doesn't make sense
+        because of how the kernel code works:
+
+        >>> C = Manifold("m015(1,2)")
+        >>> C.identify()
+        [m006(-5,2)]
+        >>> C.identify(True)
+        []
+        """
+        return self._identify(extends_to_link)
+
     def high_precision(self):
         """
         Return a high precision version of this manifold.
@@ -56,8 +101,11 @@ class Manifold(_ManifoldLP):
     def low_precision(self):
         return self.copy()
 
-class ManifoldHP(_ManifoldHP):
+# We want ManifoldHP to be a subclass of TriangulationHP.
+# See comment about Manifold and the diamond pattern.
+class ManifoldHP(_ManifoldHP, TriangulationHP):
     __doc__ = _ManifoldHP.__doc__
+
     def low_precision(self):
         """
         Return a low precision version of this high precision manifold.
@@ -65,6 +113,7 @@ class ManifoldHP(_ManifoldHP):
         >>> M = ManifoldHP('m004')
         >>> type(M.low_precision())
         <class 'snappy.Manifold'>
+
         """
         LP = Manifold('empty')
         LP._from_string(self._to_string(), initialize_structure=False)
@@ -84,27 +133,32 @@ class ManifoldHP(_ManifoldHP):
 
     def identify(self, extends_to_link=False):
         """
-        Look for the manifold in all of the SnapPy databases:
+        Looks for the manifold in all of the SnapPy databases.
+        For hyperbolic manifolds this is done by searching for isometries:
 
         >>> M = ManifoldHP('m125')
         >>> M.identify()
         [m125(0,0)(0,0), L13n5885(0,0)(0,0), ooct01_00000(0,0)(0,0)]
-        
-        One can require that there be an isometry taking merdians
-        to meridians:
+
+        By default, there is no restriction on the isometries. One can require
+        that the isometry take meridians to meridians. This might return
+        fewer results:
 
         >>> M.identify(extends_to_link=True)
         [m125(0,0)(0,0), ooct01_00000(0,0)(0,0)]
-        
+
         For closed manifolds, extends_to_link doesn't make sense because
-        of how the kernel code works:        
+        of how the kernel code works:
+
         >>> C = Manifold("m015(1,2)")
         >>> C.identify()
         [m006(-5,2)]
         >>> C.identify(True)
         []
+
         """
-        return self.low_precision().identify(extends_to_link)
+        return self.low_precision()._identify(extends_to_link)
+
 
 SnapPy._manifold_class = Manifold
 SnapPy._triangulation_class = Triangulation
@@ -116,449 +170,387 @@ __all__ = ['Triangulation', 'Manifold', 'ManifoldHP', 'AbelianGroup',
            'DirichletDomain', 'DirichletDomainHP', 'CuspNeighborhood',
            'CuspNeighborhoodHP', 'SymmetryGroup', 'AlternatingKnotExteriors',
            'NonalternatingKnotExteriors', 'SnapPeaFatalError',
+           'InsufficientPrecisionError',
            'pari', 'twister', ]
 
-from .sage_helper import _within_sage
-if _within_sage:
-    to_sage = lambda n : n.sage()
-    Manifold.use_field_conversion(to_sage)
-    ManifoldHP.use_field_conversion(to_sage)
+def _symmetrize_high_precision_manifold(
+        mfd1 : Union[Manifold, ManifoldHP],
+        mfd2 : Union[Manifold, ManifoldHP]
+              ) -> Union[Tuple[Manifold, Manifold],
+                         Tuple[ManifoldHP, ManifoldHP]]:
+    """
+    Given a (potential) mix of two Manifold and ManifoldHP,
+    promote one to high precision if necessary and return
+    the result as pair.
+    """
+    resolved_mfd1 = mfd1
+    resolved_mfd2 = mfd2
+    high1 = isinstance(mfd1, ManifoldHP)
+    high2 = isinstance(mfd2, ManifoldHP)
+    if high1 and not high2:
+        resolved_mfd2 = ManifoldHP(mfd2)
+    if high2 and not high1:
+        resolved_mfd1 = ManifoldHP(mfd1)
+    return (resolved_mfd1, resolved_mfd2)
+
+def _symmetrize_low_precision_triangulation(
+        tri1 : Union[Triangulation, TriangulationHP],
+        tri2 : Union[Triangulation, TriangulationHP]
+              ) -> Union[Tuple[Triangulation, Triangulation],
+                         Tuple[TriangulationHP, TriangulationHP]]:
+    """
+    Given a (potential) mix of two Triangulation and TriangulationHP,
+    demote one to low precision if necessary and return
+    the result as pair.
+    """
+    resolved_tri1 = tri1
+    resolved_tri2 = tri2
+    low1 = isinstance(tri1, Triangulation)
+    low2 = isinstance(tri2, Triangulation)
+    if low1 and not low2:
+        resolved_tri2 = Triangulation(tri2, remove_finite_vertices=False)
+    if low2 and not low1:
+        resolved_tri1 = Triangulation(tri1, remove_finite_vertices=False)
+    return (resolved_tri1, resolved_tri2)
+
+def is_isometric_to(self,
+                    other : Union[Manifold, ManifoldHP],
+                    return_isometries : bool = False
+                    ) -> Union[bool, List[Isometry]]:
+    resolved_self, resolved_other = (
+        _symmetrize_high_precision_manifold(
+            self, other))
+
+    return resolved_self._is_isometric_to(
+        resolved_other,
+        return_isometries=return_isometries)
+
+is_isometric_to.__doc__ = _ManifoldLP._is_isometric_to.__doc__
+Manifold.is_isometric_to = is_isometric_to
+ManifoldHP.is_isometric_to = is_isometric_to
+
+def isomorphisms_to(self,
+                    other : Union[Triangulation, TriangulationHP]
+                    ) -> List[Isometry]:
+    resolved_self, resolved_other = (
+        _symmetrize_low_precision_triangulation(
+            self, other))
+
+    return resolved_self._isomorphisms_to(
+        resolved_other)
+
+isomorphisms_to.__doc__ = _TriangulationLP._isomorphisms_to.__doc__
+Triangulation.isomorphisms_to = isomorphisms_to
+TriangulationHP.isomorphisms_to = isomorphisms_to
 
 from . import snap
 snap.add_methods(Manifold)
 snap.add_methods(ManifoldHP)
 snap.add_methods(Triangulation, hyperbolic=False)
+snap.add_methods(TriangulationHP, hyperbolic=False)
+
+from . import exterior_to_link
+Triangulation.exterior_to_link = exterior_to_link.exterior_to_link
+TriangulationHP.exterior_to_link = exterior_to_link.exterior_to_link
+Manifold.exterior_to_link = exterior_to_link.exterior_to_link
+ManifoldHP.exterior_to_link = exterior_to_link.exterior_to_link
 
 from . import verify
 Manifold.verify_hyperbolicity = verify.verify_hyperbolicity
 ManifoldHP.verify_hyperbolicity = verify.verify_hyperbolicity
 
-def canonical_retriangulation(
-    manifold, verified = False,
-    interval_bits_precs = verify.default_interval_bits_precs,
-    exact_bits_prec_and_degrees = verify.default_exact_bits_prec_and_degrees,
-    verbose = False):
+from . import len_spec
+Manifold.length_spectrum_alt_gen = len_spec.length_spectrum_alt_gen
+ManifoldHP.length_spectrum_alt_gen = len_spec.length_spectrum_alt_gen
+Manifold.length_spectrum_alt = len_spec.length_spectrum_alt
+ManifoldHP.length_spectrum_alt = len_spec.length_spectrum_alt
 
-    """
-    The canonical retriangulation which is closely related to the canonical
-    cell decomposition and described in more detail `here 
-    <verify.html#the-canonical-retriangulation-and-the-isometry-signature>`_::
-
-       >>> M = Manifold("m412")
-       >>> K = M.canonical_retriangulation()
-       >>> len(K.isomorphisms_to(K)) # Unverified size of the isometry group.
-       8
-
-    When used inside `Sage <http://sagemath.org/>`_ and ``verified = True`` is
-    passed as argument, the verify module will certify the result to be
-    correct::
-
-      sage: M = Manifold("m412")
-      sage: K = M.canonical_retriangulation(verified = True)
-      sage: len(K.isomorphisms_to(K)) # Verified size of the isometry group.
-      8
-   
-    See :py:meth:`verify.verified_canonical_retriangulation` for the
-    additional options.
-    """
-    if False in manifold.cusp_info('complete?'):
-        raise ValueError('Canonical retriangulation needs all cusps to be complete')
-
-    if verified:
-        return verify.verified_canonical_retriangulation(
-            manifold,
-            interval_bits_precs = interval_bits_precs,
-            exact_bits_prec_and_degrees = exact_bits_prec_and_degrees,
-            verbose = verbose)
-    else:
-        return manifold._canonical_retriangulation()
-    
-Manifold.canonical_retriangulation = canonical_retriangulation
-ManifoldHP.canonical_retriangulation = canonical_retriangulation
+from . import canonical
+Manifold.canonical_retriangulation = canonical.canonical_retriangulation
+ManifoldHP.canonical_retriangulation = canonical.canonical_retriangulation_hp
 
-def isometry_signature(
-    manifold, of_link = False, verified = False,
-    interval_bits_precs = verify.default_interval_bits_precs,
-    exact_bits_prec_and_degrees = verify.default_exact_bits_prec_and_degrees,
-    verbose = False):
+from . import isometry_signature
 
-    """
-    The isomorphism signature of the canonical retriangulation. This is a
-    complete invariant of the isometry type of a hyperbolic 3-manifold and
-    described in more detail `here 
-    <verify.html#the-canonical-retriangulation-and-the-isometry-signature>`_::
-
-        >>> M = Manifold("m125")
-        >>> M.isometry_signature() # Unverified isometry signature
-        'gLLPQccdefffqffqqof'
-
-    When used inside `Sage <http://sagemath.org/>`_ and ``verified = True`` is
-    passed as argument, the verify module will certify the result to be
-    correct::
-
-        sage: M = Manifold("m125")
-        sage: M.isometry_signature(verified = True) # Verified isometry signature
-        'gLLPQccdefffqffqqof'
-
-    When ``of_link = True`` is specified, the peripheral curves are included in
-    such a way that the result is a complete invariant of a link. In particular,
-    ``isometry_signature(of_link=True)`` is invariant under changing the
-    ordering or orientations of the components or flipping all crossings of a
-    link simultaneously (it passes ``ignore_cusp_order = True,
-    ignore_curve_orientations = True`` to
-    :py:meth:`Manifold.triangulation_isosig`)::
-
-        >>> Manifold("5^2_1").isometry_signature(of_link = True)
-        'eLPkbdcddhgggb_baCbbaCb'
-        >>> Manifold("7^2_8").isometry_signature(of_link = True)
-        'eLPkbdcddhgggb_bBcBbaCb'
-
-    See :py:meth:`verify.verified_canonical_retriangulation` for the
-    additional options.
-
-    Note that interval methods cannot verify a canonical retriangulation
-    with non-tetrahedral cells such as in the cas of ``m412``, so the following
-    call returns ``None``::
-
-        sage: M = Manifold("m412")
-        sage: M.isometry_signature(verified = True, exact_bits_prec_and_degrees = None)
+Manifold.isometry_signature = isometry_signature.isometry_signature
+ManifoldHP.isometry_signature = isometry_signature.isometry_signature
 
-    """
-    if False in manifold.cusp_info('complete?'):
-        raise ValueError('isometry_signature needs all cusps to be complete')
+from .cusps import cusp_area_matrix
 
-    retrig = manifold.canonical_retriangulation(
-         verified = verified,
-         interval_bits_precs = interval_bits_precs,
-         exact_bits_prec_and_degrees = exact_bits_prec_and_degrees,
-         verbose = verbose)
+Manifold.cusp_area_matrix = cusp_area_matrix.cusp_area_matrix
+ManifoldHP.cusp_area_matrix = cusp_area_matrix.cusp_area_matrix
 
-    if not retrig:
-        return None
-    
-    return retrig.triangulation_isosig(decorated = of_link,
-                                       ignore_cusp_ordering = True,
-                                       ignore_curve_orientations = True)
-
-Manifold.isometry_signature = isometry_signature
-ManifoldHP.isometry_signature = isometry_signature
-
-
-def cusp_area_matrix(manifold, method='trigDependentTryCanonize',
-                     verified=False, bits_prec=None):
-    r"""
-    This function returns a matrix that can be used to check whether
-    cusp neighborhoods of areas a\ :sub:`0`\ , ..., a\ :sub:`m-1` are
-    disjoint: the cusp neighborhoods about cusp i and j are
-    disjoint (respectively, the cusp neighborhood embeds if i and j
-    are equal) if a\ :sub:`i` * a\ :sub:`j` is less than or equal to
-    the entry (i,j) of the cusp area matrix. Note that the "if"
-    becomes "if and only if" if we pick the "maximal cusp area
-    matrix".
-
-    This function can operate in different ways (determined by
-    ``method``). By default (``method='trigDependentTryCanonize'``),
-    it returns a result which can be suboptimal and non-deterministic
-    but is quicker to compute and sufficies for many applications::
-
-        >>> M = Manifold("s776")
-        >>> M.cusp_area_matrix() # doctest: +NUMERIC12
-        [28.0000000000000 7.00000000000000 6.99999999999999]
-        [7.00000000000000 21.4375000000000 7.00000000000000]
-        [6.99999999999999 7.00000000000000 21.4375000000000]
-
-    If ``method='maximal'`` is specified, the result is the "maximal
-    cusp area matrix", thus it is optimal and an invariant of the
-    manifold with labeled cusps. Note that the "maximal cusp area
-    matrix" is only available as verified computation and thus
-    requires passing ``verified = True``::
-
-        sage: M.cusp_area_matrix(method = 'maximal', verified=True) # doctest: +NUMERIC6
-        [28.0000000000?  7.0000000000?  7.0000000000?]
-        [ 7.0000000000?  28.000000000? 7.00000000000?]
-        [ 7.0000000000? 7.00000000000?   28.00000000?]
-
-    If ``verified = True`` is specified and ``method`` is not
-    ``maximal``, the entries are all guaranteed to be less than the
-    corresponding ones in the maximal cusp area matrix (more
-    precisely, the lower end point of the interval is guaranteed to be
-    less than the true value of the corresponding maximal cusp area
-    matrix entry)::
-
-        sage: M.cusp_area_matrix(verified=True, bits_prec=70) # doctest: +NUMERIC15
-        [ 28.000000000000000?  7.0000000000000000?  7.0000000000000000?]
-        [ 7.0000000000000000? 21.4375000000000000?  7.0000000000000000?]
-        [ 7.0000000000000000?  7.0000000000000000? 21.4375000000000000?]
-
-    For expert users:
-
-    Besides the two values above, ``method`` can be ``trigDependent``:
-    this result is also fast to compute by making the assumption that
-    cusp neighborhoods are not only disjoint but also in "standard
-    form" with respect to the triangulation (i.e., when lifting of a
-    cusp neighborhood to a horoball in the universal cover, it
-    intersects a geodesic tetrahedron in three but not four
-    faces). ``trigDependentTryCanonize`` is similar to
-    ``trigDependent`` but tries to "proto-canonize" (a copy of) the
-    triangulation first since this often produces a matrix that is
-    closer to the maximal cusp area matrix, for example::
-
-        >>> M = Manifold("o9_35953")
-        >>> M.cusp_area_matrix(method = 'trigDependent') # doctest: +NUMERIC9
-        [72.9848715318467 12.7560424258060]
-        [12.7560424258060 6.65567118002656]
-        >>> M.cusp_area_matrix(method = 'trigDependentTryCanonize') # doctest: +NUMERIC9
-        [72.9848715318466 12.7560424258060]
-        [12.7560424258060 62.1043047674605]
-
-    Compare to maximal area matrix::
-
-        sage: M.cusp_area_matrix(method = 'maximal', verified = True, bits_prec = 100) # doctest: +NUMERIC15
-        [       72.984871531846664? 12.7560424258059765562778?]
-        [12.7560424258059765562778?     62.104304767460978078?]
+from .cusps import cusp_areas_from_matrix
 
+def cusp_areas(manifold,
+               policy : str = 'unbiased',
+               method : str = 'maximal',
+               verified : bool = False,
+               bits_prec : Optional[int] = None,
+               first_cusps : List[int] = []):
     """
+    Returns a list of areas, one for each cusp. The cusp neighborhoods
+    defined by these areas are embedded and disjoint. Furthermore, these
+    neighborhoods are maximal in that they fail to be embedded or
+    disjoint if any cusp neighborhood is enlarged (unless :attr:`method`
+    is set to a value different from the default).
 
-    if method == 'maximal':
-        if not verified:
-            raise NotImplementedError("Maximal cusp area matrix only "
-                                      "available as verified computation. "
-                                      "Pass verified = True.")
-        return verify.verified_maximal_cusp_area_matrix(
-            manifold, bits_prec = bits_prec)
-    if method in ['trigDependent', 'trigDependentTryCanonize']:
-        if method == 'trigDependentTryCanonize':
-            manifold = manifold.copy()
-            manifold.canonize()
+    There are different policies how these cusp neighborhoods are found.
 
-        return verify.triangulation_dependent_cusp_area_matrix(
-            manifold, verified = verified, bits_prec = bits_prec)
-
-    raise RuntimeError("method passed to cusp_area_matrix must be "
-                       "'trigDependent', 'trigDependentTryCanonize', "
-                       "or 'maximal'.")
-
-Manifold.cusp_area_matrix = cusp_area_matrix
-ManifoldHP.cusp_area_matrix = cusp_area_matrix
-
-from .verify import cusp_areas as verify_cusp_areas
-
-def cusp_areas(manifold, policy = 'unbiased',
-               method = 'trigDependentTryCanonize',
-               verified = False, bits_prec = None, first_cusps=[]):
-
-    """
-    Picks areas for the cusps such that the corresponding cusp
-    neighborhoods are disjoint. By default, the ``policy`` is
-    ``unbiased`` which means that the cusp neighborhoods are blown up
-    simultaneously with a cusp neighborhood stopping to grow when it
-    touches another cusp neighborhood or itself::
+    The default :attr:`policy` is ``unbiased``. This means that the
+    cusp neighborhoods are blown up simultaneously and a cusp neighborhood
+    stops growing when it touches any cusp neighborhood including itself::
 
         >>> M = Manifold("s776")
         >>> M.cusp_areas() # doctest: +NUMERIC9
         [2.64575131106459, 2.64575131106459, 2.64575131106459]
 
-    Alternatively, ``policy='greedy'`` means that the first cusp
-    neighborhood is blown up until it touches itself, then the second
-    cusp neighborhood is blown up until it touches itself or the first
-    cusp neighborhood, ...::
+    Alternatively, :attr:`policy='greedy'` can be specified. This means
+    that the first cusp neighborhood is blown up until it touches itself,
+    then the second cusp neighborhood is blown up until it touches itself
+    or the first cusp neighborhood, and so on::
 
         >>> M.cusp_areas(policy='greedy') # doctest: +NUMERIC9
         [5.29150262212918, 1.32287565553230, 1.32287565553229]
 
-    To specify cusps to be blown up first, and in which order to blow
-    them up, set ``first_cusps`` to the appropriate list of cusps.
+    Use :attr:`first_cusps` to specify the order in which the cusp
+    neighborhoods are blown up::
 
-        >>> M = Manifold('o9_44210')
-        >>> M.cusp_areas(policy='greedy') # doctest: +NUMERIC9
-        [7.053940530873898, 3.2712450270, 2.7091590087]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[]) # doctest: +NUMERIC9
-        [7.053940530873898, 3.2712450270, 2.7091590087]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[0,]) # doctest: +NUMERIC9
-        [7.053940530873898, 3.2712450270, 2.7091590087]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[0,1]) # doctest: +NUMERIC9
-        [7.053940530873898, 3.2712450270, 2.7091590087]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[0,1,2]) # doctest: +NUMERIC9
-        [7.053940530873898, 3.2712450270, 2.7091590087]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[0,2,1]) # doctest: +NUMERIC9
-        [7.053940530873898, 2.3513135103, 3.7690945490]
-        >>> M.cusp_areas(policy='greedy', first_cusps=[1,]) # doctest: +NUMERIC9
-        [4.0302253322, 5.725527974287718, 1.5478612583]
-    
-    ``cusp_areas`` is implemented using
-    :py:meth:`Manifold.cusp_area_matrix` and the same arguments
-    (``method``, ``verified``, ``bits_prec``) are accepted. For
-    example, verified computations are supported::
+        >>> M.cusp_areas(policy='greedy', first_cusps=[1,0,2]) # doctest: +NUMERIC9
+        [1.32287565553230, 5.29150262212918, 1.32287565553229]
 
-        sage: M=Manifold("v2854")
-        sage: M.cusp_areas(verified=True) # doctest: +NUMERIC9
-        [3.6005032476?, 3.6005032476?]
+    An incomplete list can be given to :attr:`first_cusps`. In this case,
+    the list is automatically completed by appending the remaining cusps in
+    order. Thus, the above call is equivalent to::
 
-    If ``method='maximal'``, ``policy='unbiased'`` and
-    ``verified=True``, the result is an invariant of the manifold with
-    labeled cusps and the corresponding cusp neighborhoods are maximal
-    in that every cusp neighborhood is touching some (not necessarily
-    distinct) cusp neighborhood.
+        >>> M.cusp_areas(policy='greedy', first_cusps=[1]) # doctest: +NUMERIC9
+        [1.32287565553230, 5.29150262212918, 1.32287565553229]
 
-    Area of the cusp neighborhood touching itself for a one-cusped
-    manifold::
+    Under the hood, this method is using
+    :meth:`~snappy.Manifold.cusp_area_matrix`.
 
-        sage: M=Manifold("v1959")
-        sage: M.cusp_areas(method='maximal', verified=True, bits_prec=100) # doctest: +NUMERIC15
-        [7.15679216175810579?]
+    **Verified computation**
 
+    If :attr:`verified = False`, floating-point issues can arise resulting in
+    incorrect values. The method can be made
+    :ref:`verified <verify-primer>` by passing :attr:`verified = True`::
+
+        sage: M=Manifold("s776")
+        sage: M.cusp_areas(verified=True) # doctest: +NUMERIC9
+        [2.64575131107?, 2.64575131107?, 2.64575131107?]
+    
+    :param verified:
+            Use :ref:`verified computation <verify-primer>`.
+    :param bits_prec:
+            Precision used for computation. Increase if computation
+            did not succeed or a more precise result is desired.
+    :param method:
+            Passed to :meth:`~snappy.Manifold.cusp_area_matrix`. If set
+            to a value different from the default ``maximal``, the cusp
+            neighborhoods stop growing when the corresponding value
+            in the computed cusp area matrix is exceeded. At this point,
+            the cusp neighborhood might not necessarily touch any other
+            cusp neighborhood since we do not use the maximal cusp area
+            matrix.
+    :param policy:
+            Specifies process of choosing cusp neighborhoods.
+            Either ``unbiased`` or ``greedy``, see above.
+    :param first_cusps:
+            Preference order of cusps.
+            Only relevant if :attr:`policy='greedy'`, see above.
+    :return:
+            Areas of maximal embedded and disjoint cusp neighborhoods
+            (default). Or areas of some embedded and disjoint cusp
+            neighborhoods (if :attr:`method` switches to older algorithm).
     """
     if policy not in ['unbiased', 'greedy']:
-        raise RuntimeError("policy passed to cusp_areas must be 'unbiased' "
+        raise ValueError("policy passed to cusp_areas must be 'unbiased' "
                            "or 'greedy'.")
 
     m = manifold.cusp_area_matrix(
         method=method, verified=verified, bits_prec=bits_prec)
 
     if policy == 'unbiased':
-        return verify_cusp_areas.unbiased_cusp_areas_from_cusp_area_matrix(m)
+        return cusp_areas_from_matrix.unbiased_cusp_areas_from_cusp_area_matrix(m)
     else:
-        return verify_cusp_areas.greedy_cusp_areas_from_cusp_area_matrix(m, first_cusps=first_cusps)
+        return cusp_areas_from_matrix.greedy_cusp_areas_from_cusp_area_matrix(m, first_cusps=first_cusps)
 
 Manifold.cusp_areas = cusp_areas
 ManifoldHP.cusp_areas = cusp_areas
 
 from .verify import short_slopes as verify_short_slopes
 
+
 def short_slopes(manifold,
-                 length = 6,
-                 policy = 'unbiased', method = 'trigDependentTryCanonize',
-                 verified = False, bits_prec = None, first_cusps=[]):
+                 length=6,
+                 policy : str = 'unbiased',
+                 method : str = 'maximal',
+                 verified : bool = False,
+                 bits_prec : Optional[int] = None,
+                 first_cusps : List[int] = []):
     """
-    Picks disjoint cusp neighborhoods (using
-    :py:meth:`Manifold.cusp_areas`, thus the same arguments can be
-    used) and returns for each cusp the slopes that have length less
-    or equal to given ``length`` (defaults to 6) when measured on the
-    boundary of the cusp neighborhood::
+    Returns a list of short slopes (for Dehn-fillings) for each cusp.
+
+    That is, the method uses :meth:`~snappy.Manifold.cusp_areas` to find
+    (maximal) embedded and disjoint cusp neighborhoods. It uses the boundaries
+    of these cusp neighborhoods to measure the length of a peripheral curve.
+    For each cusp, it determines all simple peripheral curves shorter than
+    the given :attr:`length` (which defaults to 6). The result is a list
+    of the corresponding slopes for each cusp::
 
         >>> M = Manifold("otet20_00022")
         >>> M.short_slopes()
         [[(1, 0), (-1, 1), (0, 1)], [(1, 0)]]
-    
-    When ``verified=True``, the result is guaranteed
-    to contain all slopes of length less or equal to given ``length``
-    (and could contain additional slopes if precision is not high
-    enough)::
 
-        sage: M.short_slopes(verified = True)
-        [[(1, 0), (-1, 1), (0, 1)], [(1, 0)]]
-    
+    It takes the same arguments as :meth:`~snappy.Manifold.cusp_areas`::
+
+        >>> M.short_slopes(policy = 'greedy')
+        [[(1, 0)], [(1, 0)]]
+
     The ten exceptional slopes of the figure-eight knot::
 
         >>> M = Manifold("4_1")
         >>> M.short_slopes()
         [[(1, 0), (-4, 1), (-3, 1), (-2, 1), (-1, 1), (0, 1), (1, 1), (2, 1), (3, 1), (4, 1)]]
 
-    Two more slopes appear when increasing length to 2 pi::
-        
+    Two more slopes appear when increasing length to :math:`2\\pi`::
+
         >>> M.short_slopes(length = 6.283185307179586)
         [[(1, 0), (-5, 1), (-4, 1), (-3, 1), (-2, 1), (-1, 1), (0, 1), (1, 1), (2, 1), (3, 1), (4, 1), (5, 1)]]
 
-    When using verified computations, ``length`` is converted into the ``RealIntervalField`` of requested precision::
+    **Verified computation**
+
+    If :attr:`verified = False`, floating-point issues can arise resulting in
+    incorrect values. The method can be made
+    :ref:`verified <verify-primer>` by passing :attr:`verified = True`::
+
+        sage: M = Manifold("4_1")
+        sage: M.short_slopes(verified = True)
+        [[(1, 0), (-4, 1), (-3, 1), (-2, 1), (-1, 1), (0, 1), (1, 1), (2, 1), (3, 1), (4, 1)]]
+
+    If :attr:`verified = True`, the result is guaranteed to contain all short
+    slopes and might contain additional slopes (with lengths slightly longer
+    than the given :attr:`length` but this could not be proven using the
+    interval estimates).
+
+    The given :attr:`length` is cast to a SageMath ``RealIntervalField`` of the
+    given precision if :attr:`verified = True`::
 
         sage: from sage.all import pi
-        sage: M.short_slopes(length = 2 * pi, verified = True, bits_prec = 100) 
+        sage: M.short_slopes(length = 2 * pi, verified = True, bits_prec = 100)
         [[(1, 0), (-5, 1), (-4, 1), (-3, 1), (-2, 1), (-1, 1), (0, 1), (1, 1), (2, 1), (3, 1), (4, 1), (5, 1)]]
 
     """
 
     return [
         verify_short_slopes.short_slopes_from_cusp_shape_and_area(
-            shape, area, length = length)
+            shape, area, length=length)
         for shape, area
         in zip(manifold.cusp_info(
-                'shape', verified = verified, bits_prec = bits_prec),
+                'shape', verified=verified, bits_prec=bits_prec),
                manifold.cusp_areas(
-                policy = policy, method = method,
-                   verified = verified, bits_prec = bits_prec, first_cusps=first_cusps)) ]
+                policy=policy, method=method,
+                   verified=verified, bits_prec=bits_prec, first_cusps=first_cusps)) ]
+
 
 Manifold.short_slopes = short_slopes
 ManifoldHP.short_slopes = short_slopes
 
-def cusp_translations(manifold, policy = 'unbiased',
-                      method = 'trigDependentTryCanonize',
-                      verified = False, bits_prec = None, first_cusps=[]):
+
+def cusp_translations(manifold,
+                      policy : str = 'unbiased',
+                      method : str = 'maximal',
+                      verified : bool = False,
+                      bits_prec : Optional[int] = None,
+                      first_cusps : List[int] = []):
     """
-    Picks disjoint cusp neighborhoods and returns the respective
-    (complex) Euclidean translations of the meridian and longitude for
-    each cusp. The method takes the same arguments as
-    :py:meth:`Manifold.cusp_areas` and uses that method to pick the
-    cusp neighborhood. The result is a list of pairs, the second entry
-    corresponding to a longitude is always real::
+    Returns a list of the (complex) Euclidean translations corresponding to the
+    meridian and longitude of each cusp.
+
+    That is, the method uses :meth:`~snappy.Manifold.cusp_areas` to find
+    (maximal) embedded and disjoint cusp neighborhoods. It then uses the
+    boundaries of these cusp neighborhoods to measure the meridian and
+    longitude of each cusp. The result is a pair for each cusp. The first
+    entry of the pair corresponds to the meridian and is complex. The
+    second entry corresponds to the longitude and is always real::
 
         >>> M = Manifold("s776")
         >>> M.cusp_translations() # doctest: +NUMERIC9
         [(0.500000000000000 + 1.32287565553230*I, 2.00000000000000), (0.500000000000000 + 1.32287565553230*I, 2.00000000000000), (0.499999999999999 + 1.32287565553230*I, 2.00000000000000)]
 
-    Arguments such as ``policy='greedy'`` are interpreted the same way as
-    for :py:meth:`Manifold.cusp_areas`::
+    It takes the same arguments as :meth:`~snappy.Manifold.cusp_areas`::
 
-        >>> M.cusp_translations(policy = 'greedy', first_cusps = [], bits_prec = 100) # doctest: +NUMERIC21
+        >>> M.cusp_translations(policy = 'greedy') # doctest: +NUMERIC9
         [(0.70710678118654752440084436210 + 1.8708286933869706927918743662*I, 2.8284271247461900976033774484), (0.35355339059327376220042218105 + 0.93541434669348534639593718308*I, 1.4142135623730950488016887242), (0.35355339059327376220042218105 + 0.93541434669348534639593718308*I, 1.4142135623730950488016887242)]
 
-    and can return verified intervals::
-
-        sage: M.cusp_translations(method = 'maximal', verified = True) # doctest: +NUMERIC9
-        [(0.50000000000? + 1.32287565553?*I, 2.00000000000?), (0.500000000000? + 1.32287565554?*I, 2.00000000000?), (0.500000000000? + 1.32287565554?*I, 2.00000000000?)]
+    **Verified computations**
 
-    that are guaranteed to contain the true translations of cusp neighborhoods
-    verified to be disjoint (the element corresponding to a longitude
-    is always in a ``RealIntervalField``).
+    If :attr:`verified = False`, floating-point issues can arise resulting in
+    incorrect values. The method can be made
+    :ref:`verified <verify-primer>` by passing :attr:`verified = True`::
 
-    **Remark:** The default ``method = 'trigDependentTryCanonize'`` is
-    (potentially) non-deterministic and thus the result of
-    
-        [ M.cusp_translations()[i] for i in range(M.num_cusps()) ]
+        sage: M.cusp_translations(verified = True) # doctest: +NUMERIC9
+        [(0.50000000000? + 1.32287565553?*I, 2.00000000000?), (0.500000000000? + 1.32287565554?*I, 2.00000000000?), (0.500000000000? + 1.32287565554?*I, 2.00000000000?)]
 
-    might not correspond to disjoint cusp neighborhoods.
+    Note that the first element of each pair is a SageMath ``ComplexIntervalField`` and
+    the second element a ``RealIntervalField``.
     """
 
     return [
         verify_short_slopes.translations_from_cusp_shape_and_area(
-            shape, area, kernel_convention = True)
+            shape, area, kernel_convention=True)
         for shape, area
         in zip(manifold.cusp_info(
-                'shape', verified = verified, bits_prec = bits_prec),
+                'shape', verified=verified, bits_prec=bits_prec),
                manifold.cusp_areas(
-                policy = policy, method = method,
-                   verified = verified, bits_prec = bits_prec, first_cusps=first_cusps)) ]
+                policy=policy, method=method,
+                   verified=verified, bits_prec=bits_prec, first_cusps=first_cusps)) ]
+
 
 Manifold.cusp_translations = cusp_translations
 ManifoldHP.cusp_translations = cusp_translations
 
-def complex_volume(manifold, verified_modulo_2_torsion = False,
-                   bits_prec = None):
+
+def complex_volume(manifold, verified_modulo_2_torsion=False,
+                   bits_prec=None):
     """
-    Returns the complex volume, i.e.
-    volume + i 2 pi^2 (chern simons)
-    
-    >>> M = Manifold('5_2')
-    >>> M.complex_volume() # doctest: +NUMERIC6
-    2.82812209 - 3.02412838*I
-    >>> c = M.chern_simons()
-    >>> M.dehn_fill((1,2))
-    >>> M.complex_volume() # doctest: +NUMERIC6
-    2.22671790 + 1.52619361*I
-    >>> M = Manifold("3_1")
-    >>> cvol = M.complex_volume()
-    >>> cvol.real() # doctest: +NUMERIC6
-    0
-    >>> cvol.imag() # doctest: +NUMERIC6
-    -1.64493407
+    Returns the complex volume modulo :math:`i \\pi^2` which is given by
+
+    .. math::
+        \\text{vol} + i \\text{CS}
+
+    where :math:`\\text{CS}` is the (unnormalized) Chern-Simons invariant.
+
+        >>> M = Manifold('5_2')
+        >>> M.complex_volume() # doctest: +NUMERIC6
+        2.82812209 - 3.02412838*I
+
+    Note that :meth:`chern_simons <snappy.Manifold.chern_simons>`
+    normalizes the Chern-Simons invariant by dividing it by
+    :math:`2 \\pi^2 = 19.7392...` ::
+
+        >>> M.chern_simons() # doctest: +NUMERIC6
+        -0.153204133297152
+
+    More examples::
+
+        >>> M.dehn_fill((1,2))
+        >>> M.complex_volume() # doctest: +NUMERIC6
+        2.22671790 + 1.52619361*I
+        >>> M = Manifold("3_1") # A non-hyperbolic example.
+        >>> cvol = M.complex_volume()
+        >>> cvol.real() # doctest: +NUMERIC6
+        0
+        >>> cvol.imag() # doctest: +NUMERIC6
+        -1.64493407
 
     If no cusp is filled or there is only one cusped (filled or
     unfilled), the complex volume can be verified up to multiples
-    of i pi^2 / 2 by passing `verified_modulo_2_torsion = True`
-    when inside SageMath (and higher precision can be requested
-    with `bits_prec`)::
+    of :math:`i \\pi^2 /2` by passing ``verified_modulo_2_torsion = True``
+    when inside SageMath. Higher precision can be requested
+    with ``bits_prec``::
 
         sage: M = Manifold("m015")
-        sage: M.complex_volume(verified_modulo_2_torsion=True, bits_prec = 90) # doctest: +NUMERIC24
+        sage: M.complex_volume(verified_modulo_2_torsion=True, bits_prec = 93) # doctest: +NUMERIC21
         2.828122088330783162764? + 1.910673824035377649698?*I
         sage: M = Manifold("m015(3,4)")
         sage: M.complex_volume(verified_modulo_2_torsion=True) # doctest: +NUMERIC6
@@ -567,76 +559,29 @@ def complex_volume(manifold, verified_modulo_2_torsion = False,
     """
     if verified_modulo_2_torsion:
         return verify.verified_complex_volume_torsion(
-            manifold, bits_prec = bits_prec)
+            manifold, bits_prec=bits_prec)
 
     if bits_prec:
         raise Exception("Arbitrary precision for complex volume only "
                         "supported for verified computations and cusped "
                         "manifolds.")
-    
+
     return manifold._complex_volume()
 
 Manifold.complex_volume = complex_volume
 ManifoldHP.complex_volume = complex_volume
 
-try:
-    from .gui import ViewerWindow
-    from .raytracing.inside_viewer import InsideViewer
-    from .raytracing.inside_viewer import NonorientableUnsupportedError
-    from .raytracing import cohomology_fractal
-except ImportError as e:
-    InsideViewer = None
-    _importErrorRaytracing = str(e)
-
-def manifold_inside_view(self, cohomology_class = None):
-    """
-    Show raytraced inside view of hyperbolic manifold:
-
-        >>> M = Manifold("m004")
-        >>> M.inside_view() #doctest: +CYMODERNOPENGL
-
-    Or show the cohomology fractal:
-
-        >>> M = Manifold("m004")
-        >>> M.inside_view(cohomology_class = 0) #doctest: +CYMODERNOPENGL
-
-    The cohomology class in H^2(M, bd M; R) producing the cohomology
-    fractal can be specified as a cocycle or using an automatically computed
-    basis (of, say, length ``n``). Thus, ``cohomology_class`` can be one of
-    the following.
-
-    - An integer ``i`` between 0 and ``n`` - 1 to pick the ``i``-th basis
-      vector.
-    - An array of length ``n`` specifying the cohomology class as linear
-      combination of basis vectors.
-    - A weight for each face of each tetrahedron.
-
-    """
-    
-    if InsideViewer is None:
-        raise RuntimeError("Raytraced inside view not imported; "
-        "Tk or CyOpenGL is probably missing "
-        "(original error : %s)" % _importErrorRaytracing)
-    
-    if not self.is_orientable():
-        raise NonorientableUnsupportedError(self)
+from . import drilling
+drilling._add_methods(Manifold)
+drilling._add_methods(ManifoldHP, high_precision=True)
 
-    weights, cohomology_basis, cohomology_class = (
-        cohomology_fractal.compute_weights_basis_class(
-            self, cohomology_class))
+from . import raytracing
 
-    return ViewerWindow(
-        InsideViewer,
-        self,
-        title = "Inside view of %s" % self.name(),
-        weights = weights,
-        cohomology_basis = cohomology_basis,
-        cohomology_class = cohomology_class)
+Manifold.inside_view = raytracing.inside_view
+ManifoldHP.inside_view = raytracing.inside_view
 
-Manifold.inside_view = manifold_inside_view
-ManifoldHP.inside_view = manifold_inside_view
 
-def all_translations(self, verified = False, bits_prec = None):
+def all_translations(self, verified=False, bits_prec=None):
     """
     Returns the (complex) Euclidean translations of the meridian
     and longitude for each cusp measured with respect to the cusp neighborhood.
@@ -656,10 +601,10 @@ def all_translations(self, verified = False, bits_prec = None):
         >>> N.set_displacement(100,2)
         >>> N.all_translations() # doctest: +NUMERIC9
         [(-0.477656250512815 + 2.33461303362557*I, 2.71240613125259), (-0.259696455247511 + 1.26930345526993*I, 1.47470541152065), (0.131389112265699 + 0.991330873713731*I, 1.22318540718077)]
-        
+
     This can also be achieved by :py:meth:`Manifold.cusp_translations` which
     would have made a different choice of disjoint cusp neighborhoods though::
-        
+
         >>> M.cusp_translations() # doctest: +NUMERIC6
         [(-0.315973594129651 + 1.54436599614183*I, 1.79427928161946), (-0.315973594129649 + 1.54436599614182*I, 1.79427928161946), (0.198620491993677 + 1.49859164484929*I, 1.84908538602825)]
 
@@ -691,16 +636,17 @@ def all_translations(self, verified = False, bits_prec = None):
 
     is not verified to correspond to disjoint cusp neighborhoods.
     """
-        
+
     if verified or bits_prec:
-        # Use the implementation in verify.cuspTranslations that uses
+        # Use the implementation in verify.cusp_translations that uses
         # tetrahedra_shapes and ComplexCuspNeighborhood
         return verify.cusp_translations_for_neighborhood(
-            self, verified = verified, bits_prec = bits_prec)
+            self, verified=verified, bits_prec=bits_prec)
 
     # Use the implementation in the SnapPea kernel
     return [ self.translations(i) for i in range(self.num_cusps()) ]
 
+
 CuspNeighborhood.all_translations = all_translations
 CuspNeighborhoodHP.all_translations = all_translations
 
@@ -711,6 +657,7 @@ from . import twister
 
 from . import database
 database.Manifold = Manifold
+database.Triangulation = Triangulation
 snappy_module = sys.modules[__name__]
 database_objects = []
 known_manifold_packages = [('snappy_manifolds', True),
@@ -730,11 +677,12 @@ __all__ += database_objects
 
 from spherogram.codecs import DTcodec
 
+
 def _link_exterior(self, with_hyperbolic_structure=True,
                    remove_finite_vertices=True):
     """
     The exterior or complement of the link L, that is, S^3 minus L.
-    
+
     >>> K = Link('4_1')
     >>> M = K.exterior()
     >>> M.volume() # doctest: +NUMERIC6
@@ -749,7 +697,7 @@ def _link_exterior(self, with_hyperbolic_structure=True,
     >>> M = K.exterior(False, False)
     >>> (M.num_cusps(), M._num_fake_cusps())
     (1, 2)
-    
+
     """
     M = Triangulation('empty')
     M._get_from_link_data(self.KLPProjection(), remove_finite_vertices)
@@ -761,6 +709,7 @@ def _link_exterior(self, with_hyperbolic_structure=True,
         M.set_name(self.name)
     return M
 
+
 link_objects = []
 
 from spherogram.links import (Crossing, Strand, Link, Tangle,
@@ -787,27 +736,25 @@ for mfld_class in [Triangulation, Manifold, ManifoldHP]:
                    'normal_boundary_slopes']:
         setattr(mfld_class, method, getattr(_spun, method))
 
+import textwrap
+
 #   Documentation for the module:
-SnapPy_doc = """
+__doc__ = """
 SnapPy is a Cython wrapping of Jeff Weeks' SnapPea kernel.
 
 The module defines the following classes:
-  Triangulation, Manifold,
-  AbelianGroup, FundamentalGroup, HolonomyGroup,
-  DirichletDomain, CuspNeighborhood, SymmetryGroup,
-  OrientableCuspedCensus, NonorientableCuspedCensus,
-  OrientableClosedCensus, NonorientableClosedCensus,
-  AlternatingKnotExteriors, NonalternatingKnotExteriors,
-  SnapPeaFatalError, pari, twister,
-  %s
-  %s.
-
-"""%(', '.join(database_objects), ', '.join(link_objects))
-
-# Add easy way to get the version info 
+%s""" % textwrap.fill(
+    ', '.join(__all__) + '.',
+    width=78,
+    initial_indent='    ',
+    subsequent_indent='    ')
+
+# Add easy way to get the version info
 from .version import version as release_info
 
+
 def version():
     return release_info
 
+
 __version__ = version()