SnapPea 3.0
Scripting

SnapPea 3.0 is organized as a set of Python classes, which sit on top of the SnapPea kernel. For simple scripts you might be able to modify the samples below to suit your purposes. For more extensive work, you may obtain good Python documentation online from the Python web site, or in printed form from amazon.com.

As you read the following examples, you may want to follow along on your own computer. To start Python on a unix machine, simply type python at the shell prompt:

jeff$ python
Python 1.5.1 (#1, Mar 21 1999, 22:49:36)
[GCC egcs-2.91.66 19990314/Li on linux-i386
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>>

The >>> is Python's own prompt. You type Python commands at the prompt, each followed by a return. When you are done, type Control-D to quit. Python does not understand quit or exit.

At its most basic level, Python is a calculator:

>>> 2 + 2
4

You may extend Python's modest built-in capabilities by importing the functions from the math library:

>>> from math import *
>>> pi
3.14159265359
>>> cos(pi/4)
0.707106781187

Python lets you use variables in the obvious way:

>>> a = 7
>>> b = 10
>>> a + b
17

Variables are not typed. They may be integers, floating point numbers, strings, lists (illustrated here), and even Triangulations or AbelianGroups (illustrated later in this document). Note that list elements are accessed with square brackets.

>>> a = [1, 'two', 3.0]
>>> a[0]
1
>>> a[1]
'two'
>>> a[2]
3.0

To use SnapPea within Python, always begin with
from SnapPea import * 

>>> from SnapPea import *
>>> t = Triangulation('MyFile')
>>> t

name:      MyFile
volume:    2.029883
homology:  Z
Dehn fillings:
  0      complete

The preceding example reads a Triangulation from MyFile and assigns it to the variable t. Printing t reveals some basic information about the Triangulation. We may ask for additional information about t by calling its methods (functions).

>>> t.fundamental_group()
generators:  a,b,c
relations:
aCAbc
aBcb

The data returned by a method may, of course, be assigned to a variable of its own, and queried further. 

>>> h = t.homology()
>>> h
Z
>>> h.Betti_number()
1

The Cusped Census manifolds are available as shown below, specifying the number of tetrahedra (5, 6, or 7) and the orientability ('o' for orientable or 'n' for nonorientable). If no orientability is given, the default is 'o'. If no number of tetrahedra is given, the default is 5. In the following example, a is the nonorientable 6-tetrahedron census, b and c are both the orientable 6-tetrahedron census, and d is the 5-tetrahedron census.

>>> a = CuspedCensus(6, 'n')
>>> b = CuspedCensus(6, 'o')
>>> c = CuspedCensus(6)
>>> d = CuspedCensus()

(As in SnapPea 2.x, the 5-tetrahedron census is exceptional in two ways: it contains all cusped hyperbolic 3-manifolds, orientable and nonorientable, obtainable from 5 or fewer tetrahedra. Its orientability parameter -- the 'n' in CuspedCensus(5, 'n') -- is ignored.)

Once we have a CuspedCensus, we may read manifolds from it. For example, the 0th manifold in the 5-tetrahedron census is the Gieseking, and the 4th manifold is the figure eight knot complement.

>>> d = CuspedCensus()
>>> s = d[0]
>>> s

name:      m000
volume:    1.014942
homology:  Z
Dehn fillings:
  0      complete

>>> t = d[4]
>>> t

name:      m004
volume:    2.029883
homology:  Z
Dehn fillings:
  0      complete

Python offers control structures similar to those of C. Note that

  1. the indentation determines the block structure (no curly brackets!), and
  2. the use of the colon.

>>> a = [3, 5, 7, 9]
>>> for n in a:
...     m = n*n
...     print n, m
...
3 9
5 25
7 49
9 81

The same syntax works with Triangulations:

>>> for t in CuspedCensus(5):
...     t.volume()
...
1.01494160641
1.83193118835
2.02988321282
2.02988321282
2.02988321282
2.40690959305
etc.

If were interested only in the manifolds with first Betti number at least 2, it would be easy to select them out:

>>> for t in CuspedCensus(5):
...     if t.homology().Betti_number() > 1:
...         print t.get_name(), t.volume(), t.homology()
...
m124 3.66386237671 Z/2 + Z + Z
m125 3.66386237671 Z + Z
m128 3.66386237671 Z + Z
etc.

Typing scripts at the python prompt is frustrating, because if you make even the smallest mistake you need to retype the whole thing. A better approach is to type the script into a file (using a text editor, not python), such as the following:

links.py 
#   links.py

#   Search for link complements in the 5-tetrahedron census.

#   Note:  The pound sign (#) introduces comments.

from SnapPea import *

#   Examine each Triangulation in the 5-tetrahedron census.

for t in CuspedCensus():

    #   For each cusp, do a Dehn filling on the shortest
    #   curve, which, by SnapPea's convention, is the
    #   meridional filling (1,0).
    for i in range(t.get_num_cusps()):
        t.set_cusp(i, 1, 0)
        
    #   We now have a closed manifold.
    #   Look at its fundamental group, and if the
    #   number of generators is zero (meaning the
    #   group is trivial), print the name of
    #   the original Triangulation, which we have shown
    #   to be a link complement in a homotopy sphere.
    if t.fundamental_group().num_generators() == 0:
        print t.get_name()

To run the script (under Unix) you may either pass it to Python at the shell prompt...

jeff$ python links.py
m004
m015
m016
etc.

...or import it within the Python interpreter (without the .py suffix).

jeff$ python
Python 1.5.1 (#1, Mar 21 1999, 22:49:36)  [GCC egcs-2.91.66 19990314/Li on linux-i386
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import links
m004
m015
m016
etc.

I will eventually provide systematic documentation of SnapPea 3.0's objects and their methods. In the meantime, you may glean this information from the file SnapPea.py.

And speaking of documentation, I'm eager to have your feedback on how this documentation should be developed. Please let me know what you would find useful. Send comments to Jeff Weeks.

For interactive work, use SnapPea 3.0's graphical user interface.

up