# 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
    >>>