# What does Regina do?

Some of Regina's more noteworthy features are listed below.

### 3-Manifold Triangulations

Regina's greatest strengths are in 3-manifold topology. Here, the primary objects that a user works with are 3-manifold triangulations. A large part of Regina is devoted to the creation, analysis and manipulation of these triangulations.

#### 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;

- a tree decomposition of the face pairing graph, for use with fixed-parameter tractable algorithms [Bur15];

- 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];

- “greedy” simplification, which uses a fast combination of these elementary moves to reduce the number of tetrahedra as far as possible;

- “exhaustive” simplification, which involves a comprehensive search through the Pachner graph to find simplification moves that the greedy method could not;

- 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).

### 4-Manifold Triangulations

Since version 5.0, Regina now offers rich support for triangulated 4-manifolds.

You can create 4-manifold triangulations using similar methods to 3-manifolds, including manual gluings of pentachora, automatic generation of standard families, reconstruction from isomorphism signatures, and construction of ready-made examples.

To analyse 4-manifold triangulations, Regina offers a similar suite of algebraic and combinatorial tools, including detailed information about the skeleton and edge/vertex links, various homology and homotopy groups, analysis and tree decompositions of the facet pairing graph, isomorphism testing, and isomorphism signatures.

To manipulate 4-manifold triangulations, Regina offers a similar combinatorial toolbox to that for 3-manifolds, including elementary moves, automated simplification, barycentric subdivision, double covers, and converting between ideal and real boundary components.

### Higher Dimensions

Beyond 4-manifolds, Regina offers very basic support support for triangulations of dimensions 5–15. This support is not available through the GUI: for this you will need to use either Python or C++.

Currently this support is limited to basic combinatorial tools, such analysis of the skeleton and face structure of the triangulation, double covers, creating ideal vertices, isomorphism testing, and isomorphism signatures.

The level of support for higher-dimensional triangulations is expected to grow in future releases.

### Census Creation and Lookup

Regina can be used to form censuses of all triangulations that satisfy various constraints, through the command-line tool tricensus. Census enumeration is currently available in dimensions 2, 3 and 4.

The census algorithms are 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 and Hypersurfaces

Regina is capable of enumerating all vertex or fundamental normal surfaces within a 3-manifold triangulation, or all vertex or fundamental normal hypersurfaces within a 4-manifold triangulation. For 3-manifolds, almost normal surfaces[1] are supported also.

These operations—enumerating vertex and fundamental normal surfaces—are required by many high-level topological algorithms for 3-manifolds. The underlying enumeration algorithms are highly optimised, and are described in detail in [Bur10a], [Bur09a], [Bur10b], [Bur14a], and [BO13].

For 3-manifolds, 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/hypersurfaces, or can be expanded to include immersed and singular surfaces/hypersurfaces. Regina also supports spun-normal surfaces [Til08], which are non-compact surfaces with infinitely many discs found in ideal 3-manifold triangulations.

To analyse normal surfaces within a 3-manifold triangulation, 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.

For normal hypersurfaces in a 4-manifold triangulation, some analogous operations are available. In particular, you can view hypersurfaces in different coordinate systems, calculate basic properties, and test for local (but not yet global) compatibility.

### 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 3-manifold 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 within a 3-manifold triangulation 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.