snappy 3.2__cp311-cp311-macosx_10_12_x86_64.whl

snappy/exterior_to_link/hyp_utils.py

@@ -0,0 +1,112 @@
+def pos_tets(manifold):
+    return manifold.solution_type() == 'all tetrahedra positively oriented'
+
+
+def basic_improve_tri(manifold, tries=10):
+    M = manifold.copy()
+    for i in range(tries):
+        if pos_tets(M):
+            return M
+        M.randomize()
+    return manifold.copy()
+
+
+def improved_triangulation(manifold, tries=10):
+    M = basic_improve_tri(manifold, tries=tries)
+    if pos_tets(M):
+        return M
+
+    curves = M.dual_curves()
+    for i, c in zip(range(tries), curves):
+        D = M.drill(c)
+        D.dehn_fill((1, 0), M.num_cusps())
+        F = D.filled_triangulation()
+        if pos_tets(F):
+            return F
+
+    return manifold.copy()
+
+
+def is_isometric_to_with_effort(A, B, return_isometries=False, tries=10):
+    A = improved_triangulation(A, tries=tries)
+    B = improved_triangulation(B, tries=tries)
+    try:
+        return A.is_isometric_to(B, return_isometries=return_isometries)
+    except RuntimeError:  # SnapPea kernel failed
+        return []
+
+
+def orient_pres(isometry):
+    """
+    >>> M = Manifold('K4a1')
+    >>> kinds = {orient_pres(iso) for iso in M.is_isometric_to(M, True)}
+    >>> sorted(kinds)
+    [False, True]
+    """
+    return isometry.cusp_maps()[0].det() > 0
+
+
+def are_orient_pres_isometric_as_ordered_links(A, B):
+    """
+    All of the following manifolds isometric, but not as ordered links
+
+    >>> A = Manifold('L10n1')
+    >>> B = Manifold('L7a2')
+    >>> C = Manifold('L10n1')
+    >>> C._reindex_cusps([1, 0])
+    >>> are_orient_pres_isometric_as_ordered_links(A, B)
+    False
+    >>> are_orient_pres_isometric_as_ordered_links(A, C)
+    False
+    >>> are_orient_pres_isometric_as_ordered_links(C, C)
+    True
+    """
+    isos = is_isometric_to_with_effort(A, B, return_isometries=True)
+    isos = [iso for iso in isos if iso.extends_to_link() and orient_pres(iso)]
+    ident = list(range(A.num_cusps()))
+    return any(iso.cusp_images() == ident for iso in isos)
+
+
+def orientation_preserving_link_isometries(A, B, tries=100):
+    isos = is_isometric_to_with_effort(A, B, return_isometries=True, tries=tries)
+    ans = any(iso.extends_to_link() for iso in isos)
+    if not ans:
+        A, B = A.high_precision(), B.high_precision()
+        isos = is_isometric_to_with_effort(A, B, return_isometries=True, tries=tries)
+    good_isos = [iso for iso in isos if iso.extends_to_link() and orient_pres(iso)]
+    if good_isos:
+        return good_isos[0]
+
+
+def reorder_link_components(link, perm):
+    """
+    This link has three components, which are in order a trefoil, the
+    figure 8, and an unknot.
+
+    >>> L0 = Manifold('DT[uciicOFRTIQKUDsMpgBelAnjCH.000001011100110110010]').link()
+    >>> [len(L0.sublink([i]).crossings) for i in range(3)]
+    [3, 4, 0]
+
+    perm is the permutation of {0, 1, ... , num_comps - 1} where
+    perm[old_comp_index] = new_comp_index.
+
+    >>> L1 = reorder_link_components(L0, [1, 2, 0])
+    >>> [len(L1.sublink([i]).crossings) for i in range(3)]
+    [0, 3, 4]
+    >>> L2 = reorder_link_components(L0, [2, 0, 1])
+    >>> [len(L2.sublink([i]).crossings) for i in range(3)]
+    [4, 0, 3]
+    """
+    n = len(link.link_components)
+    assert len(perm) == n and link.unlinked_unknot_components == 0
+    L = link.copy()
+    component_starts = n * [None]
+    for a, b in enumerate(perm):
+        component_starts[b] = L.link_components[a][0]
+    L._build_components(component_starts)
+    return L
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod()

snappy/exterior_to_link/link_projection.py

@@ -0,0 +1,323 @@
+"""
+For a PL link in R^3, produce a link diagram by projecting it onto a
+plane (by default a randomly chosen one).  Also includes code for
+simplifying a PL link by basic straightening moves.
+"""
+
+import spherogram
+import random
+import itertools
+from . import pl_utils
+from .rational_linear_algebra import QQ, Matrix, Vector3
+from .exceptions import GeneralPositionError
+
+
+def fig8_points():
+    # Extracted from put_in_S3.example10, used for testing.
+    pts = [(1564, 148, 0, 1117), (765, 1137, 786, 1117), (1117, 1882, 1490, 1117),
+           (1469, 1137, 786, 1117), (698, 280, 0, 1117), (1166, 372, -744, 1117),
+           (1862, 372, -1440, 1117), (1514, 1068, -744, 1117), (380, 198, 0, 279),
+           (564, 604, 604, 559), (701, 219, 438, 1117), (-679, -241, 0, 1117),
+           (460, 679, -482, 1117)]
+    return [[Vector3([a, b, c])/d for a, b, c, d in pts]]
+
+
+def twist_knot_points():
+    """
+    The knot 5_2 = K5a1
+    """
+    pts = [(25, 36, 5), (14, 36, -3), (14, 14, 0), (47, 14, 0), (47, 25, 0),
+           (3, 25, 0), (3, 47, 0), (36, 47, -6), (36, 3, 4), (25, 3, -5)]
+    return [[Vector3(pt) for pt in pts]]
+
+
+def proj(point):  # projection onto z = 0
+    return Vector3([point[i] for i in [0,1]]+[0])
+
+
+def random_transform(steps=5):
+    """
+    Generators of SL(3, Z) from
+
+    https://doi.org/10.1090/S0002-9939-1992-1079696-5
+
+    >>> random_transform(5).det()
+    1
+    """
+    I = Matrix([[1, 0, 0], [0, 1, 0], [ 0, 0, 1]])
+    X = Matrix([[0, 1, 0], [0, 0, 1], [ 1, 0, 0]])
+    Y = Matrix([[1, 0, 1], [0, -1, -1], [ 0, 1, 0]])
+    Z = Matrix([[0, 1, 0], [1, 0, 0], [-1, -1, -1]])
+    # X and Y have order two and Z order three, so there are
+    # symmetric gens:
+    gens = [I, X, X*X, Y, Y*Y, Z, Z]
+    ans = I
+    for s in range(steps):
+        ans = ans * random.choice(gens)
+    return ans
+
+
+def norm_sq(v):
+    return sum(x**2 for x in v)
+
+
+def min_dist_sq(points):
+    pairs = itertools.combinations(points, 2)
+    return min(norm_sq(p - q) for p, q in pairs)
+
+
+def straightenable_tri(points, extra_arcs=None):
+    if extra_arcs is None:
+        extra_arcs = []
+    n = len(points)
+    for i in range(n):
+        indices = i, (i + 1) % n, (i + 2) % n
+        tri = [points[k] for k in indices]
+        other_arcs = [(points[k], points[(k+1) % n])
+                      for k in range(n) if k not in indices[:2]]
+        if pl_utils.colinear(*tri):
+            return indices
+        M = pl_utils.standardize_bend_matrix(*tri)
+        if all(pl_utils.can_straighten_bend(a, tri, False, M)
+               for a in other_arcs + extra_arcs):
+            return indices
+
+
+def arcs_from_points(points_list):
+    arcs = []
+    for p in points_list:
+        n = len(p)
+        arcs += [(p[k], p[(k+1) % n]) for k in range(n)]
+    return arcs
+
+
+def straighten_knot(points):
+    while True:
+        tri = straightenable_tri(points)
+        if tri:
+            a, b, c = tri
+            # We shuffle is so that we look for next triangle in less examined location
+            if a < b < c:
+                points = points[c:] + points[:b]
+            else:
+                points = points[:b] + points[b + 1:]
+        else:
+            break
+    return points
+
+
+def straighten_link(points_list):
+    for i in range(len(points_list)):
+        other_points = points_list.copy()
+        del other_points[i]
+        other_arcs = arcs_from_points(other_points)
+        while True:
+            points = points_list[i]
+            tri = straightenable_tri(points, other_arcs)
+            if tri:
+                a, b, c = tri
+                if a < b < c:
+                    points = points[c:] + points[:b]
+                else:
+                    points = points[:b] + points[b + 1:]
+            else:
+                break
+            points_list[i] = points
+    return points_list
+
+
+class Arc():
+    """
+    An arc from point a to point b where a and b are labeled by i and j.
+    """
+    def __init__(self, a, i, b, j, label):
+        self.a, self.i, self.b, self.j, self.label = a, i, b, j, label
+        self.proj = a[:2], b[:2]
+        self.crossings = []
+
+    def __getitem__(self, index):
+        return [self.a, self.b][index]
+
+    def add_crossing(self, crossing, t):
+        self.crossings.append((t, crossing))
+        try:
+            self.crossings.sort()
+        except TypeError:
+            raise GeneralPositionError('Two crossings on top of one another')
+
+
+class Crossing():
+    def __init__(self, over_arc, under_arc, s, t, label):
+        self.over, self.under, self.label = over_arc, under_arc, label
+        self.s, self.t = s, t
+        a, b = over_arc.proj
+        u, v = under_arc.proj
+        M = Matrix([b - a, v - u])
+        self.sign = 1 if M.det() > 0 else -1
+        e = 1e-12
+        assert (1 - s)*a + s*b == (1 - t)*u + t*v
+        assert ((e < s < 1 - e) and (e < t < 1 - e))
+        over_arc.add_crossing(self, s)
+        under_arc.add_crossing(self, t)
+
+
+class LinkProjection():
+    """
+    The idea is to apply a unimodular matrix and to project the knot
+    onto the z=0 plane. We then recover the crossing data by finding
+    points that intersect after projecting then taking the over
+    crossing to be the lift with larger z coord.
+
+    >>> pts = fig8_points()
+    >>> kp = LinkProjection(pts)
+    >>> K = kp.link()
+    >>> K.exterior().identify()
+    [m004(0,0), 4_1(0,0), K2_1(0,0), K4a1(0,0), otet02_00001(0,0)]
+
+    >>> M = Matrix([[0,1,1],[1,1,0],[0,0,2]])
+    >>> kp = LinkProjection(pts, M)
+    >>> K = kp.link()
+    >>> K.exterior().identify()
+    [m004(0,0), 4_1(0,0), K2_1(0,0), K4a1(0,0), otet02_00001(0,0)]
+
+    >>> kp = LinkProjection(twist_knot_points())
+    >>> K = kp.link()
+    >>> M = Manifold('K5a1')
+    >>> isos = M.is_isometric_to(K.exterior(), True)
+    >>> {iso.cusp_maps()[0].det() for iso in isos}
+    {1}
+    """
+
+    def __init__(self, points_by_component, mat=None):
+        # mat is a matrix, we transform the points by mat then project
+        # onto z = 0 plane, plane is point and vector
+        if mat is None:
+            mat = Matrix([[0, -2, -1], [1, 2, 2], [-1, 1, 0]])
+        self.mat = mat
+
+        components = []
+        for component_points in points_by_component:
+            start = sum(len(C) for C in components)
+            comp_len = len(component_points)
+            components.append(list(range(start, start + comp_len)))
+
+        self.components = components
+        all_points = sum(points_by_component, [])
+        self.points = [mat*p for p in all_points]
+        self.projected_points = [proj(p) for p in self.points]
+
+        # Check that nothing is too degenerate:
+        assert min_dist_sq(self.points) > 1e-15
+        if min_dist_sq(self.projected_points) < 1e-16:
+            raise GeneralPositionError('Projection is nearly degenerate')
+
+        self._setup_crossings()
+
+    def _setup_crossings(self):
+        # compute the over and under crossings of the link projection
+
+        pts = self.points
+        crossings, arcs = [], []
+        for component in self.components:
+            successive_pairs = [(c, component[(i + 1) % len(component)]) for
+                                 i, c in enumerate(component)]
+            arcs += [Arc(pts[i], i, pts[j], j, i) for i, j in successive_pairs]
+
+        for A, B in itertools.combinations(arcs, 2):
+            a = proj(A[0]), proj(A[1])
+            b = proj(B[0]), proj(B[1])
+
+            # When A and B are successive arcs, we just need to test
+            # things are sufficiently generic.
+
+            if A.j == B.i:
+                # assert not near_reverse(a[0], a[1], b[1])
+                continue
+            elif B.j == A.i:
+                # assert not near_reverse(b[0], b[1], a[1])
+                continue
+            elif pl_utils.segments_meet_not_at_endpoint(a, b):
+                # There is a crossing and now we figure out which arc
+                # crosses over the other.
+
+                # find the intersection point
+                M = Matrix([a[1]-a[0], b[0]-b[1]]).transpose()
+                if M.rank() != 2:
+                    raise GeneralPositionError('Segments overlap on their interiors')
+                s, t = M.solve_right(b[0]-a[0])
+                e = 1e-12
+                if not ((e < s < 1 - e) and (e < t < 1 - e)):
+                    raise GeneralPositionError('Intersection too near the end of one segment')
+
+                x_a = (1-s)*A[0] + s*A[1] # lift of intersection to A
+                x_b = (1-t)*B[0] + t*B[1] # lift of intersection to B
+
+                # make sure our lifts project to same point in plane
+                assert norm_sq(proj(x_a - x_b)) < 1e-5
+
+                # whichever arc contains the higher intersection
+                # lifted point is the over crossing arc
+                height_a = x_a[2]
+                height_b = x_b[2]
+
+                assert abs(height_a - height_b) > 1e-14
+                if height_a > height_b:
+                    crossings.append(Crossing(A, B, s, t, len(crossings)))
+                else:
+                    crossings.append(Crossing(B, A, t, s, len(crossings)))
+
+        self.crossings, self.arcs = crossings, arcs
+
+    def link(self):
+        # For bookkeeping, we use a Strand for each point the
+        # projection, together with the obviously needed crossings.
+
+        strands = [spherogram.Strand(label='S%d' % i)
+                   for i, p in enumerate(self.points)]
+        crossings = [spherogram.Crossing(label='C%d' % i)
+                     for i, c in enumerate(self.crossings)]
+
+        for arc in self.arcs:
+            A, a = strands[arc.i], 1
+            for t, C in arc.crossings:
+                B = crossings[C.label]
+                if arc == C.over:
+                    b = 3 if C.sign == 1 else 1
+                else:
+                    b = 0
+                # glue up
+                A[a] = B[b]
+                A, a = B, (b + 2) % 4
+
+            # glue to Strand corresponding to the endpoint of the arc.
+            B, b = strands[arc.j], 0
+            A[a] = B[b]
+
+        L = spherogram.Link(strands + crossings)
+        return L
+
+
+def project_to_diagram(link_in_R3):
+    """
+    >>> project_to_diagram(fig8_points())
+    <Link: 1 comp; 4 cross>
+    """
+    diagram = None
+    for mat_size in [None, 15, 25, 15, 25, 15, 25, 100, 250, 100, 250, 500, 500]:
+        if mat_size is None:
+            proj_mat = Matrix([[3, 1, 0], [1, -1, 5], [0, 0, -1]])
+        else:
+            proj_mat = random_transform(mat_size)
+        try:
+            projection = LinkProjection(link_in_R3, proj_mat)
+            diagram = projection.link()
+            break
+        except GeneralPositionError as e:
+            pass
+
+    return diagram
+
+
+if __name__ == '__main__':
+    import doctest
+    print(doctest.testmod())

snappy/exterior_to_link/main.py

@@ -0,0 +1,197 @@
+"""
+Defines the main function `exterior_to_link`.
+"""
+
+import random
+import typing
+from .exceptions import ExteriorToLinkError
+from .simplify_to_base_tri import good_simplification
+from . import put_in_S3
+from . import link_projection
+from .rational_linear_algebra import Matrix
+from . import hyp_utils
+from ..SnapPy import set_rand_seed
+
+
+def filled_is_3sphere(manifold):
+    """
+    >>> isosig = 'nLvLLLPQQkcfejimhklkmlkmuphkvuoupilhhv_Bbba(1, 0)'
+    >>> filled_is_3sphere(Manifold(isosig))
+    True
+    >>> filled_is_3sphere(Triangulation('m004(1, 2)'))
+    False
+    """
+    if hasattr(manifold, 'without_hyperbolic_structure'):
+        T = manifold.without_hyperbolic_structure()
+    else:
+        T = manifold.copy()
+    for i in range(T.num_cusps()):
+        if T.cusp_info(i).is_complete:
+            T.dehn_fill((1, 0), i)
+
+        for i in range(10):
+            if T.fundamental_group().num_generators() == 0:
+                return True
+            F = T.filled_triangulation()
+            if F.fundamental_group().num_generators() == 0:
+                return True
+            T.randomize()
+
+    return False
+
+
+def exterior_to_link(manifold,
+                     verbose : bool = False,
+                     check_input : bool = True,
+                     check_answer : bool = True,
+                     careful_perturbation : bool = True,
+                     simplify_link : bool = True,
+                     pachner_search_tries :int = 10,
+                     seed : typing.Optional[int] = None) -> 'Link':
+    """
+    For a triangulation of the exterior of a link in the 3-sphere,
+    return a planar diagram for the link.  The peripheral curves whose
+    Dehn filling is the 3-sphere are **part of the input**, specified
+    by either:
+
+    a. If no cusp is filled, then they are the meridians of the
+       current peripheral curves.
+
+    b. If every cusp is filled, then they are the current Dehn filling
+       curves.
+
+    In particular, it does **not** try to determine whether there exist
+    fillings on the input which give the 3-sphere.  Example usage:
+
+    >>> M = Manifold('m016')
+    >>> L = exterior_to_link(M)
+    >>> L.exterior().is_isometric_to(M)
+    True
+
+    The algorithm used is that of `Dunfield, Obeidin, and Rudd
+    <https://arxiv.org/abs/2112.03251>`_.  The optional arguments are
+    as follows.
+
+    * ``verbose``: When ``True``, prints progress updates as the algorithm
+      goes along.
+
+    * ``check_input``: When ``True`` (the default), first checks that the
+      fundamental group of the specified Dehn filling is trivial.  As
+      it doesn't try too hard to simplify the group presentation, it
+      can happen that this check fails but the algorithm still finds a
+      diagram if you pass ``check_input=False``.
+
+    * ``check_answer``: When ``True`` (the default), take the exterior of
+      the final link diagram and use ``Manifold.is_isometric_to`` to
+      confirm that it is homeomorphic to the input.  If the input is
+      not hyperbolic or is very large, this check may fail even though
+      the diagram is correct.
+
+    * ``careful_perturbation``: The rational coordinates of the
+      intermediate PL links are periodically rounded to control the
+      size of their denominators.  When ``careful_perturbation=True``
+      (the default), computations are performed to ensure this
+      rounding does not change the isotopy class of the link.
+
+    * ``simplify_link``: When ``True`` (the default), uses
+      ``Link.simplify('global')`` to minimize the size of the final
+      diagram; otherwise, it just does ``basic`` simplifications, which
+      can be much faster if the initial link is complicated.
+
+    * ``pachner_search_tries``: Controls how hard to search for a
+      suitable sequence of Pachner moves from the filled input
+      triangulation to a standard triangulation of the 3-sphere.
+
+    * ``seed``: The algorithm involves many random choices, and hence
+      each run typically produces a different diagram of the
+      underlying link.  If you need the same output each time, you can
+      specify a fixed seed for the various pseudo-random number
+      generators.
+
+    Note on rigor: Provided at least one of ``check_answer`` and
+    ``careful_perturbation`` is ``True``, the exterior of the output
+    link is guaranteed to match the input (including the choice of
+    meridians).
+
+    **Warning:** The order of the link components and the cusps of the
+    input manifold is only guaranteed to match when
+    ``check_answer=True``.  Even then, the implicit orientation along
+    each component of the link may not be preserved.
+    """
+
+    unfilled = set(manifold.cusp_info('is_complete'))
+    if unfilled == {True, False}:
+        raise ValueError('Cusps should either be all filled or all unfilled')
+
+    if check_input and not filled_is_3sphere(manifold):
+        raise ValueError('Filling in the meridians does not obviously give S^3')
+
+    def print_status(*args, **kwargs):
+        if verbose:
+            print(*args, **kwargs, flush=True)
+
+    print_status(f'Finding link for {manifold.name()}')
+    if seed is not None:
+        seed = int(seed)
+        random.seed(seed)
+        set_rand_seed(seed)
+        print_status('    Seed:', seed)
+
+    print_status('    Finding moves to base triangulation of S^3...')
+    tris_with_moves = good_simplification(manifold,
+                                          max_tries=pachner_search_tries)
+    if tris_with_moves:
+        M, moves, expanded_moves = tris_with_moves
+    else:
+        raise ExteriorToLinkError('Could not simplify to standard triangulation of S^3')
+
+    print_status(f'    Starting with {len(M)} tets, to do {len(moves)} simple Pachner moves.')
+    M.perform_moves(moves, push=True, straighten=True, round=True, careful=careful_perturbation)
+    M.rebuild()
+    M.connect_arcs()
+    print_status('    Moves resulted in', sum(len(tet.arcs) for tet in M),
+                 f'PL segments; max denom of coor is {M._curr_max_denom()}.')
+    print_status('    Embedding in S3...', end='')
+    link_in_R3 = put_in_S3.embed_link_in_S3(M)
+    link_in_R3 = link_projection.straighten_link(link_in_R3)
+    num_seg = sum(len(component) + 1 for component in link_in_R3)
+    print_status('got PL link of', num_seg ,'segments.')
+    print_status('    Projecting...', end='')
+
+    L = link_projection.project_to_diagram(link_in_R3)
+    if L is None:
+        raise ExteriorToLinkError('Was unable to project link')
+
+    L.simplify('basic')
+    print_status(f'got diagram with {len(L.crossings)} crossings.')
+
+    if simplify_link:
+        print_status('    Simplifying diagram...', end='')
+        L.simplify('pickup')
+        print_status(f'{len(L.crossings)} crossings...', end='')
+        L.simplify('global')
+        print_status(f'{len(L.crossings)} crossings.')
+
+    if check_answer:
+        E = L.exterior()
+        if unfilled == {True}:
+            F = manifold
+        else:
+            F = manifold.copy()
+            F.dehn_fill(F.num_cusps()*[(0, 0)])
+            F.randomize()
+        if hasattr(F, 'with_hyperbolic_structure'):
+            F = F.with_hyperbolic_structure()
+
+        iso = hyp_utils.orientation_preserving_link_isometries(E, F, tries=1000)
+        if iso is not None:
+            L = hyp_utils.reorder_link_components(L, iso.cusp_images())
+            E = L.exterior()
+            if hyp_utils.are_orient_pres_isometric_as_ordered_links(E, F):
+                print_status('    Exterior of final link checks!\n')
+            else:
+                ExteriorToLinkError('Could not correctly order link components')
+        else:
+            raise ExteriorToLinkError('Could not confirm topology of link exterior')
+
+    return L