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 X 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 NTriangulation and NSnapPeaTriangulation 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 NTriangulation or NSnapPeaTriangulation constructor.

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

  • When sending data from Regina to SnapPy, if your triangulation is of the class NTriangulation, then NTriangulation.snapPea() will create a SnapPy manifold in which all fillings and peripheral curves are marked as unknown. If your triangulation is of the class NSnapPeaTriangulation, and if you already have fillings and peripheral curves stored on each cusp, then NSnapPeaTriangulation.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 NTriangulation class or the NSnapPeaTriangulation class. If you use the NTriangulation class then all fillings and peripheral curves will be lost. If you use the NSnapPeaTriangulation class then fillings and peripheral curves will be preserved (but your interface will be more restricted).

Regarding the interface: the NSnapPeaTriangulation class inherits from NTriangulation, 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 NSnapPeaTriangulation 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., twoThreeMove() 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 4.96
Software for 3-manifold topology and normal surface theory
Copyright (c) 1999-2013, The Regina development team
>>> import snappy
>>> m = snappy.Manifold('m001')
>>> t = NSnapPeaTriangulation(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 NAngleStructureList.enumerate(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 = NExampleTriangulation.figureEightKnotComplement()
>>> m2 = snappy.Manifold(t2.snapPea())
>>> print m2.volume()
2.02988321282
>>>