# What does Regina do?

Some of ®ina;'s more noteworthy features are listed below.

## 3-Manifold Triangulations

®ina;'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 ®ina; 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 bib-0-efficiency, bib-layeredlensspaces, and standard constructions of &sfslong;s over the sphere;

- reconstruction from text-based isomorphism signatures bib-burton-pachner-orprime and Callahan-Hildebrand-Weeks dehydration strings bib-cuspedcensus;

- building new triangulations from old, such as via orientable double covers, or doubling over the boundary;

- building triangulations from framed links, using the command-line tool &katie;;

- importing triangulations from &snappeapylink; (which now preserves fillings and peripheral curves), and also from &orburl;;

- 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 bib-turaevviro;

- the Kawauchi-Kojima invariants of the torsion linking form bib-kktorsionlinkingform, and comments on where the triangulation might be embeddable;

- 3-sphere, 3-ball, handlebody 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 bib-0-efficiency 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 bib-burton-facegraphs, with the help of &graphviz;;

- a tree decomposition of the face pairing graph, for use with fixed-parameter tractable algorithms bib-turaevviro-fpt;

- text-based isomorphism signatures bib-burton-pachner-orprime, which identify a triangulation uniquely up to combinatorial isomorphism;

- Callahan-Hildebrand-Weeks dehydration strings bib-cuspedcensus, 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 bib-burton-phd, bib-burton-nor7, bib-burton-satblocks, Martelli and Petronio bib-italian9 and Matveev bib-matveev6. As a result, ®ina; 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 bib-burton-nor7;

- “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 bib-0-efficiency;

- barycentric subdivision, truncating vertices, and creating ideal vertices by coning boundary components;

- retriangulating in an attempt to reduce the treewidth;

- 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

®ina; also 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, building from framed links, and constructing ready-made examples.

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

To manipulate 4-manifold triangulations, ®ina; 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, ®ina; offers very basic support support for triangulations of dimensions 5–8 (and, if you make your own custom build, 9–15). This support is not available through the &gui;: for this you will need to use either &python; or &cpp;.

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.

## Knots and Links

®ina; offers native support for knots and links, including classical as well as virtual links.

You can create knots and links from Gauss, Dowker-Thistlethwaite or planar diagram codes, knot/link signatures, parameterised families of knots and links, or construction of ready-made examples. You can also create new links from old, such as through composition, Whitehead doubles, and parallel cables.

®ina; computes several link invariants including the Alexander, Jones, &homflypt;, arrow and affine index polynomials, and the link group and extended link group. It allows you to build and study the underlying 4-valent graph and its tree decompositions, offers tools for isomorphism testing and isomorphism signatures, and allows you to build the knot/link complement as a 3-manifold triangulation.

To manipulate knots and links, you can edit individual crossings, perform individual Reidemeister moves, run sophisticated simplification algorithms, and search for ways to reduce the treewidth.

## Census Creation and Lookup

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

The census algorithms are heavily optimised; see bib-burton-facegraphs, bib-burton-nor10 and bib-burton-genus for details.

®ina; ships with several census databases, including closed 3-manifold triangulations bib-burton-nor8, bib-burton-nor10, bib-burton-genus, hyperbolic 3-manifolds bib-burton-complete, bib-cuspedcensus, bib-closedhypcensus, and knots and links bib-burton-knots.

®ina; can also search for a given triangulation across these databases (and indeed across much larger extensions of these databases), using isomorphism signatures bib-burton-pachner-orprime, and fast hashing techniques.

## Normal Surfaces and Hypersurfaces

®ina; 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

Almost normal surfaces are closely related to normal surfaces and are used by Rubinstein in his 3-sphere recognition algorithm bib-rubin-3sphere1, bib-rubin-3sphere2. ®ina; only considers octagonal almost normal discs, and does not consider annular pieces.

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 bib-burton-dd, bib-burton-convert, bib-burton-quadoct, bib-burton-fund, and bib-bo-tree.

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 bib-quadspace. Likewise, for almost normal surfaces this includes the 10`n` standard coordinates as well as the 6`n` quadrilateral-octagon coordinates bib-burton-quadoct.

The enumeration can be restricted to embedded normal surfaces/hypersurfaces, or can be expanded to include immersed and singular surfaces/hypersurfaces. ®ina; also supports spun-normal surfaces bib-tillus-spun, 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 bib-jaco-oertel and fast heuristics bib-weber-seifert;

- cut along a normal surface and retriangulate, or crush the surface using the techniques of Jaco and Rubinstein bib-0-efficiency;

- recognise standard surfaces within a triangulation such as splitting surfaces (described below) and thin or normalised vertex, edge and triangle 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 bib-lackenby-taut, bib-lackenby-anglestruct and Rivin bib-rivin-structures, bib-rivin-combopt, 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, ®ina; can enumerate all vertex angle structures in a triangulation, or all taut structures (for which each dihedral angle is precisely 0 or π). ®ina; can also identify veering structures, which are taut structures that induce a specific type of combinatorial structure on the underlying triangulation bib-agol-ideal, bib-hodgson-veering.

For strict angle structures (in which all angles are strictly positive) or generalised angle structures (where negative angles are allowed), ®ina; can test for existence very quickly and find an explicit example if one exists, using techniques from linear programming and linear algebra.

## 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 bib-burton-phd.

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

## Scripting

Users can interact with ®ina; 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 ®ina;, 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 ®ina; 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 ®ina; and &snappy; can communicate with each other inside the same &python; session. See the &python; chapter for details.

If you build ®ina; from source, you have the option of working with either &python; 2 or &python; 3. (If you download a ready-made package, then the package maintainer will have made this choice for you.)

## Interfaces

The usual method of running ®ina; 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 ®ina; is provided as a &cpp; 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 ®ina; (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 &cpp; programmers seeking to modify or extend the software, the full &api; for ®ina;'s mathematical engine is also extensively documented. You can access the &api; documentation by selecting Help Python API Reference .

## Data Files

®ina; 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 .