# What does Regina do?

A list of Regina's more noteworthy features is presented below.

### Triangulations

The primary objects that a user works with in Regina are 3-manifold triangulations. As such, a large part of the software is devoted to the creation, analysis and manipulation of these triangulations. Regina can also work with 2-manifold triangulations and recognise their underlying manifolds.

#### Creation

You can create 3-manifold triangulations in the following ways:

- manual construction by entering individual tetrahedron face gluings by hand;

- automatic generation of several standard families of triangulations, such as layered solid tori and layered lens spaces [JR03], [JR06], and standard constructions of Seifert fibred spaces over the sphere;

- reconstruction from text-based isomorphism signatures [Bur11c] and Callahan-Hildebrand-Weeks dehydration strings [CHW99];

- importing triangulations from SnapPea / SnapPy (which now preserves fillings and peripheral curves), and also from Orb;

- automatic construction of several ready-made example triangulations.

#### Analysis

You can compute the following properties of a 3-manifold triangulation:

- detailed combinatorial information about the skeleton and boundary components, including triangulations of the vertex links and the shapes formed by the various triangles (2-faces) within the triangulation;

- a variety of homology and homotopy groups;

- the quantum invariants of Turaev and Viro [TV92];

- the Kawauchi-Kojima invariants of the torsion linking form [KK80], and comments on where the triangulation might be embeddable;

- 3-sphere, 3-ball, solid torus and unknot recognition, as well as connected sum decomposition, irreducibility testing and Hakenness testing;

- triangulation attributes relating to the existence of particular types of normal surface, such as 0-efficiency [JR03] and the existence of splitting surfaces (described below);

- fast and rigorous certification of hyperbolicity (using strict angle structures and linear programming);

- a richer but non-rigorous collection of hyperbolic invariants computed by the SnapPea kernel;

- a visual representation of the face pairing graph [Bur04], with the help of Graphviz;

- text-based isomorphism signatures [Bur11c], which identify a triangulation uniquely up to combinatorial isomorphism;

- Callahan-Hildebrand-Weeks dehydration strings [CHW99], for those triangulations that can support them.

Pairs of triangulations can be tested for direct isomorphism, or for whether one triangulation is isomorphic to a subcomplex of another. In addition the software can recognise and identify a large variety of well-formed structures within a triangulation. These include common building blocks (such as the layered solid tori mentioned above) as well as infinite families of complete triangulations such as those described by Burton [Bur03], [Bur07c], [Bur08a], Martelli and Petronio [MP01] and Matveev [Mat98]. As a result, Regina can frequently recognise the underlying 3-manifolds for well-structured triangulations that it has not previously encountered.

#### Manipulation

You can manipulate a 3-manifold triangulation using the following tools:

- elementary moves (transformations local to a small number of tetrahedra), such as Pachner moves and other transformations described in [Bur07c];

- automated simplification in which the software attempts to use a combination of these elementary moves to reduce the number of tetrahedra as far as possible, though there is no guarantee that the smallest possible number of tetrahedra will be achieved;

- conversion to a 0-efficient triangulation where possible for closed orientable 3-manifolds [JR03];

- barycentric subdivision, truncating ideal vertices (whose links are neither 2-spheres nor discs) to give real boundary components, and conversely coning real boundary components to give ideal vertices;

- conversion of a non-orientable triangulation to an orientable double cover;

- cutting along normal surfaces within a triangulation or crushing them to a point, as described below;

- puncturing manifolds, drilling out neighbourhoods of edges, and building connected sums;

- Dehn fillings for SnapPea triangulations (via the SnapPea kernel).

### Census Creation and Lookup

Regina can be used to form censuses of all 3-manifold triangulations that satisfy various constraints, through the command-line tool tricensus.

The census algorithm is heavily optimised; see [Bur04], [Bur07a] and [Bur11a] for details. There is also an MPI version that can be distributed across a large number of machines for use on high-performance clusters.

Regina ships with a several census databases, including closed 3-manifold triangulations [Bur07b], [Bur07a], [Bur11a], hyperbolic 3-manifolds [Bur14c], [CHW99], [HW94], and knot and link complements (tabulated by Joe Christy).

Regina can also search for a given triangulation across these databases (and indeed across much larger extensions of these databases), using isomorphism signatures [Bur11c], and fast hashing techniques.

### Normal Surfaces

Regina is capable of enumerating all vertex or fundamental normal surfaces within a triangulation; almost normal surfaces[1] are supported also. These operations are required by many high-level topological algorithms that utilise normal surface theory. The underlying enumeration algorithms are highly optimised, and are described in detail in [Bur10a], [Bur09a], [Bur10b], [Bur14a], and [BO13].

This enumeration can be performed in a variety of coordinate systems. For an `n`-tetrahedron triangulation this includes the 7`n` standard triangle and quadrilateral coordinates, as well as the smaller set of 3`n` quadrilateral-only coordinates [Tol98]. Likewise, for almost normal surfaces this includes the 10`n` standard coordinates as well as the 6`n` quadrilateral-octagon coordinates [Bur10b]. Regina also offers experimental support for transversely oriented normal surfaces [CT09].

The enumeration can be restricted to embedded normal surfaces or can be expanded to include immersed and singular surfaces. Regina also supports spun-normal surfaces [Til08], which are non-compact surfaces with infinitely many discs found in ideal triangulations.

To analyse normal surfaces, you can:

- view normal surfaces in a variety of coordinate systems, including the standard and quadrilateral-only coordinates discussed above as well as the edge weight coordinates introduced by Casson;

- calculate basic properties of normal surfaces such as Euler characteristic, orientability and one-sidedness;

- test surfaces for incompressibility, using both exact techniques [JO84] and fast heuristics [BRT12];

- cut along a normal surface and retriangulate, or crush the surface using the techniques of Jaco and Rubinstein [JR03];

- recognise standard surfaces within a triangulation such as splitting surfaces (described below) and vertex and edge links;

- test pairs of surfaces for local compatibility (compatible quadrilaterals and/or octagons) and global compatibility (being able to make the surfaces disjoint);

- filter large lists of normal surfaces by various properties such as Euler characteristic, orientability and boundary.

### Angle Structures

Angle structures, studied originally by Casson and then developed by Lackenby [Lac00a], [Lac00b] and Rivin [Riv94], [Riv03], 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.

Using similar techniques to normal surface enumeration Regina can enumerate all vertex angle structures in a triangulation, or all taut structures (for which each dihedral angle is precisely 0 or π). Regina can also identify veering structures, which are taut structures that induce a specific type of combinatorial structure on the underlying triangulation [Ago11], [HRST11].

For strict angle structures (in which all angles are strictly positive), Regina can test for existence very quickly (and find an explicit example if one exists), using linear programming techniques.

### Splitting Surfaces

A splitting surface contains precisely one quadrilateral disc within each tetrahedron and no other normal or almost normal discs. These surfaces have some interesting combinatorial and topological properties, described in detail in [Bur03].

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, Regina can generate a census of all possible splitting surface signatures of a given size.

### Scripting

Users can interact with Regina at a lower level by writing and running scripts in Python. 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 or run from the command line, and custom libraries of routines can be written to share code between files.

On many systems, default installations of Regina and SnapPy can communicate with each other inside the same Python session. See the Python chapter for details.

### Interfaces

The usual method of running Regina is through a full point-and-click graphical user interface. Alternatively, for those requiring immediate access to the mathematical core of the software, an interactive command-line interface is available for users to control the program using Python scripting as described above. Various other specialised command-line utility programs are also available.

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

### Documentation

Significant effort has been spent on documentation for this software. A full users' handbook is available for Regina (which you are reading now). In addition, the graphical user interface offers extensive assistance through tooltips and "What's This?" texts. Just hit Shift+F1 and click on any element of the user interface for immediate assistance.

For users writing Python scripts or for C++ programmers seeking to modify or extend the software, the full API for Regina's mathematical engine is also extensively documented. You can access the API documentation by selecting Help->Python API Reference.

### Data Files

Regina stores data in a well-organised hierarchical structure, allowing a single data file to contain multiple triangulations, normal surface lists and other topological structures, along with supporting data such as text notes, Python scripts and PDF documents. The file format is based on compressed XML, an open and widely-supported text-based data format. International characters are fully supported.

Again, this XML file format is extensively documented. For details, select Help->File Format Reference.

[1] Almost normal surfaces are closely related to normal surfaces and are used by Rubinstein in his 3-sphere recognition algorithm [Rub95], [Rub97]. Regina only considers octagonal almost normal discs, and does not consider annular pieces.