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.90
Software for 3-manifold topology and normal surface theory
Copyright (c) 1999-2011, 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 = regina.NTriangulation()
>>> t.insertLayeredSolidTorus(3,4)
<regina.NTetrahedron object at 0x10046ac20>
>>> print t
Triangulation with 3 tetrahedra.
>>> 
>>> # Print the full skeleton of the triangulation.
... print t.toStringLong()
Size of the skeleton:
  Tetrahedra: 3
  Faces: 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

Faces:
  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.
... from regina import NNormalSurfaceList
>>> surfaces = NNormalSurfaceList.enumerate(t, NNormalSurfaceList.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.toStringLong()
Embedded vertex normal surfaces
Coordinates: Standard normal (tri-quad)
Number of surfaces is 9
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
1 1 0 0 ; 0 0 1 || 1 1 0 0 ; 0 0 0 || 0 0 0 0 ; 0 1 0
1 1 1 1 ; 0 0 0 || 1 1 0 0 ; 1 0 0 || 0 0 0 0 ; 0 2 0
0 0 0 0 ; 0 0 2 || 0 0 0 0 ; 0 2 0 || 0 0 1 1 ; 1 0 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 = 0 ; Or = true
Chi = 0 ; Or = true
Chi = 0 ; Or = false
Chi = -1 ; Or = true
Chi = 0 ; Or = true
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.90
Software for 3-manifold topology and normal surface theory
Copyright (c) 1999-2011, 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.
... from regina import NBoolSet
>>> census = regina.NContainer()
>>> regina.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.NTriangulation object at 0x10046ade0>
<regina.NTriangulation object at 0x10046ad70>
<regina.NTriangulation object at 0x10046aec0>
<regina.NTriangulation object at 0x10046ac90>
<regina.NTriangulation object at 0x10046ae50>
<regina.NTriangulation object at 0x10046ad70>
>>> 
>>> # 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.90
Software for 3-manifold topology and normal surface theory
Copyright (c) 1999-2011, 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 = regina.NTriangulation.fromIsoSig(sig)
>>> print tri.getNumberOfTetrahedra(), 'tetrahedra'
18 tetrahedra
>>> 
>>> # Create a progress manager to use during the normal surface enumeration.
... # This will report the state of progress while the enumeration runs in
... # the background.
... manager = regina.NProgressManager()
>>> 
>>> # Start the normal surface enumeration.
... # Because we are passing a progress manager to enumerate(), the
... # enumeration will start in the background and control will return
... # immediately to the python console.
... surfaces = regina.NNormalSurfaceList.enumerate(tri,
...     regina.NNormalSurfaceList.STANDARD, 1, manager)
>>> 
>>> # Wait for the surface enumeration to fully start up.
... while not manager.isStarted():
...     time.sleep(1)
... 
>>> 
>>> # At this point the enumeration is up and running.
... # Output a progress report every second until it finishes.
... prog = manager.getProgress()
>>> while not manager.isFinished():
...     print 'Progress:', prog.getDescription()
...     time.sleep(1)
... 
Progress: 17/21
Progress: 17/21
Progress: 19/21
Progress: 19/21
>>> 
>>> # The surface enumeration is now complete.
... print surfaces.getNumberOfSurfaces(), 'normal surfaces'
2319 normal surfaces
>>> 
>>> # Output the total time spent during the surface enumeration.
... print 'Total real time:', prog.getRealTime(), 'seconds'
Total real time: 5 seconds
>>> print 'Total cpu time:', prog.totalCPUTime(), 'seconds'
Total cpu time: 4 seconds
>>>