snappy 3.2__cp310-cp310-macosx_10_12_x86_64.whl

snappy/drilling/peripheral_curves.py

@@ -0,0 +1,210 @@
+from ..snap.t3mlite import Mcomplex
+from ..snap.t3mlite import simplex, Tetrahedron
+
+from collections import deque
+
+from typing import Dict
+
+
+def install_peripheral_curves(start_tet : Tetrahedron) -> None:
+    """
+    Given a suitable base tetrahedron in the complex obtained by
+    crushing edges in the barycentric subdivision, compute a new
+    meridian and longitude.
+    """
+
+    # Also see notes about orientation below.
+    _install_meridian(start_tet)
+
+    # Longitude computed as curve intersecting meridian once, so
+    # we need to compute meridian first.
+    _install_longitude(start_tet)
+
+
+def _walk_face(tet : Tetrahedron, ml : int, f : int) -> Tetrahedron:
+    """
+    Input is a tetrahedron, a number ml saying whether we want to
+    set the meridian or longitude and a t3mlite.simplex-style
+    face not equal to simplex.F0.
+
+    Add piece to peripheral curve to cusp triangle about vertex 0
+    corresponding to walking across the given face. Returns
+    tetrahedron after crossing the given face.
+    """
+
+    tet.PeripheralCurves[ml][tet.orientation][simplex.V0][f] = +1
+    tet = tet.Neighbor[f]
+    tet.PeripheralCurves[ml][tet.orientation][simplex.V0][f] = -1
+
+    return tet
+
+
+def _install_meridian(start_tet : Tetrahedron) -> None:
+    # Before the barycentric subdivision, we can just pick a loop
+    # about one of the edges making up the geodesic (or closed
+    # simple curve isotopic to the geodesic) as meridian.
+    #
+    # Imagine a cusp triangle at one end of the edge in a tetrahedron
+    # adjacent to the edge. After the barycentric subdivision, the
+    # cusp triangle will be divided like this:
+    #
+    #                        1
+    #                       /|\
+    #                      / | \
+    #                     /  |  \
+    #                    /   |   \
+    #                   2*   |   *2
+    #                  /   * | *   \
+    #                 / c    3      \
+    #                /     * | *     \
+    #               /    *   |   *    \
+    #              /   *     |     *   \
+    #             /  *   c   |   b   *  \
+    #            / *         |         * \
+    #           1------------2------------1
+    #
+    # The subtriangles c are crushed, but crush_geodesic_pieces has
+    # given us the subtetrahedron associated with subtriangle b. Thus,
+    # we can trace a meridian by going around the crushed subtriangles.
+    # That is, starting from the given subtetrahedron, we go through
+    # face 2, then 1, then 2, and then 3 (crossing to what used to be
+    # the next tetrahedron about the crushed edge) and so on until we
+    # are back at the given subtetrahedron.
+
+    tet = start_tet
+    while True:
+        for f in [ simplex.F2, simplex.F1, simplex.F2, simplex.F3 ]:
+            tet = _walk_face(tet, 0, f)
+        if tet is start_tet:
+            break
+
+
+def _has_meridian(tet : Tetrahedron) -> bool:
+    for sheet in tet.PeripheralCurves[0]:
+        for v in sheet[simplex.V0].values():
+            if v != 0:
+                return True
+    return False
+
+
+def _walk_tet_to_face(start_tet : Tetrahedron,
+                      tet_to_face : Dict[Tetrahedron, int]) -> None:
+    tet = start_tet
+    while True:
+        tet = _walk_face(tet, 1, tet_to_face[tet])
+        if tet is start_tet:
+            break
+
+
+def _install_longitude(start_tet : Tetrahedron):
+    """
+    Uses the meridian installed with _install_meridian to
+    find a curve crossing the meridian once.
+    """
+
+    # The following figure shows the meridian installed by
+    # _install_meridian in the vertex link.
+    # M denotes the meridian and tet1 is the peripheral
+    # base subtetetrahedron.
+    #
+    #                 1
+    #                / \
+    #               /   \
+    #              /     \
+    #             /     M \
+    #            /    M    \
+    #           /     M     \
+    #          /      M      \
+    #         2---------------3---------------1
+    #        / \      M tet1 / \             /
+    #       /   \     M     /   \           /
+    #      /     \    L  M /     \         /
+    #     /      L\      L/LM     \       /
+    #    /    L    \     /   LML   \     /
+    #   /           \   /     M     \   /
+    #  /    tet2     \ / tet0 M      \ /
+    # 3---------------1---------------2
+    #                / \      M      /
+    #               /   \     M     /
+    #              /     \    M    /
+    #             /       \ M     /
+    #            /      M  \     /
+    #           /     M     \   /
+    #          /      M      \ /
+    #         2---------------3
+    #
+    # We start our longitude by traversing tet0, tet1 and tet2.
+    #
+    # To close it to a loop, we look for a path out from tet0 to tet2
+    # traversing only those cusp triangles not containing the meridian
+    # (maybe we should say: we are allowed to jump into a cusp triangle
+    # if it does not contain the meridian to go from tet0 to tet2 -
+    # since the very first piece of the path from tet0 to tet2 is in
+    # a cusp triangle that the meridian crosses).
+    #
+    # We find that path trough breadth-first search.
+
+    tet0 = start_tet
+    tet1 = start_tet.Neighbor[simplex.F2]
+    tet2 = tet1.Neighbor[simplex.F3]
+
+    if not _has_meridian(tet0):
+        raise Exception(
+            "start_tet expected to have meridian.")
+    if not _has_meridian(tet1):
+        raise Exception(
+            "F2-neighbor of start_tet expected to have meridian.")
+    if _has_meridian(tet2):
+        raise Exception(
+            "F3-enighbor of F2-neighbor of start_tet not expected to have "
+            "meridian.")
+
+    # For a tetrahedron stores the face through which this face was
+    # first reached. Thus, we can later trace back a path to the starting
+    # tetrahedron.
+    visited_tet_to_face = { tet1 : simplex.F3 }
+    pending_tets = deque([( tet0, simplex.F2)])
+    while True:
+        tet, entry_f = pending_tets.popleft()
+        if tet in visited_tet_to_face:
+            continue
+        visited_tet_to_face[tet] = entry_f
+        if tet is tet2:
+            break
+        for f in [ simplex.F1, simplex.F2, simplex.F3 ]:
+            neighbor = tet.Neighbor[f]
+            if f != entry_f and not _has_meridian(neighbor):
+                pending_tets.append((neighbor, f))
+
+    _walk_tet_to_face(start_tet, visited_tet_to_face)
+
+# Notes on orientation
+#
+# We want to pick a longitude that is parallel (vs anti-parallel) to the
+# drilled curve. That is, when embedding the drilled manifold into the
+# undrilled manifold, the longitude is isotopic to the given geodesic.
+#
+# We also want to pick a meridian such that the orientations of the meridian,
+# longitude and manifold are consistent according to the SnapPea kernel
+# conventions (ideally, but not strictly necessary: if we flipped the
+# meridian, the SnapPea kernel would actually flip it back).
+#
+# An important piece of achieving this is in crush.py where a subtetrahedron
+# is picked as peripheral base. Picking that subtetrahedron both checks
+# the orientation of the subtetrahedron with respect to the manifold and
+# the orientation of its 0-1 edge with respect to the drilled geodesic
+# are consistent. See _find_perm_for_piece.
+#
+# Several tests check that the orientation of the longitude is indeed correct.
+#
+# Checking that the meridian is picked correctly here cannot be done through
+# tests since the SnapPea kernel can flip the meridian to make its orientation
+# consistent with the longitude and manifold.
+#
+# To check the meridian, it is thus necessary to add printf's into the kernel
+# and exercise Manifold.drill_word. The two if-branches where the kernel is
+# flipping the meridian and that should not be executed are:
+#
+#   "if (tet->cusp[v]->intersection_number[L][M] == -1)" in orient.c and
+#   "if (tet->cusp[i]->intersection_number[L][M] == -1)" in peripheral_curves.c
+#

snappy/drilling/perturb.py

@@ -0,0 +1,188 @@
+from . import constants
+from . import epsilons
+from . import exceptions
+
+from ..geometric_structure.geodesic.tiles_for_geodesic import compute_tiles_for_geodesic
+from ..geometric_structure.geodesic.geodesic_start_point_info import GeodesicStartPointInfo
+from ..geometric_structure.geodesic.check_away_from_core_curve import check_away_from_core_curve_iter
+from ..hyperboloid import ( # type: ignore
+    unit_time_vector_to_o13_hyperbolic_translation,
+    r13_dot,
+    time_r13_normalise)
+from ..hyperboloid.line import R13Line
+from ..hyperboloid.distances import distance_r13_lines, distance_r13_points
+from ..tiling.triangle import add_triangles_to_tetrahedra
+from ..snap.t3mlite import Mcomplex # type: ignore
+from ..exceptions import InsufficientPrecisionError # type: ignore
+from ..matrix import make_vector # type: ignore
+from ..math_basics import correct_min # type: ignore
+
+from typing import Sequence, Tuple, List, Any
+
+# For perturbing, it is sufficient to just find some non-trivial
+# lower bound for the embedding radius of a tube about a geodesic.
+# To just any such bound, set _tube_developing_radius = 0.
+# This will develop the tube just to the point where we can verify
+# that it has positive radius.
+#
+# To stress-test our code, we can develop the tube further, by
+# setting _tube_developing_radius > 0. The isotopy type of
+# the drilled curve will not change no matter how large
+# _tube_developing_radius is. In other words, we still compute
+# a lower bound for the embedding radius which eventually will
+# be the embedding radius up to rounding errors as
+# _tube_developing_radius increases.
+#
+_tube_developing_radius = 0
+
+def perturb_geodesics(
+        mcomplex : Mcomplex,
+        geodesics : Sequence[GeodesicStartPointInfo],
+        verbose=False):
+    """
+    Given a triangulation with structures added by add_r13_geometry
+    and GeodesicStartPointInfo's with start points on the line that is a lift
+    of the closed geodesic, perturbs the start point away from the line
+    and computes a new end point (as image of the new start point under
+    the matrix associated to the geodesic line). The line segment
+    from the start point to the end point forms a simple closed
+    curve in the manifold which is guaranteed to be isotopic to the
+    closed geodesic.
+
+    If several GeodesicStartPointInfo's are given and/or there are filled
+    cusps with core curves, the system of simple closed curves
+    resulting from the perturbation together with the core curves
+    is guaranteed to be isotopic to the original system of closed
+    geodesics together with the core curves.
+
+    Through the perturbation, the simple closed curve should avoid
+    the 1-skeleton (more precision might be required to see this).
+    In particular, the start point should be in the interior of
+    a tetrahedron and trace_geodesic should succeed.
+    An example where trace_geodesic would not succeed without
+    perturbation is e.g., the geodesic 'a' in m125 which lies entirely
+    in the 2-skeleton.
+    """
+
+    if mcomplex.verified:
+        epsilon = 0
+    else:
+        epsilon = epsilons.compute_tube_injectivity_radius_epsilon(mcomplex.RF)
+
+    # Compute a lower bound for the maximal distance we can
+    # perturb the start points before we might change the isotopy class.
+    #
+    r = compute_lower_bound_injectivity_radius(mcomplex, geodesics)
+
+    if verbose:
+        print("Tubes lower bound injectivity radius:", r)
+
+    # If the distance between two different closed geodesics or
+    # between two different lifts of the same geodesic (that is the
+    # closed geodesic is not simple) or between
+    # a closed geodesic and a core curve is zero, raise exception that
+    # the system is not simple.
+    if not r > epsilon:
+        raise exceptions.GeodesicSystemNotSimpleError(r)
+
+    # Perturb each geodesic using above amount
+    for g in geodesics:
+        perturb_geodesic(g, r, mcomplex.verified)
+
+def compute_lower_bound_injectivity_radius(
+        mcomplex : Mcomplex,
+        geodesics : Sequence[GeodesicStartPointInfo]):
+
+    if len(geodesics) == 0:
+        raise Exception("No geodesic tubes given")
+    
+    add_triangles_to_tetrahedra(mcomplex)
+
+    min_radius = mcomplex.RF(_tube_developing_radius)
+
+    distances = []
+
+    tet_to_lines : List[List[R13Line]] = [[] for tet in mcomplex.Tetrahedra ]
+
+    core_curve_epsilon = _compute_core_curve_epsilon(mcomplex)
+
+    for geodesic in geodesics:
+        for tile in (
+                check_away_from_core_curve_iter(
+                    compute_tiles_for_geodesic(mcomplex, geodesic),
+                    epsilon=core_curve_epsilon,
+                    obj_name='Geodesic %s' % geodesic.word)):
+            if tile.lower_bound_distance > min_radius:
+                distances.append(tile.lower_bound_distance)
+                break
+            tet_index = tile.lifted_tetrahedron.tet.Index
+            tet_to_lines[tet_index].append(
+                tile.inverse_lifted_geometric_object)
+
+    for tet in mcomplex.Tetrahedra:
+        for curve in tet.core_curves.values():
+            tet_to_lines[tet.Index].append(curve.r13_line)
+
+    for r13_lines in tet_to_lines:
+        for i, r13_line0 in enumerate(r13_lines):
+            for r13_line1 in r13_lines[:i]:
+                distances.append(distance_r13_lines(r13_line0, r13_line1))
+
+    return correct_min(distances) / 2
+
+
+def perturb_geodesic(geodesic : GeodesicStartPointInfo,
+                     injectivity_radius,
+                     verified : bool):
+    if geodesic.line is None:
+        raise ValueError("GeodesicStartPointInfo needs line to be perturbed.")
+
+    perturbed_point = perturb_unit_time_point(
+        time_r13_normalise(geodesic.unnormalised_start_point),
+        max_amt=injectivity_radius,
+        verified=verified)
+
+    m = geodesic.line.o13_matrix
+
+    geodesic.unnormalised_start_point = perturbed_point
+    geodesic.unnormalised_end_point = m * perturbed_point
+    geodesic.line = None
+
+    geodesic.find_tet_or_core_curve()
+
+
+def perturb_unit_time_point(point, max_amt, verified : bool):
+
+    RF = point.base_ring()
+
+    amt = RF(0.5) * max_amt
+    direction = make_vector(
+        [RF(x) for x in constants.point_perturbation_direction])
+    perturbed_origin = make_vector(
+        [ amt.cosh() ] + list(amt.sinh() * direction.normalized()))
+
+    m = unit_time_vector_to_o13_hyperbolic_translation(point)
+    perturbed_point = m * perturbed_origin
+
+    if not verified:
+        return perturbed_point
+
+    space_coords = [ RF(x.center()) for x in perturbed_point[1:4] ]
+    time_coord = sum((x**2 for x in space_coords), RF(1)).sqrt()
+    perturbed_point = make_vector([time_coord] + space_coords)
+
+    d = distance_r13_points(point, perturbed_point)
+    if not d < RF(0.75) * max_amt:
+        raise InsufficientPrecisionError(
+            "Could not verify perturbed point is close enough to original "
+            "start point. "
+            "Increasing the precision will probably fix this.")
+
+    return perturbed_point
+
+def _compute_core_curve_epsilon(mcomplex):
+    if mcomplex.verified:
+        return 0
+    else:
+        RF = mcomplex.RF
+        return RF(0.5) ** (RF.prec() // 2 - 8)

snappy/drilling/shorten.py

@@ -0,0 +1,36 @@
+from .cusps import CuspPostDrillInfo
+from .barycentric import transpositions, perm_to_index, mark_subtetrahedra_about_edge
+
+from ..snap.t3mlite import Tetrahedron, Perm4, simplex
+
+
+def shorten_in_barycentric_subdivision(tetrahedra, verbose : bool = False):
+    while shorten_one_in_barycentric_subdivision(tetrahedra):
+        if verbose:
+            print("Shortening geodesic by sweeping across triangle.")
+
+def shorten_one_in_barycentric_subdivision(tetrahedra):
+    for tet in tetrahedra:
+        for perm, orientation in zip(Perm4.S4(), tet.marked_subtetrahedra):
+            if orientation != +1:
+                continue
+            other_perm = perm * transpositions[1]
+            j = perm_to_index(other_perm)
+            if tet.marked_subtetrahedra[j] == 0:
+                continue
+            mark_subtetrahedra_about_edge(tet, perm, 0)
+            mark_subtetrahedra_about_edge(tet, other_perm, 0)
+            new_perm = perm * Perm4((1,2,0,3))
+            mark_subtetrahedra_about_edge(tet, new_perm)
+            _remove_post_drill_info_from_vertex(tet, perm.image(simplex.V0))
+            return True
+    return False
+
+def _remove_post_drill_info_from_vertex(tet, v):
+    if tet.post_drill_infos[v].index is None:
+        return
+    tet.post_drill_infos[v] = CuspPostDrillInfo()
+    for f in simplex.FacesAroundVertexCounterclockwise[v]:
+        _remove_post_drill_info_from_vertex(
+            tet.Neighbor[f],
+            tet.Gluing[f].image(v))