Snappea Tutorial

This tutorial walks you through the most useful features of
the 'snappea' (pronounced "snap pea", like the vegetable) hyperbolic
structures programs.

[ UNIX users: snappea sometimes writes things out to files, and it
  always does this relative to the directory from which you invoke it.
  Sometimes the files go into subdirectories of the current directory
  (with names like "generators", "Dirichlet_domains", ...), and snappea
  will create these subdirectories if they don't yet exist.  If you
  plan to use snappea very much it might be a good idea to create a
  snappea "work directory" to work in, and then always invoke snappea
  from that directory. ]

(0)  If you are using a Mac, start the program by double-clicking on
     the program icon.  If you are using a UNIX workstation, start it
     by typing "snappea" at the shell prompt.  You should get a
     "select program" prompt.  Snappea is really an umbrella program
     which gives you access to several constituent programs.
     (Eventually there'll be a smoother interface for all this.)

(1a) If you are using a Mac, type "l" (that's the letter "el") to
     start the link entry program.  If you are not using a Mac, skip
     down to step 2; the link entry program is not yet available on
     other systems.

(1b) Use the mouse to draw the figure eight knot.  Click to make the
     vertices.  To close a component, click on the initial vertex.  By
     the way, if you attempt to add a segment that's not in general
     position relative to what you've already drawn the program will
     beep at you and refuse to add that segment.  You can now adjust
     the crossings (over vs. under) by clicking on them, or you can
     choose Alternate from the Edit menu to fix them all at once.

(1c) Choose Save... from the File menu to save the link you have
     drawn.  Give it a one-word name like "fig8".  First the program
     saves the projection in a folder called "link projections" (which
     it creates if necessary), then it triangulates the complement,
     finds a hyperbolic structure for it, and saves the result in the
     folder "manifolds" (which it also creates if necessary).  It tells
     1you something about the hyperbolic structure; when you're done
     looking at the information, click the mouse to return to the main
     link entry program.  If you want, you can play around with the
     other menu commands, which are all self-explanatory.

     [Note: when you save link complements the manifold's cusps will
     be numbered in the same order you drew the corresponding link
     components.]

(1d) Choose Quit Link Entry from the File menu.


(2a) Type "d" to start the Dehn filling program.  At the "which
     manifold" prompt, type "fig8" (or whatever you called your figure
     eight knot complement).  If you were not able to do step 1
     because you are not using a Mac, type "figure8" which will cause
     snappea to load the figure eight knot complement from its
     supplied library of manifolds.  You'll see some information about
     this manifold.

(2b) If you are on a Mac, or an IRIS with geomview, type "dd" (for
     Dirichlet domain) and after a brief computation you'll see a
     Dirichlet domain for the figure eight knot complement.  [ On an
     IRIS it may take several seconds for geomview to appear. ] Drag
     it with the mouse to rotate it.  If you let go of the mouse
     button while the mouse is still moving the Dirichlet polyhedron
     will keep spinning.

     On Macs: hit Command-S for a see-through Dirichlet domain.  Click
     the close box of the viewing window when you're done playing with
     the Dirichlet domain.

     On IRISes with geomview: you can use all the features of geomview
     to view and manipulate the Dirichlet domain.  See the geomview
     documentation for details.

     On UNIX workstations without geomview: typing "dd" will cause
     snappea to write an OOGL file containing the Dirichlet domain.
     Snappea will prompt you for the name of this file.  You can then
     view this file with geomview on an IRIS somewhere if you have
     access to one.

     On any computer: if you type "ddf" instead of "dd", snappea will
     prompt you for the name of a file and will write an OOGL data
     file by that name containing the Dirichlet domain.

(2c) Type "5 1" to ask snappea to do (5, 1) Dehn filling on the figure
     eight knot complement.  You'll see the volume and homology of
     this closed hyperbolic 3-manifold, and also the length and
     torsion of the core geodesic of the filled in solid torus.  Type
     "dd" to see the Dirichlet domain (the computation will be a
     little slower this time (particularly on a MacPlus or SE)).  Note
     the tetrahedral symmetry.  The program finds Dirichlet domains
     centered at points of locally maximal injectivity radius.

(2d) Type "com" to return to the complete hyperbolic structure for the
     figure eight knot complement.  Type "cs" to toggle the Chern-
     Simons calculator on.  You'll be asked for the Chern-Simons
     invariant of the present configuration.  The present
     configuration is the complete structure on the figure eight knot
     complement, and its Chern-Simons invariant is 0, so type 0.  Then
     type "5 1" again, and this time the Chern-Simons invariant will
     be displayed along with the other information.

(2e) Type "gen" to create a set of generators (in PSL(2,C)) for the
     fundamental group of this manifold.  (This will take several
     seconds.)  A file containing the generators will be created
     automatically and saved in a folder/directory called generators
     under the name "fig8(5,1)".

(2f) Type "-5 1" and you'll see that (-5,1) Dehn filling has the same
     invariants as the (+5,1) Dehn filling.  Are they isometric?  Type
     "gen" to create the generators for the (-5,1) filling, and then
     type "diff" to compare the two files (you just hit return twice
     to have diff use the two most recently computed sets of
     generators, which is what we want).  You'll see that the lists of
     generators are complex conjugate, which means that the (+5,1)
     filling and (-5,1) filling are isometric, but oppositely
     oriented.

     Technical comments (optional): When the generators are different
     you can't conclude that the manifolds are nonisometric, because
     the generators might have been computed relative to different
     basepoints.  The basepoint is always a local maximum of the
     injectivity radius function, but there may be several such local
     maxima.  In pratice this is seldom a problem.  (Also, one can
     obtain different basepoints by using different starting points in
     the basepoint finding algorithm, but I still haven't settled on a
     good user interface for this.)  When two manifolds are not
     isometric you have to use other invariants to distinguish them.

     For manifolds obtained by doing several Dehn fillings on a
     multicusp manifold the Dirichlet domain program occasionally
     fails due to the excessive roundoff error which accumulates
     during the computation of the canonical basepoint.  There's a
     compile-time option to use larger error tolerances (the drawback
     to larger error tolerances is that when you go to do high-order
     Dehn fillings, which yield Dirichlet domains with lots of tiny
     faces, some of the tiniest faces get swallowed up entirely by the
     error tolerances).  Get in touch with me if you have problems
     with these algorithms not working for the cases you are
     interested in.

     Note: the Dehn fillings needn't be on the same cusped manifold.
     For example, the program will show you that m003(-1,3) and
     m004(5,1) are isometric.  ("m003" and "m004" will be explained
     below)

(2g) Type "complete" (or just "com") to return to the complete (i.e.
     not Dehn filled) hyperbolic structure on the figure eight knot
     complement.  At the ">" prompt type "ls" to compute a complex
     length spectrum ("complex" means it includes both the length and
     the torsion for each closed geodesic included).  Type "2.5" for
     "tiling radius" and 2.0 for "cutoff length".  After a short
     computation (or a long computation if you're using a MacPlus)
     you'll be prompted for a file name under which to store the list
     of lengths and torsions of closed geodesics up to length 2.0.
     The file will be placed in a directory called "length spectra",
     which the program creates if necessary.  You may examine this
     file using any word processor (e.g. the one you use to read this
     tutorial).  Note that because the figure eight knot complement
     has an orientation reversing symmetry each closed geodesic has a
     mate of the same length but opposite torsion. If you compute a
     length spectrum for the (5,1) Dehn filling (by typing "5 1", then
     "ls", "2.5", "2.0" and a file name) you'll see that the lengths
     do not occur in matched pairs, which implies that the manifold is
     chiral.

     New feature: typing "tube" at the ">" prompt will compute a tube
     radius of each geodesic.  I recommend a radius of about 2.0.
     Warning: the tube radius algorithm is not carefully thought out,
     so I don't guarantee its correctness.

     Technical comments on choosing values for the "tiling radius" and
     the "cutoff length".  You should probably just skip this material
     and go on to paragraph (2h) below, but if you are particularly
     interested in length spectra, then read on.  The program computes
     length spectra by tiling hyperbolic space with lifts of a
     (hypothetical) fundamental domain.  To decide when to stop
     tiling, it keeps track of how far each group element translates
     the basepoint.  If the basepoint is translated a distance less
     than the "tiling radius", the program continues its recursive
     tiling by considering the lifts obtained by multiplying the given
     group element by each generator in a precomputed generating set.
     When the recursion is complete the program computes the complex
     length associated to each group element it found, and reports the
     lengths whose real part (i.e. the actual length, ignoring
     torsion) is less than the "cutoff length".

     Obviously the "cutoff length" should be less than the "tiling
     radius".  In practice, "tiling radius" = "cutoff length" + 0.5
     works well.  If you want to verify the result you can run it
     again with "tiling radius" = "cutoff length" + 1.0.  Using
     "cutoff length" = 3.0 and tiling radius = 3.5 gives fast results;
     "cutoff length" = 3.5 and "tiling radius" = 4.0 is also tolerably
     fast.  The number of group elements increases exponentialy with
     the distance, of course, so you can go a little beyond that (say
     to 5.0) but not a whole lot further.

     If you want to check out the accuracy more systematically (e.g.
     if you find a particularly interesting set of spectra) I
     recommend the following procedure.  Do, say, "tiling radius" =
     "cutoff length" = 3.5, then do "tiling radius" = "cutoff length"
     = 4.0 and see where the first new length occurs.  You can be
     fairly certain that the spectrum is complete up to that point.

     Finding a delta such that the list of lengths up to the "cutoff
     length" is guaranteed to be complete when the "tiling radius" is
     greater than "cutoff length" + delta is tricky, even for a fixed
     "cutoff length".  The catch is that is is theoretically possible
     that the recursion could terminate (having reached lifts all of
     which translate the basepoint a distance greater than "tiling
     radius") and still miss some lifts which are further away in a
     combinatorial sense yet nevertheless translate the basepoint a
     distance less than the "tiling radius".  (In practice this will
     occur seldom if at all.)  Fortunately it is still possible to get
     some bounds which will rigorously guarantee the completeless of
     the reported length spectrum.  In the case of a closed manifold
     with fundamental domain of radius delta, one can prove that the
     reported length spectrum will be complete when "tiling radius" >
     "cutoff length" + 2*delta.  Unfortunately this bound isn't much
     good for manifolds with short geodesics (because delta will be
     large, which makes the prescribed "tiling radius" intractibly
     large) and for cusped manifolds it's useless.  Other techniques
     are possible in the latter cases (namely getting bounds on how
     far a closed geodesic of length less than "cutoff length" can
     travel up the cusp) but they are messy and I haven't pursued
     them.

(2h) Hit return at the ">" prompt to stop doing Dehn fillings on the
     figure eight knot complement, then hit return again at the "which
     manifold" prompt to quit the Dehn filling program.


(3)  There are five ways to create new manifolds.  Each will be described
     below.  For reference, here's the list of all five ways.

     (a)  Use the link entry program [on the Mac only].
     (b)  Recall manifolds from the "census" (i.e. data base) of all
          cusped hyperbolic 3-manifolds obtainable from 5 or fewer
          ideal tetrahedra.
     (c)  Recall manifolds from the census of all orientable cusped
          hyperbolic 3-manifolds obtainable from 6 ideal tetrahedra.
     (d)  Recall manifolds from the link library which contains all the
          knots and links which appear in the standard tables (e.g.
          Rolfsen).
     (e)  Create punctured torus bundles.

     You can, of course, do Dehn fillings on manifolds obtained in any
     of the above ways.

(3a) The link entry program was described above.

(3b)  Return to the Dehn filling program by typing "Dehn" (or just "d")
      and at the "which manifold?" prompt type "m003".  This calls up
      a manifold from the so-called "census" of all 415 cusped
      hyperbolic 3-manifolds obtainable from 5 or fewer ideal
      tetrahedra.  The census manifolds are named m000 through m414,
      and are listed in order of increasing volume (e.g. m000 is the
      Gieseking).  A table giving various invariants for these
      manifolds is available.  Note that even though the manifold m003
      has the same volume as the figure eight knot complement, it has
      first homology Z + Z5, and is therefore not a knot complement.

      These "census manifolds" are my favorite source of examples
      because they are completely general and thus provide a better
      idea of what hyperbolic manifolds are like than one gets by,
      say, looking only at knot and link complements.  Both orientable
      and nonorientable manifolds are included in the census.

      The census manifolds are stored in a "dehydrated" form and are
      "rehydrated" on the fly whenever you need to use one.  That's
      why you get the message about "rehydrating m003... solution
      found...".

(3c) A similar library exists for the 962 orientable manifolds
     obtainable from 6 (but not fewer) ideal tetrahedra.  They are
     named "s000" through "s961".  Similarly, the 3552 orientable
     manifolds obtained from 7 (but not fewer) ideal tetrahedra are
     named "v000" through "v3551".

(3d) Hit return at the ">" prompt to close the m003 manifold, and at
     the "which manifold" prompt type "L306002".  This gives you the
     Borromean rings complement.  All the knots and links from the
     standard tables are available, as well as 11-crossing knots and
     10-crossing links (thanks to Joe Christy).  The n-th knot or link
     of m crossings and p components is named "Lpmmnnn" (e.g. the
     Borromean rings are the second 6-crossing 3-component link).  You
     can do Dehn fillings on the Borromean rings like you did on the
     figure eight knot complement.  The program will start you off
     doing Dehn fillings on cusp number 0.  To change to one of the
     other cusps, type "cusp 1" or "cusp 2".  At any point you may
     view the shapes of the tetrahedra (given as complex edge
     parameters) and the Dehn filling coefficients of the cusps by
     typing "view".  For a complete listing of the commands available
     in the Dehn_filling program, type "help" at the ">" prompt.

     When you're done with the Borromean rings hit return at the ">"
     prompt and again at the "which manifold" prompt to leave the Dehn
     filling program.

     Note: if you want to rehydrate all the links in the link library
     and save them in the manifolds folder/directory (so you don't
     have to rehydrate them on the fly) type "r" at the "select
     program" prompt.  This operation takes a while, so you probably
     don't want to do it now.

(3e) At the "select program" prompt type "bundles" (or just "b") to
     enter the punctured torus bundle program.  Type "+" for the sign
     of the determinant, "+" for the sign of the trace, and "RL" for
     the RL factorization, and you will see that you've created a
     manifold of the same volume (2.02...) as the figure eight knot
     complement and the manifold m003.

     The information you provided gives a factorization of the
     monodromy of the desired bundle.  The string of R's and L's
     provides a factorization in terms of the 2 x 2 matrices R =
     (1,1;0,1) and L = (1,0;1,1).  In addition, if you specify "-" for
     the determinant the result will be multiplied by (0,1;1,0), and
     if you specify "-" for the trace the result will be multiplied by
     (-1,0;0,-1).  (Note: the string of R's and L's read left to right
     determines the sequence of matrices read right to left.)

     Type "+" for the determinant, "-" for the trace, and RL for the
     RL-factorization.  You'll get another manifold of volume 2.02... .

     Hit return to leave the bundle program.

     Warning: At the moment the meridian and longitude on the cusp of
     a punctured torus bundle are the ones natural relative to the
     Euclidean structure on the cusp (namely the shortest and second
     shortest curves), NOT the usual meridian and longitude one
     expects to find on a punctured torus bundle.  In the near future
     I will write the code to put on the ones natural to the bundle.


(4)  Go back to the Dehn filling program and examine the manifolds
     "B++RL" and "B+-RL" you just created, and also the census
     manifolds m003 and m004.  An examination of the various
     invariants for these manifolds suggests that B++RL is isometric
     to m004 and B+-RL is isometric to m003.  To prove they are
     isometric you can ask snappea to compute a canonical
     triangulation for each and then check whether the canonical
     triangulations are combinatorially the same.  To do this, hit
     return to leave the Dehn filling program, and then type
     "isometric" (or just "i") to use the isometry checker.  Provide
     the names B++RL and m004 and snappea will tell you they are
     isometric; Provide B++RL and m003 snappea will tell you they're
     different.  While you're at it you can show that B++RL = m004 =
     L104001 = fig8.  When you're done hit return to leave the
     isometry checker.

     The canonical triangulations are dual to the Ford domain.  In
     rare cases the cell-division dual to the Ford domain contains
     cells other than tetrahedra, and in these cases there is no
     unique canonical triangulation.  Snappea will report this
     ambiguity and refuse to speculate on whether the manifolds are
     the same (unless they happen to have the same triangulations to
     begin with).  I hope to correct this deficiency in the future.

     Note: There are two ways to check whether two manifolds are
     isometric: you can check canonical triangulations as just
     described, or you can compute generators for the group of
     covering transformations as described in (2f) above.  Comparing
     canonical triangulations has several advantages:

     (i)   It's faster.
     (ii)  It works in virtually all cases.
     (iii) In the final analysis it is comparing two combinatorial
           triangulations, so there is absolutely no possibility of
           round-off error leading to a "false positive" result.

     By contrast, two very high order Dehn fillings on a cusped
     manifold will have nearly identical generators.  (In fact,
     comparision of generators MUST fail to resolve some such pairs of
     manifolds because any finite computer can represent only a finite
     number of distinct matrices, yet there are infinitely many
     distinct high order Dehn fillings.)

     It has one disadvantage, namely that it can be used only for the
     original cusped hyperbolic 3-manifolds, not for the manifolds
     represented as Dehn fillings.


(5)  If you are not using a Mac, skip this step. If you are using a
     Mac, at the "select program" prompt type "p" to use "pretty
     pictures", and at the "which manifold" prompt type "L306002" to
     get the Borromean rings.  A couple messages with advice for
     printing hard copies will appear; you can safely ignore them for
     now.  Type "0" to take a look at cusp number 0.  You'll be asked
     for a lower bound on the diameter of the horoballs you want
     plotted.  On a Mac II or SE/30 (or any newer Mac with a floating
     point coprocessor) 0.2 is a reasonable choice.  If you've got a
     MacPlus or SE, try 0.3 or 0.35.  (The number of horoballs grows
     outrageously fast as the minimum diameter decreases, so the
     difference in time and memory requirements between 0.3 and 0.2 is
     more than you might expect.)  A blank screen with a menu bar
     appears.  (If you're lucky enough to have a color monitor you
     should, at this point, choose the Color Monitor option on the
     Options menu.  If you have THINK C you can later change a
     #defined constant to make the Color Monitor option on by
     default.)  (In the new SnapPea the program will take care of
     these matters automatically.)  Choose the Horoballs item from the
     Draw menu.  A picture will appear which shows the view in the
     manifold as seen looking down cusp 0 "from infinity". The view in
     the manifold is, of course, the same as the view in the universal
     cover.  Each disk you see is a lift to the universal cover of a
     horospherical neighborhood of one of the cusps.  The program
     chooses the largest horospherical neighborhoods which have equal
     volumes and disjoint interiors.  Different fill patterns (or
     different colors on a color monitor) distinguigh the different
     cusps.  (You can choose Fill Patterns from the Draw menu to see
     which pattern/color corresponds to which cusp.)  You are, of
     course, looking at the manifold from inside one of the
     horospherical neighborhoods; we imagine its horospherical
     boundary is opaque from the outside but transparent from the
     inside so that it doesn't hide the other horoballs.

     A more prosaic interpretation of the horoball picture is that
     it's the universal cover of the manifold as represented in the
     upper half space model of hyperbolic 3-space, viewed from above,
     with the boundary of the current cusp represented as a horizontal
     plane at height one (the horizontal plane at height one is not
     explicitly shown in the picture to avoid hiding the other
     horoballs).

     Play around with the various Draw menu commands and Options menu
     options, and when you are done choose Quit Drawing to return to
     the console.  You may now draw the pictures for cusps 1 and 2 if
     you wish (but because the Borromean rings is so symmetrical the
     pictures will be the same as for cusp 0, only with the fill
     patterns permuted).

     When you're done with the Borromean rings hit return in response
     to "which cusp".  If you want to look at other examples, the
     first ten or twenty census manifolds (m000 - m020) offer some
     nice patterns.  It's also interesting to create a punctured torus
     bundle whose RL-factorization is almost but not quite periodic,
     like B+-RLRLLLRLRLRLRLRLLRLRLRL.  (Note: the console window
     supports copy-and-paste, so you never have to retype those long
     bundle names by hand.  I.e. copy the name from the bundle program
     and paste it into the pretty pictures program at the "which
     manifold" prompt.)  When you're done, hit return at the "which
     manifold" prompt to leave pretty pictures.

(6)  SnapPea can compute symmetry groups of manifolds.  Type
     "symmetries" (or just "s") at the "select program" prompt, and
     enter the name of whatever manifold interests you.  For example,
     you'll find that the symmetry group of m003 is Z/2 x Z/4, and the
     symmetry group of m004 is the dihedral group D4 (a group of order
     8).  SnapPea reports both the symmetry group of the manifold and
     the symmetry group of the corresponding link.  For a manifold
     which you created as a knot or link complement to begin with, the
     symmetry group of the link is just what you expect it to be; in
     general, the symmetry group of the "link" is defined to be the
     subgroup of the full symmetry group consisting of those
     symmetries which take meridians to meridians in whatever
     coordinate system is employed on the boundary components of the
     manifold.

(7)  Last but not least, snappea can compute presentations for
     fundamental groups.  At the "select program" prompt type "f" (for
     "fundamental group"), and when asked "which manifold" type
     "L306002" for the Borromean rings.  You'll see a presentation for
     the fundamental group of the Borromean rings, followed by the
     words representing the peripheral curves.  You are now in an
     environment similar to the Dehn filling environment.  In response
     to the "pi one>" prompt, type "1 0" to do a (1,0) Dehn filling on
     cusp 0 of the Borromean rings.  You will be told that the
     fundamental group of the Dehn filled manifold is a free group on
     two generators.  Type "info" (or just "i") to see the status of
     all cusps.  (By convention (0,0) means that a cusp is unfilled.)
     Try some other Dehn fillings on this cusp, and then return to the
     (1,0) Dehn filling before proceeding.  Type "cusp 1" (or just "c
     1") to switch to cusp 1.  Type "1 0" to do a (1,0) Dehn filling
     on this cusp and you'll see that the fundamental group of the
     result is the integers.  Type "info" to see the status of the
     cusps if you want.  Now type "c 2" and "1 0" to switch to cusp 2
     and do a (1,0) Dehn filling.  Snappea will tell you that you have
     a homotopy sphere.  Hit return when you're done.

     For more information on the programs available within snappea,
     type "help" at the "select program" prompt.

     By the way, the snappea console window on the Mac really is
     resizable, even though it has no resizing box and the cursor is
     always an I-beam!  Just move the cursor to the lower right hand
     corner of the window, pretend there's a resizing box, and
     everything will work fine.

     Note: Many of the longer computations can be aborted by holding
     down control-C until the word "CANCEL" appears.

     I am eager to receive any and all comments and suggestions for
     improving these programs, from major additions to minor
     annoyances and typos.  Please send comments and questions to
     weeks@poincare.geom.umn.edu or Jeff Weeks, Geometry Supercomputer
     Project, 1200 Washington Ave. S., Minneapolis, MN 55415.  Thanks.

CREDITS:

Craig Hodgson has done large amounts of the programming, particularly
in the routines to compute the Chern-Simons invariant and the
quasicanonical generators for the groups, and in the enumeration of
closed manifolds.  More generally he has contributed to the design of
the entire project from the very beginning.  More recently, Joe
Christy has made substantial contributions, and is coauthoring the GUI
for the new SnapPea.  The winged edge data structure in the Dirichlet
domain program is from a Dirichlet domain program written by Charlie
Gunn, which was the inspiration for the present one.  Diane Hoffoss
wrote the routine which generates lists of "nearby" group elements and
computes length spectra.  Martin Hildebrand did most of the work on
the Census.  Colin Adams, Bob Meyerhoff and Walter Neumann have also
made significant contributions.  Bill Thurston is responsible for most
of the mathematics underlying these programs.

The Geometry Center Home Page

Comments to: webmaster@www.geom.uiuc.edu
Created: Feb 08 1996 --- Last modified: Jun 18 1996