What does Regina do?

The primary objects with which a user interacts when running Regina are 3-manifold triangulations. As such a large part of the software is devoted to the creation, analysis and manipulation of triangulations.

Regina can be used to form a census of all 3-manifold triangulations satisfying a particular set of census constraints. The command-line tool tricensus is particularly well suited for this task.

Elements of the census algorithm are described in [Bu2] and [Bu5]. The algorithm contains significant optimisations for censuses of closed minimal P²-irreducible triangulations — in particular, the face pairing graph results of [Bu3] and [Bu5] are incorporated into the algorithm, as are several more local structural results relating to vertices, edges and faces [Bu3], [CHW], [Ma].

Census creation can require significant amounts of computing time (months or years in some cases). As a result, support is provided for splitting this process into pieces that can be distributed across several machines. An MPI version is also provided for use on high-performance clusters.

In addition to forming new censuses, Regina ships with a number of prepackaged censuses including closed 3-manifold triangulations [Bu4], [Bu5], hyperbolic 3-manifolds [CHW], [HW], and knot and link complements (tabulated by Joe Christy). A census lookup facility for arbitrary triangulations is provided.

Providing a computational tool for the study of normal surfaces was in fact the original motivation for writing this software. As such, Regina is capable of enumerating all vertex normal surfaces or almost normal surfaces^[1] of a triangulation, an operation required by most high-level topological algorithms that utilise normal surface theory.

This vertex enumeration can be performed in a variety of coordinate systems. For an n-tetrahedron triangulation this includes the 7n standard triangle and quadrilateral coordinates, as well as the smaller set of 3n quadrilateral-only coordinates introduced by Tollefson for algorithmic efficiency [To]. The enumeration can be restricted to embedded normal surfaces or can be expanded to include immersed and singular surfaces. Furthermore, elementary support is present for spun normal surfaces, discussed in detail by Tillmann [Ti], which are non-compact surfaces with infinitely many discs found in ideal triangulations.

For the analysis of normal surfaces, Regina offers the following facilities.

In addition the program can crush a normal surface to a point within a triangulation. Crushing is a powerful tool for the analysis of the role played by a surface within a 3-manifold, and is used in Jaco and Rubinstein's 0-efficiency algorithm [JR1].

A related but significantly more complex procedure is the cutting open of a triangulation along a normal surface and the retriangulation of the resulting 3-manifold(s). This procedure was introduced by Haken [Ha] for attacking the homeomorphism problem and has been used in a variety of algorithms since. Like crushing, this procedure is a powerful tool and furthermore avoids the difficulties suffered by the crushing process in which topological information can be lost or (in the non-orientable case) invalid 3-manifold triangulations can be created.

Cutting along a surface however is more difficult than crushing since the individual tetrahedra containing the normal discs can become heavily subdivided. The many potential combinations of discs lead to many different ways in which this subdivision might take place, all of which must remain compatible with adjacent tetrahedra. The implementation of such a routine thereby becomes lengthy and exceptionally error-prone. For this reason cutting along a surface is planned but not implemented in Regina at the present time.

Angle structures, studied originally by Casson and then developed by Lackenby [La1], [La2] and Rivin [Ri1], [Ri2], represent a purely algebraic generalisation of hyperbolic structures. An angle structure on an ideal triangulation is formed by assigning an interior dihedral angle to each edge of every tetrahedron in such a way that a variety of linear equations and inequalities are satisfied.

The formation of angle structures is remarkably similar to the formation of normal surfaces, in which a series of triangle and quadrilateral coordinates are assigned to every tetrahedron with a set of linear equations and inequalities similarly imposed upon them. Thus it has been relatively straightforward to extend the normal surface enumeration code used by Regina in such a way that the software can also enumerate vertex angle structures.

Included in the requirements of an angle structure is the condition that each dihedral angle t satisfies 0 <= t <= Pi. In addition to the enumeration of vertex angle structures, Regina can identify whether a triangulation supports any strict angle structures (for which each dihedral angle t satisfies 0 < t < Pi) or any taut angle structures (for which each dihedral angle is precisely 0 or Pi).

Splitting surfaces represent a particular class of normal surfaces whose presence can offer insight into the triangulations containing them. A splitting surface contains precisely one quadrilateral disc within each tetrahedron and no other normal or almost normal discs. These surfaces have a number of interesting combinatorial and topological properties, described in detail in [Bu1].

As mentioned earlier, Regina can detect whether splitting surfaces occur within a triangulation. It also provides support for splitting surface signatures, which are compact text-based representations from which splitting surfaces and their enclosing 3-manifold triangulations can be reconstructed. In addition to reconstructing triangulations from signatures in this way, the software is capable of forming a census of all possible splitting surface signatures of a given size.

Regina offers the ability to write and run arbitrary scripts in the Python scripting language. These scripts are essentially high-level programs with immediate access to the mathematical core of Regina, and are ideal for performing repetitive tasks over large sets of data. Such tasks might include performing a sequence of tests upon all triangulations in a census, or testing a prototype for a new algorithm. Scripts can be embedded in Regina data files and custom libraries of routines can be written to share code between files.

The usual method of running Regina provides a full graphical interface that a user can easily understand and use. Alternatively, for those requiring immediate access to the mathematical core of the software, an interactive command-line interface is offered from which users can control the program using the Python scripting language described above. A variety of specialised utility programs are also available.

The mathematical core of Regina is provided as a C++ library, which means that programmers are able to access these mathematical routines directly from within their own code.

Significant effort has been spent on documentation for the software. A full users' handbook is available for Regina (you are reading this handbook now). In addition, the graphical user interface offers extensive assistance through tooltips and "What's This?" texts. For users writing Python scripts or for programmers seeking to modify or extend the software, the routines offered by the underlying mathematical core are also fully documented.

The data files used for saving triangulations and other information conform to a well-organised hierarchical structure. This structure not only allows multiple triangulations, normal surface lists and other topological structures to be stored together in an organised fashion but it also supports the storing of miscellaneous data such as text notes and Python scripts. The file format is well documented in the users' handbook and uses compressed XML^[2], allowing for the simple transfer of native Regina data to and from other programs. International characters are fully supported.