# Sample Python Sessions

Several sample Python sessions are reproduced below. Each session was started by running `regina-python` from the command line.

### Working with a triangulation

    example$ regina-python
    Regina 4.95
    Software for 3-manifold topology and normal surface theory
    Copyright (c) 1999-2013, The Regina development team
    >>> ################################
    ... #
    ... #  Sample Python Script
    ... #
    ... #  Illustrates different queries and actions on a 3-manifold triangulation
    ... #  and its normal surfaces.
    ... #
    ... #  See the file "triangulation.session" for the results of running this
    ... #  script.
    ... #
    ... ################################
    ...
    >>> # Create a new (3,4,7) layered solid torus.  This is a 3-tetrahedron
    ... # triangulation of a solid torus.
    ... t = NTriangulation()
    >>> t.insertLayeredSolidTorus(3,4)
    <regina.engine.NTetrahedron object at 0x10c5221a0>
    >>> print t
    Triangulation with 3 tetrahedra.
    >>>
    >>> # Print the full skeleton of the triangulation.
    ... print t.detail()
    Size of the skeleton:
      Tetrahedra: 3
      Triangles: 7
      Edges: 5
      Vertices: 1

    Tetrahedron gluing:
      Tet  |  glued to:      (012)      (013)      (023)      (123)
      -----+-------------------------------------------------------
        0  |              boundary   boundary    1 (012)    1 (130)
        1  |               0 (023)    0 (312)    2 (013)    2 (120)
        2  |               1 (312)    1 (023)    2 (312)    2 (230)

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

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

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

    >>>
    >>> # Calculate some algebraic properties of the triangulation.
    ... print t.getHomologyH1()
    Z
    >>> print t.getHomologyH1Bdry()
    2 Z
    >>>
    >>> # Test for 0-efficiency, which asks Regina to search for certain types
    ... # of normal surfaces.
    ... print t.isZeroEfficient()
    False
    >>>
    >>> # Make our own list of vertex normal surfaces in standard coordinates.
    ... surfaces = NNormalSurfaceList.enumerate(t, NS_STANDARD)
    >>>
    >>> # Verify that the normal surface list is already a child packet of the
    ... # triangulation.  This happens automatically whenever you enumerate
    ... # normal surfaces (or angle structures).
    ... if surfaces.getTreeParent() == t:
    ...     print "OK: Parent-child relationship is correct."
    ... else:
    ...     print "ERROR: Parent-child relationship is incorrect."
    ...
    OK: Parent-child relationship is correct.
    >>>
    >>> # Print the full list of vertex normal surfaces.
    ... print surfaces.detail()
    Embedded, vertex surfaces
    Coordinates: Standard normal (tri-quad)
    Number of surfaces is 9
    1 1 1 1 ; 0 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0
    0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0
    0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0
    0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0
    1 1 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 0 || 0 0 0 0 ; 0 1 0
    3 3 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 2 || 1 1 0 0 ; 0 0 1
    0 0 1 1 ; 1 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0
    0 0 0 0 ; 0 1 0 || 0 0 0 0 ; 1 0 0 || 0 0 0 0 ; 0 1 0
    1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0 || 1 1 1 1 ; 0 0 0

    >>>
    >>> # Print the Euler characteristic and orientability of each surface.
    ... for i in range(surfaces.getNumberOfSurfaces()):
    ...     s = surfaces.getSurface(i)
    ...     print "Chi =", s.getEulerCharacteristic(), "; Or =", s.isOrientable()
    ...
    Chi = -1 ; Or = True
    Chi = 0 ; Or = True
    Chi = 0 ; Or = True
    Chi = 0 ; Or = True
    Chi = 0 ; Or = False
    Chi = 1 ; Or = True
    Chi = -2 ; Or = True
    Chi = -1 ; Or = False
    Chi = 1 ; Or = True
    >>>
    >>> # List all surfaces with more than one quad in the first tetrahedron.
    ... for i in range(surfaces.getNumberOfSurfaces()):
    ...     s = surfaces.getSurface(i)
    ...     if s.getQuadCoord(0,0) + s.getQuadCoord(0,1) + s.getQuadCoord(0,2) > 1:
    ...         print s
    ...
    0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0 || 1 1 1 1 ; 0 0 0
    0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 0
    >>>
    >>> # Tidy up.
    ... # Delete the triangulation.  This will automatically delete the surface
    ... # list, which is a child of the triangulation in the packet tree.
    ... t = None
    >>>

### Working with a packet tree

    example$ regina-python
    Regina 4.95
    Software for 3-manifold topology and normal surface theory
    Copyright (c) 1999-2013, The Regina development team
    >>> ################################
    ... #
    ... #  Sample Python Script
    ... #
    ... #  Illustrates the traversal and manipulation of an entire packet tree.
    ... #
    ... #  See the file "tree.session" for the results of running this script.
    ... #
    ... ################################
    ...
    >>> # Create a new census of finite orientable closed 3-manifold
    ... # triangulations with two tetrahedra.
    ... census = NContainer()
    >>> NCensus.formCensus(census, 2, NBoolSet.sTrue,
    ...     NBoolSet.sTrue, NBoolSet.sFalse, 0, 0)
    16
    >>>
    >>> # Calculate the homology of each triangulation in the census.
    ... # The triangulations are all children of the "census" container.
    ... tri = census.getFirstTreeChild()
    >>> while tri != None:
    ...     print tri.getPacketLabel() + ":", tri.getHomologyH1()
    ...     tri = tri.getNextTreeSibling()
    ...
    Item 1: Z_7
    Item 2: Z_5
    Item 3: Z
    Item 4: Z_3
    Item 5: Z_8
    Item 6: 0
    Item 7: 0
    Item 8: 0
    Item 9: Z_2
    Item 10: 0
    Item 11: 0
    Item 12: Z_3
    Item 13: 0
    Item 14: Z_3
    Item 15: 2 Z_2
    Item 16: Z_2
    >>>
    >>> # Remove all triangulations with trivial homology from the tree.
    ... tri = census.getFirstTreeChild()
    >>> while tri != None:
    ...     next = tri.getNextTreeSibling()
    ...     hom = tri.getHomologyH1()
    ...     if hom.isTrivial():
    ...         tri.makeOrphan()
    ...     tri = next
    ...
    <regina.engine.NTriangulation object at 0x1088396e0>
    <regina.engine.NTriangulation object at 0x108839670>
    <regina.engine.NTriangulation object at 0x1088397c0>
    <regina.engine.NTriangulation object at 0x108839520>
    <regina.engine.NTriangulation object at 0x108839750>
    <regina.engine.NTriangulation object at 0x108839670>
    >>>
    >>> # Print the homology of each remaining triangulation.
    ... tri = census.getFirstTreeChild()
    >>> while tri != None:
    ...     print tri.getPacketLabel() + ":", tri.getHomologyH1()
    ...     tri = tri.getNextTreeSibling()
    ...
    Item 1: Z_7
    Item 2: Z_5
    Item 3: Z
    Item 4: Z_3
    Item 5: Z_8
    Item 9: Z_2
    Item 12: Z_3
    Item 14: Z_3
    Item 15: 2 Z_2
    Item 16: Z_2
    >>>

### Reporting progress of long operations

    example$ regina-python
    Regina 4.95
    Software for 3-manifold topology and normal surface theory
    Copyright (c) 1999-2013, The Regina development team
    >>> ################################
    ... #
    ... #  Sample Python Script
    ... #
    ... #  Illustrates progress reporting during long operations.
    ... #
    ... #  See the file "progress.session" for the results of running this script.
    ... #
    ... ################################
    ...
    >>> import time
    >>>
    >>> # Create an 18-tetrahedron triangulation of a knot complement with real
    ... # boundary faces (not an ideal vertex).  The knot is L106003 from the
    ... # knot/link census.  We used Regina to truncate the ideal vertex, and
    ... # then copied the isomorphism signature so that we can reconstruct the
    ... # triangulation here.
    ... sig = 'sfLfvQvwwMQQQccjghjkmqlonrnrqpqrnsnksaisnrobocksks'
    >>> tri = NTriangulation(sig)
    >>> print tri.getNumberOfTetrahedra(), 'tetrahedra'
    18 tetrahedra
    >>>
    >>> # Create a progress tracker to use during the normal surface enumeration.
    ... # This will report the state of progress while the enumeration runs in
    ... # the background.
    ... tracker = NProgressTracker()
    >>>
    >>> # Start the normal surface enumeration.
    ... # Because we are passing a progress tracker to enumerate(), the
    ... # enumeration will start in the background and control will return
    ... # immediately to the python console.
    ... surfaces = NNormalSurfaceList.enumerate(tri, NS_STANDARD, NS_VERTEX,
    ...     NS_ALG_DEFAULT, tracker)
    >>>
    >>> # At this point the enumeration is up and running.
    ... # Output a progress report every half-second until it finishes.
    ... while not tracker.isFinished():
    ...     print 'Progress:', tracker.percent(), '%'
    ...     time.sleep(0.5)
    ...
    Progress: 0.0 %
    Progress: 31.8218994141 %
    Progress: 44.7033691406 %
    Progress: 59.3591308594 %
    Progress: 79.1180419922 %
    Progress: 90.4166666667 %
    >>>
    >>> # The surface enumeration is now complete.
    ... print surfaces.getNumberOfSurfaces(), 'normal surfaces'
    2319 normal surfaces
    >>>