Talking with SnapPy

Since Regina 4.95, a default installation of Regina can talk directly with a default installation of SnapPy on many platforms. This includes macOS 10.7 or greater (if you installed the SnapPy app bundle in the usual Applications folder), and GNU/Linux (if your SnapPy uses the default system Python installation).

Simply type import snappy from within any of Regina's Python environments. To send information back and forth between Regina and SnapPy:

  • Regina's triangulation classes Triangulation3 and SnapPeaTriangulation both have a snapPea() function, which gives a string that you can pass to SnapPy's Manifold constructor.

  • SnapPy's Manifold class has a _to_string() function, which gives a string that you can pass to Regina's Triangulation3 or SnapPeaTriangulation constructor.

Regarding fillings and peripheral curves: Regina does not store fillings or peripheral curves for its own native triangulation packets, as represented by the Triangulation3 class. However, it does store fillings and peripheral curves for its hybrid SnapPea triangulation packets, as represented by the SnapPeaTriangulation class. The trade-off is that the native Triangulation3 class offers Regina's full fine-grained control over the triangulation, whereas the hybrid SnapPeaTriangulation class has a more limited (largely read-only) interface.

  • When sending data from Regina to SnapPy, if your triangulation is of the class Triangulation3, then Triangulation3.snapPea() will create a SnapPy manifold in which all fillings and peripheral curves are marked as unknown. If your triangulation is of the class SnapPeaTriangulation, and if you already have fillings and peripheral curves stored on each cusp, then SnapPeaTriangulation.snapPea() will create a SnapPy manifold that preserves these.

  • Conversely, when sending data from SnapPy to Regina, you can choose to instantiate a triangulation using either the Triangulation3 class or the SnapPeaTriangulation class. If you use the Triangulation3 class then all fillings and peripheral curves will be lost. If you use the SnapPeaTriangulation class then fillings and peripheral curves will be preserved (but your interface will be more restricted).

If you wish to send the complement of a native Regina Link to SnapPy, you can pass your link directly to the SnapPeaTriangulation constructor, which will preserve the peripheral curves from the link diagram; then you can pass this to SnapPy via SnapPeaTriangulation.snapPea() as above.

Regarding the interface: the SnapPeaTriangulation class inherits from Triangulation3, and so you can use it anywhere that a read-only triangulation is expected (in particular, you can use it for enumerating vertex normal surfaces or angle structures). However, because SnapPeaTriangulation must maintain two synchronised copies of the triangulation (Regina's and SnapPea's), it is essentially read-only: any attempt to modify the triangulation using Regina's native routines (e.g., pachner() or barycentricSubdivision()) will cause the SnapPea triangulation to delete itself and become a “null triangulation” instead.

Warning

At present, SnapPy (version 2.0.3) is not compatible with multiple Python interpreters. If you import SnapPy into more than one Python console in the graphical user interface, SnapPy may stop working. See this troubleshooting entry for details.

The following Python session illustrates several of the concepts discussed above.

bab@ember:~$ regina-python 
Regina 7.2
Software for low-dimensional topology
Copyright (c) 1999-2022, The Regina development team
>>> import snappy
>>> m = snappy.Manifold('m001')
>>> t = SnapPeaTriangulation(m._to_string())
>>> print t.detail()
Size of the skeleton:
  Tetrahedra: 2
  Triangles: 4
  Edges: 2
  Vertices: 1

Tetrahedron gluing:
  Tet  |  glued to:      (012)      (013)      (023)      (123)
  -----+-------------------------------------------------------
    0  |               1 (103)    1 (320)    1 (210)    1 (132)
    1  |               0 (320)    0 (102)    0 (310)    0 (132)

Vertices:
  Tet  |  vertex:    0   1   2   3
  -----+--------------------------
    0  |             0   0   0   0
    1  |             0   0   0   0

Edges:
  Tet  |  edge:   01  02  03  12  13  23
  -----+--------------------------------
    0  |           0   1   1   1   1   0
    1  |           0   1   1   1   1   0

Triangles:
  Tet  |  face:  012 013 023 123
  -----+------------------------
    0  |           0   1   2   3
    1  |           2   0   1   3

Tetrahedron shapes:
  0: ( -1.60812e-16, 1 )
  1: ( -1.60812e-16, 1 )

Cusps:
  0: Vertex 0, complete

>>> print t.hasStrictAngleStructure()
True
>>> print AngleStructures(t).detail()
4 vertex angle structures (no restrictions):
0 1 0 ; 1 0 0
0 0 1 ; 1 0 0
1 0 0 ; 0 1 0
1 0 0 ; 0 0 1

>>> t2 = Example3.figureEight()
>>> m2 = snappy.Manifold(t2.snapPea())
>>> print m2.volume()
2.02988321282
>>>