snappy 3.2__cp313-cp313-macosx_11_0_arm64.whl

snappy/snap/peripheral/dual_cellulation.py

@@ -0,0 +1,219 @@
+"""
+The dual cellulation to a triangulation of an oriented surface.
+"""
+
+from ... import sage_helper
+from .. import t3mlite as t3m
+
+if sage_helper._within_sage:
+    from ...sage_helper import ZZ, matrix, vector, ChainComplex
+    from sage.graphs.graph import Graph
+
+
+class DualCell():
+    """
+    A cell in the dual cellulation
+    """
+    def __init__(self, dual_cell):
+        self.dual_cell = dual_cell
+        self.index = dual_cell.index
+
+
+class Vertex(DualCell):
+    """
+    A vertex of the dual cellulation.
+    """
+
+
+class Edge(DualCell):
+    """
+    An oriented edge of the dual cellulation. The orientation
+    convention is that if e is the original edge and d is the dual
+    edge then one rotates from d to e anticlockwise.
+    """
+    def __init__(self, dual_cell):
+        DualCell.__init__(self, dual_cell)
+        self.vertices = [None, None]
+
+
+class Face(DualCell):
+    """
+    A face of the dual cellulation, which is just an n-gon.  The
+    vertices are numbered range(n) in an anti-clockwise orientation.
+
+    Oriented edges of the face are specified by their initial vertex.
+    """
+    def __init__(self, dual_cell):
+        DualCell.__init__(self, dual_cell)
+        self.n = len(dual_cell.corners)
+        self.edges_with_orientations = self.n*[None]
+
+    def __repr__(self):
+        return "<Face: %s>" % self.index
+
+
+class DualCellulation():
+    """
+    The dual cellulation to a triangulation of a surface.
+    """
+    def __init__(self, triangulation):
+        self.dual_triangulation = triangulation
+        self.from_original = {}
+        self.vertices = []
+        self.edges = []
+        self.faces = []
+        self._B1 = None
+        self._B2 = None
+        self._chain_complex = None
+        for vertex in triangulation.vertices:
+            face = Face(vertex)
+            self.faces.append(face)
+            self.from_original[vertex] = face
+        for edge in triangulation.edges:
+            dual_edge = Edge(edge)
+            self.edges.append(dual_edge)
+            self.from_original[edge] = dual_edge
+        for triangle in triangulation.triangles:
+            vertex = Vertex(triangle)
+            self.vertices.append(vertex)
+            self.from_original[triangle] = vertex
+
+        for vertex in triangulation.vertices:
+            face = self.from_original[vertex]
+            for i, corner in enumerate(vertex.corners):
+                edge, orient = corner.edge_with_orientation()
+                dual_edge = self.from_original[edge]
+                face.edges_with_orientations[i] = (dual_edge, -orient)
+                if orient > 0:
+                    dual_edge.vertices = [self.from_original[side.triangle] for side in edge.sides]
+
+    def euler(self):
+        """
+        sage: N = t3m.Mcomplex('o9_12345')
+        sage: D = DualCellulation(LinkSurface(N))
+        sage: D.euler()
+        0
+        sage: N = t3m.Mcomplex('jLLvQPQcdfhghigiihshhgfifme')
+        sage: D = DualCellulation(LinkSurface(N))
+        sage: D.euler()
+        2
+        """
+        return len(self.vertices) - len(self.edges) + len(self.faces)
+
+    def B1(self):
+        """
+        The matrix describing the boundary map C_1 -> C_0
+        """
+        if self._B1 is None:
+            V, E = len(self.vertices), len(self.edges)
+            assert list(range(V)) == sorted(v.index for v in self.vertices)
+            assert list(range(E)) == sorted(e.index for e in self.edges)
+
+            D = matrix(ZZ, V, E, sparse=True)
+            for e in self.edges:
+                v_init = e.vertices[0].index
+                v_term = e.vertices[1].index
+                D[v_term, e.index] += 1
+                D[v_init, e.index] += -1
+            self._B1 = D
+
+        return self._B1
+
+    def B2(self):
+        """
+        The matrix describing the boundary map C_2 -> C_1
+
+        Does *not* assume that the faces are numbered like
+        range(len(faces)).
+        """
+        if self._B2 is None:
+            E, F = len(self.edges), len(self.faces)
+            assert list(range(E)) == sorted(e.index for e in self.edges)
+            D = matrix(ZZ, E, F, sparse=True)
+            for i, face in enumerate(self.faces):
+                for edge, sign in face.edges_with_orientations:
+                    D[edge.index, i] += sign
+            self._B2 = D
+
+        return self._B2
+
+    def chain_complex(self):
+        if self._chain_complex is None:
+            self._chain_complex = ChainComplex({1:self.B1(), 2:self.B2()}, degree=-1)
+        return self._chain_complex
+
+    def integral_cohomology_basis(self, dimension=1):
+        assert dimension == 1
+        return [OneCocycle(self, list(c.weights))
+                for c in self.dual_triangulation.integral_homology_basis(dimension)]
+
+    def homology_test(self):
+        T = self.dual_triangulation
+        B1, B2 = self.B1(), self.B2()
+        assert B1*B2 == 0
+        assert T.euler() == self.euler()
+        CD = self.chain_complex()
+        CT = T.chain_complex()
+        assert CD.homology() == CT.homology()
+
+
+class OneCycle():
+    """
+    A cycle on the 1-skeleton of a DualCellulation.
+    """
+
+    def __init__(self, cellulation, weights):
+        self.cellulation, self.weights = cellulation, weights
+        assert sorted(edge.index for edge in cellulation.edges) == list(range(len(weights)))
+        assert cellulation.B1() * vector(weights) == 0
+
+    def components(self):
+        """
+        Returns a list of the connected components of the multicurve
+        corresponding to the 1-cycle, each given as a OneCycle.
+
+        Assumes for simplicity that the weights are at most one and
+        the support of the cycle is a simple multicurve.
+        """
+        assert all(abs(w) <= 1 for w in self.weights)
+        D = self.cellulation
+        G = Graph(multiedges=True)
+        for edge in D.edges:
+            if self.weights[edge.index] != 0:
+                i, j = (v.index for v in edge.vertices)
+                G.add_edge(i, j, edge.index)
+
+        assert G.num_verts() == G.num_edges()
+
+        ans = []
+        for H in G.connected_components_subgraphs():
+            weights = len(self.weights) * [0]
+            for i in H.edge_labels():
+                weights[i] = self.weights[i]
+            ans.append(OneCycle(self.cellulation, weights))
+        return ans
+
+
+class OneCocycle():
+    """
+    A cocycle on the 1-skeleton of a DualCellulation.
+    """
+
+    def __init__(self, cellulation, weights):
+        self.cellulation, self.weights = cellulation, weights
+        assert sorted(edge.index for edge in cellulation.edges) == list(range(len(weights)))
+        assert cellulation.B2().transpose() * vector(weights) == 0
+
+    def __call__(self, other):
+        if isinstance(other, OneCycle):
+            return sum(a*b for a, b in zip(self.weights, other.weights))
+
+
+def doctest_globals():
+    import link
+    return {'LinkSurface':link.LinkSurface}
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod(extraglobs=doctest_globals())

snappy/snap/peripheral/link.py

@@ -0,0 +1,127 @@
+r"""
+Studying the vertex links of triangulations of 3-manifolds.
+
+Recall that in t3m and SnapPea, a 3-simplex is oriented like this::
+
+         1
+        /|\
+       / | \
+      /  |  \
+     2---|---3
+      \  |  /
+       \ | /
+        \|/
+         0
+
+Now consider the truncated tetrahedron; there, each vertex gives rise to a
+small triangular face whose vertices correspond to edges of the original
+tetrahedron.  We orient each small triangle so that its boundary rotates
+anticlockwise when viewed from outside.
+"""
+
+import networkx as nx
+from .. import t3mlite as t3m
+from ..t3mlite.simplex import *
+from . import surface
+
+# The vertices of the small triangular faces of the truncated tetrahedron
+
+TruncatedSimplexCorners = {
+    V0 : (E01, E02, E03),
+    V1 : (E10, E13, E12),
+    V2 : (E23, E20, E21),
+    V3 : (E32, E31, E30)}
+
+# Oriented clockwise when viewed from *outside*, so that the induced
+# orientation of the hexagons in the truncated tetrahedron has the following
+# property: The orientation of each hexagon's edges is compatible with the
+# preferred orientation on the small triangular faces.
+
+VerticesOfFace = { F0 : (V1, V2, V3), F1 : (V0, V3, V2),
+                   F2 : (V0, V1, V3), F3 : (V0, V2, V1) }
+
+
+def cusp_corner_label(v, w):
+    return TruncatedSimplexCorners[v].index( v | w )
+
+
+class LinkSurface(surface.Surface):
+    def __init__(self, t3m_triangulation):
+        self.parent_triangulation = t3m_triangulation
+        N = t3m_triangulation
+        triangles = []
+        for T in N.Tetrahedra:
+            new_tris = [surface.Triangle() for i in range(4)]
+            triangles += new_tris
+            T.CuspCorners = {V0:new_tris[0], V1:new_tris[1], V2:new_tris[2], V3:new_tris[3]}
+
+        surface.Surface.__init__(self, triangles)
+
+        for F in N.Faces:
+            F0 = F.Corners[0]
+            T0 = F0.Tetrahedron
+            f0 = F0.Subsimplex
+            v0 = comp(f0)
+
+            F1 = F.Corners[1]
+            T1 = F1.Tetrahedron
+            f1 = F1.Subsimplex
+            v1 = comp(f1)
+
+            for v in VerticesOfFace[f0]:
+                w = T0.Gluing[f0].image(v)
+                C0, C1 = T0.CuspCorners[v], T1.CuspCorners[w]
+                x0 = cusp_corner_label(v, v0)
+                x1 = cusp_corner_label(w, v1)
+                E = self.glue_triangles(C0, x0, C1, x1)
+                E.face_index = F.Index
+                E.reversed = False
+
+        self.build()
+        self.label_vertices()
+
+    def label_vertices(self):
+        N = self.parent_triangulation
+        for vert in self.vertices:
+            vert.index = None
+        for edge in N.Edges:
+            corner = edge.Corners[0]
+            tet = corner.Tetrahedron
+            a = Head[corner.Subsimplex]
+            b = Tail[corner.Subsimplex]
+            sign = edge.orientation_with_respect_to(tet, a, b)
+            for (v, s) in [(a, sign), (b, -sign)]:
+                label = s*(edge.Index + 1)
+                i = TruncatedSimplexCorners[v].index(a | b)
+                tri = tet.CuspCorners[v]
+                tri.vertices[i].index = label
+
+    def edge_graph(self):
+        G = nx.Graph()
+        G.add_edges_from([[v.index for v in e.vertices] for e in self.edges])
+        return G
+
+
+class LinkSphere(LinkSurface):
+    """
+    >>> T = Mcomplex('kLLLLQMkbcghgihijjjtsmnonnkddl')  # m004(1, 2)
+    >>> L = LinkSphere(T)
+    >>> L.edge_graph().number_of_nodes()
+    22
+    >>> 2 * len(T.Edges)
+    22
+    """
+    def __init__(self, t3m_triangulation):
+        N = t3m_triangulation
+        assert len(N.Vertices) == 1 and N.Vertices[0].link_genus() == 0
+        LinkSurface.__init__(self, N)
+
+
+def doctest_globals():
+    import snappy.snap.t3mlite
+    return {'Mcomplex': snappy.snap.t3mlite.Mcomplex}
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod(extraglobs=doctest_globals())

snappy/snap/peripheral/peripheral.py

@@ -0,0 +1,159 @@
+from ... import sage_helper
+from .. import t3mlite as t3m
+from . import link, dual_cellulation
+
+if sage_helper._within_sage:
+    from ...sage_helper import matrix, vector, ZZ
+
+
+def peripheral_curve_from_snappy(dual_cell, snappy_data):
+    D = dual_cell
+    T = D.dual_triangulation
+    M = T.parent_triangulation
+    data = snappy_data
+    weights = len(D.edges)*[0]
+    for tet_index, tet in enumerate(M.Tetrahedra):
+        for vert_index, V in enumerate(t3m.ZeroSubsimplices):
+            triangle = tet.CuspCorners[V]
+            sides = triangle.oriented_sides()
+            for tri_edge_index, tet_edge in enumerate(link.TruncatedSimplexCorners[V]):
+                tet_face_index = t3m.ZeroSubsimplices.index(tet_edge ^ V)
+                side = sides[tri_edge_index]
+                global_edge = side.edge()
+                if global_edge.orientation_with_respect_to(side) > 0:
+                    dual_edge = D.from_original[global_edge]
+                    weight = data[tet_index][4*vert_index + tet_face_index]
+                    weights[dual_edge.index] = -weight
+
+    # Sanity check
+    total_raw_weights = sum([sum(abs(x) for x in row) for row in data])
+    assert 2*sum(abs(w) for w in weights) == total_raw_weights
+    return dual_cellulation.OneCycle(D, weights)
+
+
+def peripheral_curve_package(snappy_manifold):
+    """
+    Given a 1-cusped snappy_manifold M, this function returns
+
+    1. A t3m MComplex of M, and
+
+    2. the induced cusp triangulation, and
+
+    3. the dual to the cusp triangulation, and
+
+    4. two 1-cocycles on the dual cellulation which are
+    *algebraically* dual to the peripheral framing of M.
+
+    sage: M = peripheral_curve_package(Manifold('t00000'))[0]
+    sage: len(M)
+    8
+    sage: T, D = M.cusp_triangulation, M.cusp_dual_cellulation
+    sage: T.homology_test()
+    sage: D.euler()
+    0
+    sage: D.slope(D.meridian)
+    (1, 0)
+    sage: D.slope(D.longitude)
+    (0, 1)
+    """
+    M = snappy_manifold
+    assert M.num_cusps() == 1
+    N = t3m.Mcomplex(M)
+    C = link.LinkSurface(N)
+    D = dual_cellulation.DualCellulation(C)
+    cusp_indices, data = M._get_cusp_indices_and_peripheral_curve_data()
+    meridian = peripheral_curve_from_snappy(D, [data[i] for i in range(0, len(data), 4)])
+    longitude = peripheral_curve_from_snappy(D, [data[i] for i in range(2, len(data), 4)])
+    alpha, beta = D.integral_cohomology_basis()
+    A = matrix([[alpha(meridian), beta(meridian)], [alpha(longitude), beta(longitude)]])
+    assert abs(A.det()) == 1
+    Ainv = A.inverse().change_ring(ZZ)
+    B = Ainv.transpose() * matrix(ZZ, [alpha.weights, beta.weights])
+    mstar = dual_cellulation.OneCocycle(D, list(B[0]))
+    lstar = dual_cellulation.OneCocycle(D, list(B[1]))
+    AA = matrix([[mstar(meridian), lstar(meridian)], [mstar(longitude), lstar(longitude)]])
+    assert AA == 1
+
+    # Now add references to C, D, etc. to N for easy of use later
+    N.cusp_triangulation = C
+    N.cusp_dual_cellulation = D
+    D.meridian, D.longitude = meridian, longitude
+    D.meridian_star, D.longitude_star = mstar, lstar
+
+    def slope(onecycle):
+        return vector([D.meridian_star(onecycle), D.longitude_star(onecycle)])
+    D.slope = slope
+    return N, C, D, (mstar, lstar)
+
+
+class PeripheralOneCocycle():
+    """
+    Let M be an ideal triangulation with one cusp, and consider the
+    induced triangulation T of the cusp torus.  This object is a
+    1-cocycles on T, whose weights are accessed via
+
+    self[tet_num, face_index, vertex_in_face].
+    """
+    def __init__(self, dual_cellulation_cocycle):
+        self.cocycle = dual_cellulation_cocycle
+        self.dual_cellulation = D = dual_cellulation_cocycle.cellulation
+        self.cusp_triangulation = T = D.dual_triangulation
+        self.mcomplex = T.parent_triangulation
+
+    def __getitem__(self, tet_face_vertex):
+        tet_num, F, V = tet_face_vertex
+        tet = self.mcomplex.Tetrahedra[tet_num]
+        triangle = tet.CuspCorners[V]
+        for side in triangle.oriented_sides():
+            E0, E1 = (link.TruncatedSimplexCorners[V][v] for v in side.vertices)
+            if E0 | E1 == F:
+                break
+        assert E0 | E1 == F
+        global_edge = side.edge()
+        dual_edge = self.dual_cellulation.from_original[global_edge]
+        w = self.cocycle.weights[dual_edge.index]
+        s = global_edge.orientation_with_respect_to(side)
+        return w*s
+
+
+def peripheral_cohomology_basis(manifold):
+    """
+    TESTS::
+
+        sage: M = Manifold('v0000')
+        sage: m, l = peripheral_cohomology_basis(M)
+        sage: face_corners = [(t, f, v) for t in range(7) for f in t3m.TwoSubsimplices for v in t3m.ZeroSubsimplices if f & v ]
+        sage: [m[fc] for fc in face_corners]  # doctest: +SKIP
+        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+         0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0,
+         0, 0, -1, 0, -1, -1, 0, -1, 0, 0, -1, 0, 1, 0, 1, 0, 1, 0]
+    """
+    assert manifold.is_orientable() and manifold.num_cusps() == 1
+    N, T, D, (m, l) = peripheral_curve_package(manifold)
+    return PeripheralOneCocycle(m), PeripheralOneCocycle(l)
+
+
+def test_peripheral_curves(n=100, progress=True):
+    """
+    TESTS::
+
+        sage: test_peripheral_curves(5, False)
+    """
+    import snappy
+    census = snappy.OrientableCuspedCensus(cusps=1)
+    for i in range(n):
+        M = census.random()
+        if progress:
+            print(M.name())
+        peripheral_curve_package(M)
+
+
+def doctest_globals():
+    import snappy
+    return {'Manifold':snappy.Manifold}
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod(extraglobs=doctest_globals())