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

snappy/drilling/subdivide.py

@@ -0,0 +1,274 @@
+from .moves import one_four_move, two_three_move
+from .tracing import GeodesicPiece, GeodesicPieceTracker
+
+from . import debug
+
+from ..snap.t3mlite import Mcomplex, Tetrahedron
+
+from typing import Sequence, Dict
+
+
+def traverse_geodesics_to_subdivide(
+        mcomplex : Mcomplex,
+        all_pieces : Sequence[Sequence[GeodesicPiece]]) -> Sequence[Tetrahedron]:
+    """
+    The function expects a triangulation and a list of list of geodesic pieces
+    where each list was generated by calling trace_geodesic on the same
+    triangulation. That is, the pieces of each list form a simple closed curve in
+    the manifold that is geodesic except for one point. See trace_geodesic for
+    further details on the input. Note that the function corrupts its input
+    data.
+
+    The function returns a list of tetrahedra that form a triangulation that is
+    isometric to the given triangulation and such that the above simple closed
+    curves all embed into the 1-skeleton. The triangulation will have ideal and
+    finite vertices (that will be assigned light-like and (unnormalized)
+    time-like vectors, respectively by tet.R13_vertices).
+
+    An edge E of the new triangulation is part of one of the above simple
+    closed curves if there is a pair of a tetrahedron tet and an edge e in that
+    tetrahedron representing E and there is a GeodesicPiece in
+    tet.geodesic_pieces with endpoints being the endpoints of e.
+    """
+
+    # We perform _traverse_geodesic_to_subdivide for each of the given simple
+    # closed curves. A call to _traverse_geodesic_to_subdivide will use
+    # 1-4 and 2-3 move to introduce finite vertices and edges connecting them
+    # so that the given simple curve can be embedded into the 1-skeleton.
+    #
+    # While the details of this process are described in
+    # _traverse_geodesic_to_subdivide, we describe here the nature of the
+    # data structure to represent the intermediate triangulations with
+    # line segments embedded in tetrahedra (that is GeodesicPiece's).
+    #
+    # We actually do not explicitly store the set or list of tetrahedra
+    # and line segments making up the intermediate triangulations and
+    # simple closed curves, respectively here. Instead, we just keep pointers to
+    # some GeodesicPiece's and rely on the fact that the triangulation
+    # and each simple closed curve is connected and we can find all
+    # tetrahedra and pieces by traversal.
+    #
+    # The traversal uses that:
+    # Each tetrahedron tet points to its four neighbors through tet.Neighbors.
+    # Each tetrahedron tet points to all line segments embedded in it
+    # through tet.geodesic_pieces.
+    # Each GeodesicPiece points back to the tetrahedron where the line
+    # segment it represents is embedded in.
+    # Each GeodesicPiece also has a pointer to the previous and next
+    # GeodesicPiece in the simple closed curves. In other words, we have
+    # a cyclically linked list of GeodesicPiece's.
+    #
+    # Note that the 1-4 and 2-3 moves will replace tetrahedra and
+    # GeodesicPiece's with other tetrahedra and GeodesicPiece's.
+    #
+    # Thus, in general, it is not safe to keep a pointer to a tetrahedron
+    # or GeodesicPiece around.
+    #
+    # The only exception are the "unprocessed" start pieces of the
+    # simple closed curves. That is the first piece of a simple closed
+    # curve before the simple closed curve became part of the 1-skeleton
+    # through _traverse_geodesic_to_subdivide. Recall from trace_geodesic
+    # that such a start piece starts in the interior of a tetrahedron and
+    # ends at one of the faces of the tetrahedron. The code in the 1-4 and
+    # 2-3 moves has special logic to detect pieces of this nature. For
+    # such a piece, it actually modifies the GeodesicPiece in place
+    # rather than replacing it with one or several other GeodesicPiece's
+    # like it does for non-start GeodesicPiece's.
+    #
+    # Thus, we can store all start pieces here and iterate through them
+    # (a start piece will be valid until we have given it to
+    # _traverse_geodesic_to_subdivide but not after).
+
+    # Add pointers to the geodesic pieces to the respective tetrahedra.
+    for tet in mcomplex.Tetrahedra:
+        tet.geodesic_pieces = []
+    for pieces in all_pieces:
+        for piece in pieces:
+            piece.tet.geodesic_pieces.append(piece)
+
+    # Store all start pieces.
+    trackers = [ GeodesicPieceTracker(pieces[0]) for pieces in all_pieces ]
+
+    for tracker in trackers:
+        debug.check_consistency_segments(
+            debug.flatten_link_list(tracker.geodesic_piece))
+
+    # Iterate through start pieces.
+    for tracker in trackers:
+        # Make 1-skeleton contain the simple closed curve starting with
+        # the start piece.
+        last_piece : GeodesicPiece = _traverse_geodesic_to_subdivide(
+            tracker.geodesic_piece, mcomplex.verified)
+
+    # At this point, all start pieces have been processed and all elements
+    # of start_pieces are invalid. Luckily, _traverse_geodesic_to_subdivide
+    # gives us a valid GeodesicPiece we can use for traversal.
+
+    return _find_and_index_all_tetrahedra(last_piece.tet)
+
+
+def _traverse_geodesic_to_subdivide(
+        start_piece : GeodesicPiece,
+        verified : bool) -> GeodesicPiece:
+
+    debug.check_consistency_2(start_piece)
+
+    # We introduce the following notation for the current state
+    # of the GeodesicPiece's that are cyclically linked to form
+    # the simple closed curve that we are currently processing:
+    #
+    # start_piece.prev
+    #    v
+    # F-F-T-F-...-F-
+    #      ^
+    #   start_piece
+    #
+    # X-Y denotes a GeodesicPiece where X and Y are V, F, or T to
+    # indicate whether the start or end point, respectively, is
+    # a vertex, on a face or in the interior of a tetrahedron.
+    #
+    # Since we have V = X for two consecutive pieces U-V X-Y, we
+    # abbreviate to U-X-Y.
+    #
+    # Furthermore, since drawing circles in ASCII art is difficult,
+    # X- indicates that we wrap back to the first letter in a line.
+    #
+    # "v" over a piece and "^" under a piece means that is currently
+    # pointed to by a variable we are interested in where the name
+    # the variable if it is not just "piece".
+
+    # Following trace_geodesic, we start with
+    #
+    #    start_piece.prev
+    #           v
+    #        F-F-T-F-F-...-F-
+    #             ^
+    #         start_piece
+
+    end_piece, piece = one_four_move(
+        [start_piece.prev, start_piece],
+        verified)
+
+    # The first 1-4 move creates a vertex for the point where the
+    # simple closed curve starts and ends:
+    #
+    #       end_piece
+    #           v
+    #        F-F-V-F-F-...-F-
+    #             ^
+
+    debug.check_consistency_2(piece)
+
+    while True:
+        # When entering the curve, we have
+        #
+        #
+        #       V-...-V-F-...-F-
+        #              ^
+        # Note that there is only a single V if the curve
+        # runs for the first time. And there might be only
+        # a single F if we are about to finish.
+
+        # Proceed to the next piece.
+        piece = piece.next_
+
+        # We now have a different picture depending on whether
+        # there was only a single F.
+
+        if piece.is_face_to_vertex():
+
+            # We have
+            #
+            #       prev.piece
+            #            v
+            #     V-...-V-F-V-...-V-
+            #              ^
+            #
+            # We can now achieve the goal by a single 2-3 move:
+            # prev.piece and piece will turn into a single new piece
+            # that is the edge created by the 2-3 move - the face
+            # common to the tetrahedra containing prev.piece and piece
+            # has disappeared.
+
+            piece = two_three_move([piece.prev, piece], verified)
+            debug.check_consistency_2(piece)
+
+            # The entire simple closed curve consists of edges of
+            # tetrahedra.
+            #
+            #      V-...-V-V-...-V-
+            #             ^
+            #
+            # We are done.
+
+            return piece
+
+        # We have
+        #
+        #      V-...-V-F-F-...-F-
+        #               ^
+        #
+        # We pick a point on the geodesic piece and use it as vertex
+        # for a 1-4 move.
+
+        piece, next_piece = one_four_move([piece], verified)
+
+        debug.check_consistency_2(piece)
+
+        # We have
+        #
+        #    piece.prev   next_piece
+        #             v   v
+        #      V-...-V-F-V-F-...-F-
+        #               ^
+        #
+        # Remark: The current piece might not be the only geodesic
+        # piece (of this simple closed curve) going through the tetrahedron.
+        # The 1-4 move will split these other pieces into several piece.
+        # But the pieces will be again F-F. And the process still finishes
+        # in finite time. Similar for the 2-3 move.
+        #
+        # We perform a 2-3 move, see also above description.
+
+        piece = two_three_move([piece.prev, piece], verified)
+        debug.check_consistency_2(piece)
+
+        # We have
+        #
+        #      V-...-V-V-F-...-F-
+        #             ^
+        #
+        # Move to the next piece.
+
+        piece = piece.next_
+
+        # We have
+        #
+        #      V-...-V-V-F-...-F-
+        #               ^
+        #
+        # Start next iteration.
+
+
+def _find_and_index_all_tetrahedra(tet : Tetrahedron):
+    """
+    Recursively traverses neighbors of the given Tetrahedron
+    to find all tetrahedra tet in the connected component.
+
+    Assigns tet.Index to them.
+    """
+    result = []
+    pending_tets = [tet]
+    visited_tets = set()
+    i = 0
+    while pending_tets:
+        tet = pending_tets.pop()
+        if tet not in visited_tets:
+            visited_tets.add(tet)
+            tet.Index = i
+            i += 1
+            result.append(tet)
+            for neighbor in tet.Neighbor.values():
+                pending_tets.append(neighbor)
+
+    return result

snappy/drilling/test.py

@@ -0,0 +1,23 @@
+from snappy import testing
+import snappy
+
+from snappy import drilling
+import snappy.drilling.test_cases
+
+modules = [
+    drilling,
+    drilling.test_cases
+]
+
+def run_doctests(verbose=False, print_info=True):
+    globs = {'Manifold'  : snappy.Manifold,
+             'ManifoldHP': snappy.ManifoldHP}
+    return testing.doctest_modules(modules,
+                                   verbose=verbose,
+                                   print_info=print_info,
+                                   extraglobs=globs)
+
+run_doctests.__name__ = drilling.__name__
+
+if __name__ == '__main__':
+    testing.run_doctests_as_main(run_doctests)

snappy/drilling/test_cases.py

@@ -0,0 +1,126 @@
+"""
+IMPORTANT: Python only recognises this as a doc string if there is
+nothing before it. In particular, add any includes after the doc string.
+
+Test with manifold without symmetry. Note that the code in drilling is
+deterministic but the SnapPea kernel code to remove the finite vertices
+and simplify is not. Thus, we need canonical_retriangulation() to get
+a consistent result:
+
+    >>> from snappy.drilling.exceptions import GeodesicSystemNotSimpleError
+    >>> M = Manifold("v2986")
+    >>> M.drill_word('gB').canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'kLvvAQQkbhijhghgjijxxacvcccccv_baBaaBDbBa'
+
+Test non-simple geodesic and verified computation:
+
+    sage: M = ManifoldHP("m004")
+    sage: try:
+    ...       M.drill_word('bbCC', verified = True)
+    ... except GeodesicSystemNotSimpleError as e:
+    ...     print("Not simple")
+    Not simple
+
+Tests drilling one geodesic that intersects 1-skeleton::
+
+    >>> M = Manifold("m125")
+    >>> M.drill_word('d').canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'svLvLQLAzQMMQdifhjmlknlopnqpqrrroaaaaaaoaaaaaaoaaao_aBbaBaaBeDBb'
+
+Tests drilling two geodesics that intersect each other:
+
+    >>> try: # doctest: +NUMERIC9
+    ...     M.drill_words(['d','Ad'])
+    ... except GeodesicSystemNotSimpleError as e:
+    ...     print("Max tube radius:", e.maximal_tube_radius)
+    Max tube radius: 0.0000000000
+
+Tests drilling geodesics that are entirely in the 2-skeleton::
+
+    >>> M.drill_words(['a','acAADa']).canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'ivvPQQcfhghgfghfaaaaaaaaa_BabBBbBaBBbabbab'
+
+Same test as verified computation::
+
+    sage: M.drill_words(['a','acAADa'], verified = True).canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'ivvPQQcfhghgfghfaaaaaaaaa_BabBBbBaBBbabbab'
+
+Test error when drilling something close to core curve::
+
+    >>> M = Manifold("m125")
+    >>> MM = M.drill_word('d')
+    >>> MM.dehn_fill((1,0),2)
+    >>> bad_word = 'bc'
+    >>> MM.drill_word(bad_word) # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    snappy.geometric_structure.geodesic.check_away_from_core_curve.ObjectCloseToCoreCurve: Geodesic bc is very close to the core curve of cusp 2 and might intersect it. Distance: ...
+
+There are two places where we detect whether the geodesic is close
+to a core curve (rather than tiling forever). Test the other place
+in the GeodesicTube code used to determine the maximal amount we can
+perturb the geodesic:
+
+    >>> drill_words_implementation(MM, [bad_word], verified = False, bits_prec = 53, perturb = True) # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    snappy.geometric_structure.geodesic.check_away_from_core_curve.ObjectCloseToCoreCurve: Geodesic bc is very close to the core curve of cusp 2 and might intersect it. Distance: ...
+
+A particular tricky case in terms testing that the start piece is correctly
+handled by 2-3 moves (in particular, commit f9879d04 introduced a bug):
+
+    >>> Manifold("m004").drill_words(['CAC','CCbC']).canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'qLvvLvAMQQQkcgimopkllmpkonnnpixcaelchapewetvrn_bcaaBbBBbaBaBbB'
+
+
+An interesting case where geodesic intersects triangulation in only one tetrahedron:
+
+    >>> Manifold("m019").drill_word('A').canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    'gLLPQccdefffqffqqof_BaaBdcbb'
+
+A bug in an earlier implementation found by Nathan Dunfield (where putting the words in one order caused a failure):
+
+    >>> import sys
+    >>> original_limit = sys.getrecursionlimit()
+    >>> sys.setrecursionlimit(100000)
+    >>> def drilled_isosig(M, words):
+    ...     for i in range(10):
+    ...         try:
+    ...             F = M.drill_words(words).filled_triangulation()
+    ...             return F.canonical_retriangulation().triangulation_isosig(ignore_orientation=False)
+    ...         except RuntimeError:
+    ...             pass
+    >>> drilled_isosig(Manifold('K11n34(0,1)'), ['iFcdbEiFJ', 'iFJ'])
+    'zLLvLLwzAwPQMQzzQkcdgijkjplssrnrotqruvwyxyxyhsgnnighueqdniblsipklpxgcr_BcbDbBba'
+    >>> drilled_isosig(Manifold('K11n34(0,1)'), ['iFJ', 'iFcdbEiFJ'])
+    'zLLvLLwzAwPQMQzzQkcdgijkjplssrnrotqruvwyxyxyhsgnnighueqdniblsipklpxgcr_babBbaBcaB'
+    >>> sys.setrecursionlimit(original_limit)
+
+Stress test by using large perturbation. In particular, this is testing the
+case where two geodesic pieces are adjacent to the same triangle and we
+need to shorten before crushing. We do white-box testing (verbose = True)
+to make sure we really hit the shortening case.
+
+    >>> from snappy.drilling import perturb
+    >>> original_radius = perturb._tube_developing_radius
+    >>> perturb._tube_developing_radius = 1
+    >>> Manifold("m307").drill_word('dadadabCdada', verbose=True).isometry_signature(of_link=True) # doctest: +NUMERIC9
+    Tubes lower bound injectivity radius: 0.380575727320247
+    Number of geodesic pieces: [9]
+    Number of tets after subdividing: 45
+    Shortening geodesic by sweeping across triangle.
+    'oLLwQvvPQQcbeefgemnllnmnmlhhaaaaaahaaaaah_bBbabaab'
+    >>> Manifold("m320").drill_word('daaacDA', verbose=True).isometry_signature(of_link=True) # doctest: +NUMERIC9
+    Tubes lower bound injectivity radius: 0.397319067589326
+    Number of geodesic pieces: [9]
+    Number of tets after subdividing: 49
+    Shortening geodesic by sweeping across triangle.
+    'rLLPwAPvvPQQcccdfehgjiqpooqppqoqffaaaaaaaqaaaqaaa_bBbabaab'
+    >>> perturb._tube_developing_radius = original_radius
+
+"""
+
+from . import drill_words_implementation
+
+if not __doc__:
+    raise Exception("doc string with tests was not recognized.")