snappy 3.3__cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

snappy/cache.py

@@ -0,0 +1,25 @@
+class SnapPyCache(dict):
+    """
+    Implementation of a simple cache used by the Manifold and Triangulation
+    to save the results of methods which require a significant amount of
+    computation.
+
+    This cache uses the tuple (method.__name, args, kwargs) as its key.
+    """
+    debug = False
+    _clear = dict.clear
+
+    def save(self, answer, method_name, *args, **kwargs):
+        self[(method_name, args, tuple(kwargs.items()))] = answer
+        return answer
+
+    def lookup(self, method_name, *args, **kwargs):
+        return self[(method_name, args, tuple(kwargs.items()))]
+
+    def clear(self, key=None, message=''):
+        if self.debug:
+            print('_clear_cache: %s' % message)
+        if key is None:
+            self._clear()
+        else:
+            self.pop(key)

snappy/canonical.py

@@ -0,0 +1,249 @@
+from . import verify
+from . import Triangulation, TriangulationHP, Manifold, ManifoldHP
+
+from typing import Optional, Union, Sequence, Tuple
+
+__all__ = ['canonical_retriangulation', 'canonical_retriangulation_hp']
+
+def _canonical_retriangulation(
+        manifold : Union[Manifold, ManifoldHP],
+        verified : bool,
+        interval_bits_precs : Sequence[int],
+        exact_bits_prec_and_degrees : Sequence[Tuple[int, int]],
+        verbose : bool) -> Union[Triangulation, TriangulationHP,
+                                 Manifold, ManifoldHP]:
+    """
+    Returns a triangulation canonically associated to the hyperbolic manifold.
+    That is, the triangulation is (up to combinatorial isomorphism relabeling
+    the tetrahedra and vertices) completely determined by the isometry type of
+    the hyperbolic manifold.
+
+    Manifolds with incomplete cusps are rejected (unlike in the case of
+    :meth:`isometry_signature <snappy.Manifold.isometry_signature>`).
+
+    We now describe the canonical retriangulation. If all cells of
+    the canonical cell decomposition (defined by `Epstein and Penner '88
+    <https://projecteuclid.org/euclid.jdg/1214441650>`_) are tetrahedral,
+    :meth:`canonical_retriangulation <Manifold.canonical_retriangulation>`
+    simply returns that ideal triangulation as a
+    :class:`Manifold <snappy.Manifold>`. Here is an example::
+
+       >>> M = Manifold("m015")
+       >>> K = M.canonical_retriangulation()
+       >>> K.has_finite_vertices()
+       False
+       >>> K.solution_type()
+       'all tetrahedra positively oriented'
+
+    If there are non-tetrahedral cells,
+    :meth:`canonical_retriangulation <Manifold.canonical_retriangulation>`
+    subdivides the canonical cell decomposition. It introduces a finite vertex
+    for each canonical cell resulting in a
+    :class:`Triangulation <snappy.Triangulation>`. Here is an example where the
+    canonical cell is a cube::
+
+       >>> M = Manifold("m412")
+       >>> K = M.canonical_retriangulation()
+       >>> K.has_finite_vertices()
+       True
+
+    The canonical retriangulation can be used to find the symmetries of a
+    single manifold. It also can compute the isometries between two
+    manifolds. We do this using
+    :meth:`isomorphisms_to <snappy.Triangulation.isomorphisms_to>`::
+
+       >>> M = Manifold("5_2").canonical_retriangulation()
+       >>> N = Manifold("m015").canonical_retriangulation()
+       >>> M.isomorphisms_to(M) #doctest: +ELLIPSIS
+       [0 -> 0
+       [1 0]
+       [0 1]
+       ...
+       >>> M.isomorphisms_to(N) #doctest: +ELLIPSIS
+       [0 -> 0
+       [-1  2]
+       [ 0 -1]
+       ...
+
+    The canonical retriangulation is also the basis for the
+    :meth:`isometry_signature <snappy.Manifold.isometry_signature>`.
+
+    **Subdivision**
+
+    If the canonical cell decomposition has a non-tetrahedral cell, the method
+    subdivides. You can think of the subdivision in either of the following
+    (equivalent) ways:
+
+    - A coarsening of the barycentric subdivision with only a quarter of the
+      number of tetrahedra. That is, take the barycentric subdivision and
+      merge the four tetrahedra adjacent to a barycentric edge connecting
+      an edge midpoint to a face midpoint.
+    - Taking the double suspension of each face (which is an ideal n-gon)
+      about the centers of the two neighboring 3-cells. Then split each
+      such topological "lens" into n tetrahedra along its central axis.
+
+    **Verified computations**
+
+    While the canonical retriangulation is combinatorial, some intermediate
+    computations are numerical. Thus, if :attr:`verified = False`,
+    floating-point issues can arise.
+    (Arguably this gave rise to a mistake in the
+    non-orientable census. ``x101`` and ``x103`` were later identified as
+    the same by `Burton '14 <http://arxiv.org/abs/1311.7615>`_.)
+
+    The method can be made :ref:`verified <verify-primer>` by passing
+    :attr:`verified = True`::
+
+      sage: M = Manifold("v2986")
+      sage: K = M.canonical_retriangulation(verified = True)
+      sage: K.has_finite_vertices() # Cell decomposition verified to be tetrahedral
+      False
+      sage: K.triangulation_isosig(decorated=False) # Verified isometry signature.
+      'jvLALQQdeefgihihiokcmmwwswg'
+      sage: len(K.isomorphisms_to(K)) # Verified to have no (non-trivial) symmetries.
+      1
+
+    Interval arithmetic can only be used to verify the canonical cell decomposition
+    if all cells are tetrahedral. For non-tetrahedral cells, the method
+    automatically switches to
+    exact methods to verify the canonical cell decomposition. That is, it uses
+    snap-like methods
+    (`LLL-algorithm <http://en.wikipedia.org/wiki/Lenstra%E2%80%93Lenstra%E2%80%93Lov%C3%A1sz_lattice_basis_reduction_algorithm>`_)
+    to guess a representation of the
+    shapes in the shape field. It then uses exact arithmetic to verify the
+    shapes form a valid geometric structure and compute the necessary tilts
+    to verify the canonical cell decomposition. Note that this can take a
+    long time!
+
+    Here is an example where exact methods are used::
+
+      sage: M = Manifold("m412")
+      sage: K = M.canonical_retriangulation(verified = True)
+      sage: K.has_finite_vertices() # Has non-tetrahedral cell
+      True
+
+    If the canonical retriangulation cannot be verified, an exception will be
+    raised. (Note that this is new (and safer) in Version 3.2. Prior to that
+    version, :meth:`Manifold.canonical_retriangulation` could return ``None``
+    instead.)
+
+    Here is an example where we skip the (potentially lengthy) exact methods
+    needed to verify a non-tetrahedral cell. The method fails (early
+    and with an exception) since the cells are actually tetrahedral::
+
+      sage: M = Manifold("m412")
+      sage: K = M.canonical_retriangulation(verified = True, exact_bits_prec_and_degrees = []) # doctest: +ELLIPSIS +IGNORE_EXCEPTION_DETAIL
+      Traceback (most recent call last):
+      ...
+      snappy.verify.exceptions.TiltInequalityNumericalVerifyError: Numerical verification that tilt is negative has failed: ... < 0
+
+    :param verified:
+            Use :ref:`verified computation <verify-primer>`.
+    :param interval_bits_precs:
+            Only relevant if :attr:`verified = True`.
+            A list of (increasing) precisions used to try to
+            certify the canonical cell decomposition using intervals. Each
+            precision is tried until we succeed. If none succeeded, we move on
+            to exact methods.
+    :param exact_bits_prec_and_degrees:
+            Only relevant if :attr:`verified = True`.
+            A list of pairs (precision, max degree) used when the
+            LLL-algorithm is trying to find the defining
+            polynomial of the shape field with
+            ``ListOfApproximateAlgebraicNumbers.find_field``.
+            Each pair is tried until we succeed.
+    :param verbose:
+            Print information about the methods tried to compute and verify the
+            canonical retriangulation.
+    :return:
+            If the canonical cell decomposition exists entirely of
+            (hyperbolic ideal) tetrahedra, a :class:`Manifold` with those
+            tetrahedra.
+            Otherwise, a :class:`Triangulation` that is a subdivision of the
+            canonical cell decomposition.
+    """
+
+    # More information on the canonical retriangulation can be found in the
+    # SnapPea kernel ``canonize_part_2.c`` and in Section 3.1 of
+    # `Fominykh, Garoufalidis, Goerner, Tarkaev, Vesnin <http://arxiv.org/abs/1502.00383>`_.
+
+    if not all(manifold.cusp_info('complete?')):
+        # It is unclear what to do when there are filling coefficients.
+        # The SnapPea kernel ignores them and uses the complete structure
+        # to compute the canonical retriangulation.
+        #
+        # That makes sense to, e.g., compute a canonical representation
+        # of a surgery diagram.
+        #
+        # In other situations, it makes perfectly sense to fill the cusps
+        # instead. That is, e.g., what the isometry_signature does.
+        #
+        # Since it is ambiguous, I decided to simply reject it here.
+        #
+        # It is easy enough for a user to either call fill_triangulation
+        # or to save the coefficients and unfill all cusps.
+        #
+        raise ValueError(
+            'Canonical retriangulation needs all cusps to be complete.')
+
+    if verified:
+        # verified_canonical_retriangulation has code to check
+        # for incomplete cusps and fill them that never gets
+        # executed because of the above "if"
+        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:
+        # Note that the SnapPea kernel actually ignores Dehn-fillings
+        # when computing the canonical retriangulation.
+        if not all(manifold.cusp_info('complete?')):
+            # Never executed because of above "if".
+            manifold = manifold.filled_triangulation()
+            if not all(manifold.cusp_info('complete?')):
+                raise ValueError(
+                    'Could not compute filled triangulation. '
+                    'Are the filling coefficients co-prime integers?')
+
+        K = manifold._canonical_retriangulation()
+        if K.has_finite_vertices():
+            return K
+        else:
+            if isinstance(manifold, ManifoldHP):
+                return ManifoldHP(K)
+            else:
+                return Manifold(K)
+
+# Wraps _canonical_retriangulation to have the correct return type
+def canonical_retriangulation(
+        manifold : Manifold,
+        verified : bool = False,
+        interval_bits_precs : Sequence[int] = verify.default_interval_bits_precs,
+        exact_bits_prec_and_degrees : Sequence[Tuple[int, int]] = verify.default_exact_bits_prec_and_degrees,
+        verbose : bool = False) -> Union[Triangulation, Manifold]:
+    return _canonical_retriangulation(
+        manifold,
+        verified = verified,
+        interval_bits_precs = interval_bits_precs,
+        exact_bits_prec_and_degrees = exact_bits_prec_and_degrees,
+        verbose = verbose)
+canonical_retriangulation.__doc__ = _canonical_retriangulation.__doc__
+            
+# Wraps _canonical_retriangulation to have the correct return type
+def canonical_retriangulation_hp(
+        manifold : ManifoldHP,
+        verified : bool = False,
+        interval_bits_precs : Sequence[int] = verify.default_interval_bits_precs,
+        exact_bits_prec_and_degrees : Sequence[Tuple[int, int]] = verify.default_exact_bits_prec_and_degrees,
+        verbose : bool = False) -> Union[TriangulationHP, ManifoldHP]:
+    return _canonical_retriangulation(
+        manifold,
+        verified = verified,
+        interval_bits_precs = interval_bits_precs,
+        exact_bits_prec_and_degrees = exact_bits_prec_and_degrees,
+        verbose = verbose)
+canonical_retriangulation_hp.__doc__ = _canonical_retriangulation.__doc__
+
+
+

snappy/cusps/__init__.py

@@ -0,0 +1,280 @@
+"""
+Computing data about cusps such as cusp matrix, shape, translations
+and exceptional slopes.
+"""
+
+from ..geometric_structure.cusp_neighborhood.complex_cusp_cross_section import ComplexCuspCrossSection
+from ..geometric_structure.cusp_neighborhood.exceptions import IncompleteCuspError
+from ..verify.shapes import compute_hyperbolic_shapes
+from ..exceptions import NonorientableManifoldError
+from . import short_slopes_for_cusp
+from . import cusp_areas_from_matrix
+
+from typing import Optional, List
+
+def compute_cusp_shapes(manifold, verified, bits_prec=None):
+    """
+    Compute cusp shapes. Following the SnapPea kernel convention,
+    it returns the conjugate of the quotient of the translations
+    corresponding to the longitude and meridian for each cusp.
+
+    >>> M = Manifold('s843')
+    >>> M.cusp_info('shape', bits_prec = 100) # doctest: +NUMERIC21
+    [0.46738227586341496791816972792 + 1.1903600506742881207098973751*I, 0.084187324414612694374797271558 + 1.0506945576790020048456757228*I]
+
+    sage: M = Manifold('s843')
+    sage: M.cusp_info('shape', verified = True) # doctest: +NUMERIC9
+    [0.46738227587? + 1.19036005068?*I, 0.0841873244146? + 1.0506945576790?*I]
+
+    sage: M.cusp_info('shape', verified = True, bits_prec = 100) # doctest: +NUMERIC21
+    [0.4673822758634149679181698? + 1.1903600506742881207098974?*I, 0.084187324414612694374797272? + 1.050694557679002004845675723?*I]
+    """
+
+    if not manifold.is_orientable():
+        raise NonorientableManifoldError(manifold)
+
+    for cusp_info in manifold.cusp_info():
+        if not cusp_info['complete?']:
+            raise IncompleteCuspError(manifold)
+
+    shapes = compute_hyperbolic_shapes(
+        manifold, verified=verified, bits_prec=bits_prec)
+
+    # Compute cusp cross section
+    c = ComplexCuspCrossSection.fromManifoldAndShapes(manifold, shapes)
+
+    # Compute shape
+    return c.cusp_shapes()
+
+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).
+
+    There are different policies how these cusp neighborhoods are found.
+
+    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, :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]
+
+    Use :attr:`first_cusps` to specify the order in which the cusp
+    neighborhoods are blown up::
+
+        >>> M.cusp_areas(policy='greedy', first_cusps=[1,0,2]) # doctest: +NUMERIC9
+        [1.32287565553230, 5.29150262212918, 1.32287565553229]
+
+    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::
+
+        >>> M.cusp_areas(policy='greedy', first_cusps=[1]) # doctest: +NUMERIC9
+        [1.32287565553230, 5.29150262212918, 1.32287565553229]
+
+    Under the hood, this method is using
+    :meth:`~snappy.Manifold.cusp_area_matrix`.
+
+    **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 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 cusp_areas_from_matrix.unbiased_cusp_areas_from_cusp_area_matrix(m)
+    else:
+        return cusp_areas_from_matrix.greedy_cusp_areas_from_cusp_area_matrix(m, first_cusps=first_cusps)
+
+def _cusp_shapes_and_areas(
+        manifold, *,
+        policy : str,
+        method : str,
+        verified : bool,
+        bits_prec : Optional[int],
+        first_cusps : List[int]):
+
+    cusp_shapes = manifold.cusp_info(
+        'shape', verified=verified, bits_prec=bits_prec)
+    cusp_areas = manifold.cusp_areas(
+        policy=policy, method=method,
+        verified=verified, bits_prec=bits_prec, first_cusps=first_cusps)
+
+    return zip(cusp_shapes, cusp_areas)
+
+def short_slopes(manifold,
+                 length=6,
+                 policy : str = 'unbiased',
+                 method : str = 'maximal',
+                 verified : bool = False,
+                 bits_prec : Optional[int] = None,
+                 first_cusps : List[int] = []):
+    """
+    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)]]
+
+    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 :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)]]
+
+    **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)
+        [[(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 [
+        short_slopes_for_cusp.short_slopes_from_cusp_shape_and_area(
+            cusp_shape, cusp_area, length=length)
+        for cusp_shape, cusp_area
+        in _cusp_shapes_and_areas(
+            manifold,
+            policy = policy,
+            method = method,
+            verified = verified,
+            bits_prec = bits_prec,
+            first_cusps = first_cusps) ]
+
+def cusp_translations(manifold,
+                      policy : str = 'unbiased',
+                      method : str = 'maximal',
+                      verified : bool = False,
+                      bits_prec : Optional[int] = None,
+                      first_cusps : List[int] = []):
+    """
+    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)]
+
+    It takes the same arguments as :meth:`~snappy.Manifold.cusp_areas`::
+
+        >>> 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)]
+
+    **Verified computations**
+
+    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.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?)]
+
+    Note that the first element of each pair is a SageMath ``ComplexIntervalField`` and
+    the second element a ``RealIntervalField``.
+    """
+
+    return [
+        short_slopes_for_cusp.translations_from_cusp_shape_and_area(
+            cusp_shape, cusp_area, kernel_convention=True)
+        for cusp_shape, cusp_area
+        in _cusp_shapes_and_areas(
+            manifold,
+            policy = policy,
+            method = method,
+            verified = verified,
+            bits_prec = bits_prec,
+            first_cusps = first_cusps) ]

snappy/cusps/cusp_area_matrix.py

@@ -0,0 +1,98 @@
+from .maximal_cusp_area_matrix import maximal_cusp_area_matrix
+from .trig_cusp_area_matrix import triangulation_dependent_cusp_area_matrix
+from ..geometric_structure.cusp_neighborhood.exceptions import IncompleteCuspError
+
+from typing import Optional
+
+def cusp_area_matrix(
+        manifold,
+        method : str = 'maximal',
+        verified : bool = False,
+        bits_prec : Optional[int] = None):
+    """
+    Returns the maximal cusp area matrix :math:`(A_{ij})` where
+    :math:`A_{ij}` is defined as follows.
+    Let :math:`C_i` and :math:`C_j` be the (open) cusp neighborhoods about cusp
+    :math:`i` and :math:`j`. Let :math:`A(C_i)` and :math:`A(C_j)` be the
+    areas of :math:`C_i` and :math:`C_j`, respectively. Then, :math:`C_i`
+    and :math:`C_j` are embedded (if :math:`i = j`) or disjoint (otherwise)
+    if and only if :math:`A(C_i)A(C_j) \\leq A_{ij}`.
+
+    Here is an example::
+    
+        >>> M = Manifold("L6a5")
+        >>> M.cusp_area_matrix() # doctest: +NUMERIC12
+        [27.9999999999996 7.00000000000000 7.00000000000000]
+        [7.00000000000000 27.9999999999999 7.00000000000000]
+        [7.00000000000000 7.00000000000000 28.0000000000001]
+
+
+    **Faster lower bounds**
+
+    This section can be skipped by most users!
+
+    Prior to SnapPy version 3.2, the algorithm to compute the maximal cusp
+    area matrix was much slower and required :attr:`verified = True` and
+    SageMath. Thus, in prior versions, :attr:`method` defaulted to
+    ``trigDependentTryCanonize``. This meant, that, by default,
+    :meth:`~snappy.Manifold.cusp_area_matrix` only returned
+    (some) lower bounds for the maximal cusp area matrix entries.
+
+    These lower bounds can still be accessed::
+
+        >>> M.cusp_area_matrix(method = 'trigDependentTryCanonize') # doctest: +NUMERIC12
+        [21.4375000000000 7.00000000000000 7.00000000000000]
+        [7.00000000000000 28.0000000000000 7.00000000000000]
+        [7.00000000000000 7.00000000000000 28.0000000000000]
+
+    If :attr:`method = 'trigDependent'` or
+    :attr:`method = 'trigDependenyTryCanonize'`, the result is triangulation
+    dependent or not even deterministic, respectively.
+    Furthermore, if :attr:`verified = True` is also set, while the left
+    endpoints of the intervals are lower bounds for the maximal cusp area
+    matrix entries, the right endpoints are meaningless and could be smaller
+    or larger than the maximal cusp area matrix entries.
+
+    **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.cusp_area_matrix(verified=True) # doctest: +NUMERIC3
+        [       28.0000? 7.000000000000?  7.00000000000?]
+        [7.000000000000?      28.000000?  7.00000000000?]
+        [ 7.00000000000?  7.00000000000?       28.00000?]
+
+    :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:
+            Switches to older algorithms giving lower bounds when
+            ``trigDependentTryCanonize`` and ``trigDependent``.
+    :return:
+            Maximal cusp area matrix (default) or lower bounds
+            (if :attr:`method` switches to older algorithm).
+    """
+
+    for cusp_info in manifold.cusp_info():
+        if not cusp_info['complete?']:
+            raise IncompleteCuspError(manifold)
+
+    if method == 'maximal':
+        return maximal_cusp_area_matrix(
+            manifold, bits_prec=bits_prec, verified=verified)
+    if method in ['trigDependent', 'trigDependentTryCanonize']:
+        if method == 'trigDependentTryCanonize':
+            manifold = manifold.copy()
+            manifold.canonize()
+
+        return triangulation_dependent_cusp_area_matrix(
+            manifold, bits_prec=bits_prec, verified=verified)
+
+    raise ValueError("method passed to cusp_area_matrix must be "
+                       "'trigDependent', 'trigDependentTryCanonize', "
+                       "or 'maximal'.")
+