snappy 3.3__cp310-cp310-manylinux_2_24_aarch64.manylinux_2_28_aarch64.whl

snappy/len_spec/geodesic_info.py

@@ -0,0 +1,129 @@
+from ..geometric_structure.geodesic.fixed_points import r13_fixed_line_of_psl2c_matrix
+from ..geometric_structure.geodesic.geodesic_start_point_info import sample_line, GeodesicStartPointInfo
+from ..geometric_structure.geodesic.line import R13LineWithMatrix
+from ..hyperboloid.line import R13Line
+from ..hyperboloid import so13_to_psl2c
+from ..upper_halfspace import complex_length_of_psl2c_matrix
+from ..math_basics import lower # type: ignore
+from ..snap.t3mlite import Mcomplex
+
+from typing import List, Optional
+
+class GeodesicStreamInfoBase:
+    """
+    Base class for intermediates, core curves and (non-core curve)
+    geodesics in the length spectrum stream. Also used for the
+    data structures used by the length spectrum algorithm such as
+    the priority queue or the dictionary to de-duplicate geodesics.
+    """
+    def __init__(self, length):
+        self.length = length
+
+class GeodesicIntermediateInfo(GeodesicStreamInfoBase):
+    """
+    Intermediate indicating that all geodesics up to this point
+    have been enumerated.
+    """
+    pass
+
+class GeodesicInfoBase(GeodesicStreamInfoBase):
+    """
+    Basic information about a geodesic, consisting of word and matrix.
+
+    Used intermediately during the computation of the length spectrum.
+    Ordered by (lower bound of) real length.
+
+    After de-duplication, it is converted to the user-facing
+    LengthSpectrumGeodesicInfo.
+    """
+    def __init__(self,
+                 word : List[int],
+                 o13_matrix):
+        self.word = word
+        self.o13_matrix = o13_matrix
+        self.psl2c_matrix = so13_to_psl2c(self.o13_matrix)
+
+        super().__init__(
+            length=complex_length_of_psl2c_matrix(self.psl2c_matrix))
+
+        self._key = lower(self.length.real())
+
+    def __lt__(self, other):
+        """
+        Ordering <.
+        """
+        return self._key < other._key
+
+class CoreCurveGeodesicInfo(GeodesicInfoBase):
+    """
+    Information for a known core curve. That is, we go through each
+    filled cusp and compute this information before starting to compute
+    the length spectrum.
+
+    It contains the index of the corresponding (filled) cusp.
+    """
+    def __init__(self,
+                 word : List[int],
+                 o13_matrix,
+                 core_curve : int):
+        super().__init__(word, o13_matrix)
+        self.core_curve = core_curve
+
+class GeodesicKeyInfo(GeodesicInfoBase):
+    """
+    Information for a geodesic which might potentially a multiple of another
+    geodesic or even a core curve.
+
+    Via geodesic_start_point_info, we can determine whether this geodesic
+    corresponds to a multiple of a core curve.
+
+    Given two geodesics that are not core curves, we can also use this
+    information here to determine whether one is a conjugate of a multiple of
+    the other.
+
+    Also see get_geodesic_key_info_dict and get_geodesic_key_info_set.
+    """
+    def __init__(self,
+                 mcomplex : Mcomplex,
+                 word : List[int],
+                 o13_matrix):
+        super().__init__(word, o13_matrix)
+        self.mcomplex = mcomplex
+
+        self._r13_line_with_matrix : Optional[R13LineWithMatrix] = None
+        self._info : Optional[GeodesicStartPointInfo] = None
+
+    def r13_line_with_matrix(self) -> R13LineWithMatrix:
+        """
+        The actual line in H^3 with the matrix corresponding to the
+        geodesic.
+        """
+        if self._r13_line_with_matrix is None:
+            self._r13_line_with_matrix = (
+                r13_fixed_line_of_psl2c_matrix(self.psl2c_matrix))
+
+        return self._r13_line_with_matrix
+
+    def r13_line(self) -> R13Line:
+        """
+        The actually line in H^3 corresponding to the geodesic.
+        """
+        return self.r13_line_with_matrix().r13_line
+
+    def geodesic_start_point_info(self) -> GeodesicStartPointInfo:
+        """
+        Information to start developing about the geodesic.
+        """
+        if self._info is None:
+            start_point = sample_line(self.r13_line())
+
+            self._info = GeodesicStartPointInfo(
+                mcomplex=self.mcomplex,
+                word=self.word,
+                trace=self.psl2c_matrix.trace(),
+                unnormalised_start_point = start_point,
+                unnormalised_end_point=self.o13_matrix * start_point,
+                line=self.r13_line_with_matrix())
+            self._info.find_tet_or_core_curve()
+
+        return self._info

snappy/len_spec/geodesic_key_info_dict.py

@@ -0,0 +1,116 @@
+from .geodesic_piece import GeodesicPiece, get_geodesic_piece_dict
+from .geodesic_info import GeodesicKeyInfo
+
+from ..tiling.quotient_dict import QuotientDict
+from ..tiling.dict_based_set import DictBasedSet
+from ..geometric_structure.geodesic.tiles_for_geodesic import compute_tiles_for_geodesic
+from ..geometric_structure.geodesic.geodesic_start_point_info import GeodesicStartPointInfo
+from ..hyperboloid import o13_inverse, r13_to_klein
+from ..snap.t3mlite import Mcomplex
+from ..exceptions import InsufficientPrecisionError
+
+from typing import List, Sequence
+
+def get_geodesic_key_info_dict(mcomplex : Mcomplex):
+    """
+    Given a triangulation with a geometric structure, gives an (empty)
+    dictionary where keys are GeodesicKeyInfo's not corresponding to
+    core curves.
+
+    Two keys are regarded the same if they give the same geodesic in the
+    manifold up to multiplicity and orientation of the geodesic.
+
+    Note that the same caveat from get_geodesic_piece_dict about this not
+    being an equivalence relationship applies.
+
+    In particular, it assumed that we insert the primitive geodesic before
+    we insert a multiple of that primitive geodesic.
+    """
+    return QuotientDict(
+            get_geodesic_piece_dict(mcomplex),
+            _canonical_representatives)
+
+def get_geodesic_key_info_set(mcomplex : Mcomplex):
+    """
+    Analogous to get_geodesic_key_info_dict, gives a set where the
+    elements are GeodesicKeyInfo's not corresponding to core curves.
+
+    The same caveats apply.
+    """
+    return DictBasedSet(get_geodesic_key_info_dict(mcomplex))
+
+def _canonical_representatives(key_info : GeodesicKeyInfo) -> List[GeodesicPiece]:
+    """
+    To see whether two geodesics are the same, we compute the intersection
+    of the geodesic with each tetrahedron and store the information in
+    GeodesicPiece's.
+
+    If a part of the geodesic is so close to the skeleton that it cannot be
+    decided whether it intersects a tetrahedron or not, we conservatively add
+    the GeodesicPiece. In particular, if a geodesic is going through a face
+    of a tetrahedron, we add the two tetrahedra neighboring that face.
+
+    We obtain the GeodesicPieces by developing a tube about the geodesic until
+    we can verify that the tube has positive radius.
+    """
+
+    if key_info.geodesic_start_point_info().core_curve_cusp:
+        raise ValueError(
+            "Expected a non-core curve geodesic as key for dictionary of "
+            "GeodesicKeyInfo's.")
+
+    # Note that geodesic_start_point_info might compute a transform of
+    # the given geodesic. This is to ensure that it can find a lifted
+    # tetrahedron in the fundamental domain containing the point about which
+    # we start developing (or a pair of two lifted tetrahedra where one
+    # is in the fundamental domain).
+
+    return _compute_geodesic_pieces(
+        key_info.mcomplex,
+        key_info.geodesic_start_point_info(),
+        key_info.length.real())
+
+def _compute_geodesic_pieces(
+        mcomplex : Mcomplex,
+        info : GeodesicStartPointInfo,
+        real_length) -> Sequence[GeodesicPiece]:
+
+    g = info.line.o13_matrix
+
+    for tile in compute_tiles_for_geodesic(
+            mcomplex, info, avoid_core_curves = True):
+        if tile.lower_bound_distance > 0:
+            break
+
+        h = tile.lifted_tetrahedron.o13_matrix
+
+        # Compute the matrix corresponding to line given by
+        # tile.inverse_lifted_geometric_object.
+        #
+        # Ideally, compute_tiles_for_geodesic could work with
+        # both types, R13Line and R13LineWithMatrix and do the
+        # appropriate thing.
+        #
+        m0 = o13_inverse(h) * g * h
+
+        # Also compute the inverse
+        m1 = o13_inverse(m0)
+
+        pt0, pt1 = tile.inverse_lifted_geometric_object.points
+
+        # We do not know which of pt0 and pt1 is the attracting fixed point
+        # of m0 or m1.
+        # Check and switch around if necessary.
+
+        if (m0 * pt0)[0] > pt0[0]:
+            pass
+        elif (m0 * pt1)[0] > pt1[0]:
+            pt1, pt0 = pt0, pt1
+        else:
+            raise InsufficientPrecisionError(
+                "Could not determine which fixed point is attracting. "
+                "Increasing the precision should fix this.")
+
+        # Emit a GeodesicPiece for both orientations of the geodesic.
+        for pt, m in ((pt0, m0), (pt1, m1)):
+            yield GeodesicPiece(r13_to_klein(pt), m, real_length)

snappy/len_spec/geodesic_piece.py

@@ -0,0 +1,146 @@
+from ..tiling.real_hash_dict import RealHashDict
+from ..hyperboloid import o13_inverse
+from ..hyperboloid.distances import distance_r13_points
+from ..snap.t3mlite import Mcomplex
+from ..exceptions import InsufficientPrecisionError
+
+from typing import Optional
+
+class GeodesicPiece:
+    """
+    For a hyperbolic manifold given through context, this class stores enough
+    information about a loxodromic Decktransformation of H^3 to determine
+    whether one loxodromic is a positive multiple of another one.
+
+    This can be used as keys in a dictionary constructed with
+    get_geodesic_piece_dict.
+
+    The information consists of the attracting fixed point encoded as 3-vector
+    in S^2 (as boundary of the Klein or Poincare ball model), the associated
+    matrix and the real part of the translation length.
+
+    Note that intervals for the attracing fixed point can be used to verify
+    two loxodromics apart up to multiplicity (and are good for hashing).
+    But we need the matrix to verify that two loxodromics are the same - or
+    that one is a multiple of another.
+    """
+
+    def __init__(self,
+                 klein_endpoint, # 3-vector in S^2
+                 o13_matrix,
+                 real_length):
+        self.klein_endpoint = klein_endpoint
+        self.o13_matrix = o13_matrix
+        self.real_length = real_length
+
+def get_geodesic_piece_dict(mcomplex : Mcomplex):
+    """
+    Returns a dictionary where the keys can be GeodesicPiece's.
+    The GeodesicPiece's have to be for loxodromics coming from the given
+    triangulation with a geometric structure.
+
+    Two keys are regarded as the same if the matrix of one is a multiple
+    of the matrix of the other key.
+
+    Note that this is not quite an equivalence relation: if B and C are
+    multiples of A, then B is not necessarily a multiple of C.
+
+    It is assumed that we insert the primitive matrix before we insert a
+    multiple of that primitive matrix.
+    """
+    return RealHashDict(
+        _equality_predicate(mcomplex),
+        _hash(mcomplex.RF),
+        _epsilon_inverse,
+        mcomplex.verified)
+
+_epsilon_inverse = 1024
+
+def _hash(RF):
+    weights = [ RF(1.2003), RF(0.94533), RF(1.431112) ]
+
+    def result(piece : GeodesicPiece):
+        """
+        Use attracting fixed point for computing the hash.
+        """
+        return (piece.klein_endpoint[0] * weights[0] +
+                piece.klein_endpoint[1] * weights[1] +
+                piece.klein_endpoint[2] * weights[2])
+
+    return result
+
+def _equality_predicate(mcomplex):
+    def unsymmetrized_result(piece_0 : GeodesicPiece,
+                             piece_1 : GeodesicPiece) -> bool:
+        """
+        Check whether the matrix of piece_1 is a multiple of
+        the matrix of piece_0.
+
+        Raise an exception if this could not be decided.
+        """
+
+        candidate_multiplicity = piece_1.real_length / piece_0.real_length
+
+        multiplicity = _int_or_none(
+            candidate_multiplicity, mcomplex.verified)
+        if multiplicity is None:
+            return False
+
+        # Compute translates of base points.
+        base = mcomplex.R13_baseTetInCenter
+
+        base_0 = base
+        for i in range(multiplicity):
+            base_0 = piece_0.o13_matrix * base_0
+
+        base_1 = piece_1.o13_matrix * base
+
+        # And then use the distance to see whether one matrix is
+        # a multiple of the other.
+        d = distance_r13_points(base_1, base_0)
+        if d < mcomplex.baseTetInRadius:
+            return True
+        if d > mcomplex.baseTetInRadius:
+            return False
+        raise InsufficientPrecisionError(
+            "Could not determine whether two pieces of a geodesic are the "
+            "same.\n"
+            "Distance of images of basepoints: %r.\n"
+            "Base tetrahedron in radius:       %r.\n"
+            "Increasing precision should fix this." % (
+                d, mcomplex.baseTetInRadius))
+
+    def result(piece_0 : GeodesicPiece,
+               piece_1 : GeodesicPiece) -> bool:
+        """
+        Check whether the matrix of piece_0 is a multiple of
+        the matrix of piece_1 or vice versa.
+        """
+        if piece_0.real_length > piece_1.real_length:
+            return unsymmetrized_result(piece_1, piece_0)
+        else:
+            return unsymmetrized_result(piece_0, piece_1)
+
+    return result
+
+_is_int_epsilon = 0.001
+
+def _int_or_none(r, verified) -> Optional[int]:
+    if verified:
+        if r.floor() < r:
+            # We have verified that r contains no integer
+            # (r.floor() is an interval).
+            return None
+        is_int, r_int = r.is_int()
+        if is_int:
+            # We have verified that r contains a unique integer.
+            return r_int
+
+        # We get here for, e.g., RIF(0.5, 2.5).is_int()
+        raise InsufficientPrecisionError(
+            "Interval for multiplicity of geodesic contains multiple integers.")
+    else:
+        r_int = r.round()
+        if abs(r_int -r) < _is_int_epsilon:
+            return int(r_int)
+        return None

snappy/len_spec/geometric_structure.py

@@ -0,0 +1,182 @@
+from .spine import add_spine
+
+from ..geometric_structure import add_r13_geometry, add_filling_information
+from ..geometric_structure.geodesic.add_core_curves import add_r13_core_curves
+from ..geometric_structure.cusp_neighborhood.complex_cusp_cross_section import ComplexCuspCrossSection
+from ..geometric_structure.cusp_neighborhood.vertices import scale_vertices_from_horotriangles
+
+from ..cusps.trig_cusp_area_matrix import triangulation_dependent_cusp_area_matrix_from_cusp_cross_section
+from ..cusps.cusp_areas_from_matrix import unbiased_cusp_areas_from_cusp_area_matrix
+from ..tiling.triangle import add_triangles_to_tetrahedra
+from ..math_basics import correct_min
+from ..matrix import make_matrix
+from ..snap.t3mlite import Mcomplex
+
+from typing import Optional
+
+def mcomplex_for_len_spec(
+        manifold, bits_prec : Optional[int], verified : bool) -> Mcomplex:
+    """
+    Convert a SnapPy manifold (wrapping a SnapPea kernel C triangulation) to
+    an Mcomplex (a python triangulation) and a geometric structures to the
+    Mcomplex necessary to compute the length spectrum.
+
+    The basic geometric structures are:
+    - the shapes of the ideal tetrahedra in tet.ShapeParameters
+    - the position of the vertices when developing the fundamental domain
+      in R13 in tet.R13_vertices (scaled to define a cusp neighborhood or
+      tube about a core curve, see later for details)
+    - the O13 face-pairing matrices between the tetrahedra in tet.O13_matrices
+    - to what (possibly trivial) generate a face-pairing belongs
+      in tet.GeneratorsInfo
+    - the plane equations for the faces (with normal facing outward)
+      in tet in tet.R13_planes and tet.R13_unnormalised_planes
+    - ideal triangles for each face in tet.R13_triangles
+    - the (possibly trivial) filling of each cusp as matrix tet.filling_matrix
+      encoding the filling curve as well as a cure parallel to the core curve.
+    - the core curves in tet.core_curve as R13LineWithMatrix
+
+    Furthermore, we also pick disjoint and embedded cusp neighborhoods (for
+    complete cusps) or tubes (for filled cusps) about the core curve for all
+    cusps.
+
+    We always work with horotriangles to truncate tetrahedra. That is, if we
+    have a tube about a core curve, we pick the horotriangles large
+    enough that they are fully outside the tube. Through a scale factor, we
+    also (indirectly) specify the horotriangles small enough that they are
+    fully inside the tube. So for a core curve, the truncated tetrahedra look
+    like a triangular version of the Giant's Causeway in Northern Ireland.
+
+    The picked horotriangles are such that the regions of a
+    tetrahedron they cut off are disjoint and do not cut-off the incenter of
+    the tetrahedron.
+
+    We use the cusp neighborhood choices and horotriangles to compute:
+    - the radius of the tube about the core curve in
+      cusp.core_curve_tube_radius so that if a geodesic goes through a
+      core curve, we can avoid developing the geodesic inside this tube
+      (which would require infinitely many pieces to reach the core curve)
+      by calling replace_piece_in_core_curve_tube.
+    - scale the tet.R13_vertices so that they define the horosphere that
+      cuts the tetrahedron in the picked horotriangle.
+
+    Recall that a spine of the triangulation has the key property that each
+    geodesic that is not a core curve is intersecting the spine.
+
+    We also use the cusp neighborhood choices and horotriangles to compute:
+    - use the tetrahedron's incenter as its spine center tet.spine_center.
+    - compute tet.out_radius, the radius (about the spine center) of a
+      tetrahedron truncated by the smaller horotriangles given by the scale
+      factor.
+    - tet.spine_radius is the radius of a ball about tet.spine_center
+      containing the restriction of the spine to the tetrahedron.
+    - tet.inv_spine_cosh = 1 / cosh(r) where r is the tet.spine_radius
+    - The spine center of the base tetrahedron is stored in
+      mcomplex.spine_center. We regard it as center for the lift of the
+      entire spine to H^3 and restricted to a fundamental domain.
+      mcomplex.spine_radius is the radius of a ball about this spine
+      center that contains the entire spine.
+    """
+
+    mcomplex = Mcomplex(manifold)
+
+    # Add shapes, vertex positions, face-pairings, plane equations,
+    # generator info
+    add_r13_geometry(mcomplex,
+                     manifold,
+                     verified=verified, bits_prec=bits_prec)
+    # Add tet.filling_matrix
+    add_filling_information(mcomplex, manifold)
+    # Add tet.core_curve
+    add_r13_core_curves(mcomplex, manifold)
+    # Add ideal triangles in tet.R13_triangles
+    add_triangles_to_tetrahedra(mcomplex)
+
+    # Pick disjoint/embedded cusp neighborhoods and tubes about core curves
+    # avoiding the incenter of each tetrahedron.
+    _add_and_scale_cusp_cross_section(mcomplex)
+
+    # Scale tet.R13_vertices to correspond to the just chosen horotriangles
+    scale_vertices_from_horotriangles(mcomplex)
+
+    # Construct spine.
+    add_spine(mcomplex)
+
+    return mcomplex
+
+def _add_and_scale_cusp_cross_section(mcomplex : Mcomplex):
+    """
+    Pick disjoint/embedded cusp neighborhoods and tubes about core curves
+    avoiding the incenter of each tetrahedron.
+
+    Also store scaling factor for a horotriangle to be inside the chosen
+    tube about a core curve in inverse_scale_to_be_inside_tube.
+    """
+
+    c = ComplexCuspCrossSection(mcomplex)
+    c.add_structures(one_cocycle='develop')
+
+    # Develop vertices in C for incomplete cusps.
+    c.add_vertex_positions_to_horotriangles()
+    # The similarities about some point in C. But we want to work with
+    # similarities of C^*, so move.
+    c.move_fixed_point_to_zero()
+
+    c.scale_triangles_to_avoid_standard_tubes()
+
+    _scale_cusp_cross_section(c)
+
+def _scale_cusp_cross_section(c : ComplexCuspCrossSection):
+    """
+    Scale horotriangles. That is scale all horotriangles belonging to
+    the same (complete or filled) cusp by the same factor.
+
+    We scale them such that the regions the horotriangles cut off a
+    particular tetrahedron are disjoint and don't cut-off the incenter.
+
+    Also compute the radius of the corresponding tube about the core curve
+    (that is contained inside the the regions we cut off and thus embedded
+    and disjoint from the other tubes or cusp neighborhoods).
+    """
+
+    # Cusp areas we start with. For a filled cusp, this is the area of the
+    # horotriangles that touch a standard tube about the core curve.
+    original_cusp_areas = c.cusp_areas()
+    # Maximal areas to avoid incenters of the tetrahedra
+    max_areas = [ area * (c.compute_scale_to_avoid_incenter(v) ** 2)
+                  for v, area in zip(c.mcomplex.Vertices, original_cusp_areas) ]
+    cusp_area_matrix = (
+        triangulation_dependent_cusp_area_matrix_from_cusp_cross_section(c))
+    # Adjust the diagonal entries so that the incenter of a tetrahedron
+    # cannot be in a cusp neighborhoods/ horotriangles outside a tube about
+    # a core curve.
+    incenter_cusp_area_matrix = _min_matrix(cusp_area_matrix, max_areas)
+    cusp_areas = (
+        unbiased_cusp_areas_from_cusp_area_matrix(incenter_cusp_area_matrix))
+    c.normalize_cusps(cusp_areas)
+
+    # Compute (lower bound) on radius of tubes about core curves that are
+    # embedded/disjoint from the cusp neighborhoods.
+    for i, cusp in enumerate(c.mcomplex.Vertices):
+        if cusp.is_complete:
+            continue
+        cusp_area_scale = cusp_areas[i] / original_cusp_areas[i]
+        cusp_scale = cusp_area_scale.sqrt()
+        cusp.core_curve_tube_radius = cusp_scale.arcsinh()
+
+def _min_matrix(m, diag_sqrt):
+    """
+    Compute new matrix by replacing the diagonal.
+
+    A new diagonal entry will be computed by taking the minimum of the
+    old entry and the square of the corresponding entry in diag_sqrt.
+    """
+
+    n = len(diag_sqrt)
+
+    return make_matrix(
+        [ [
+            m[i,j] if i != j
+            else correct_min([diag_sqrt[i] ** 2, m[i, j]])
+            for j in range(n)]
+          for i in range(n)])