# Introduction

®ina; is a software package for low-dimensional topologists. Historically, its main strengths lie in 3-manifold topology: it has a highly optimised toolkit with a focus on normal surface theory, angle structures, and the combinatorial structures of triangulations, and it now performs many high-level topological algorithms for 3-manifolds. ®ina; also offers rich toolkits for knots and links and triangulated 4-manifolds, and offers more basic combinatorial support for manifolds of dimension 5–8 (and, if you make your own custom build, 9–15). For more on these and its many other features, see the full feature set later in this introduction.

## Getting Started

Not sure how to start ®ina;? You can find it in your main applications or programs menu; follow this link for details and screenshots.

The best way to become familiar with ®ina; is simply to play around with it. ®ina; ships with several example files, including a number of censuses of 3-manifold triangulations. Most of these examples can be accessed through the File Open Example menu when running ®ina;.

For an excellent starting point, try File Open Example Introductory Examples , which illustrates most of the structures that ®ina; can work with. The users' handbook (which you are reading now) also includes a number of sample &python; sessions that illustrate how ®ina;'s in-built &python; scripting can be used.

The graphical user interface offers extensive assistance through tooltips and "What's This?" texts. If you ever want to know what element of the user interface means (such a button or a text field), just press &Shift;F1 and click on the thing you would like to know more about.

®inafeatureset;

## Important Changes in ®ina; 7.0

®ina; 7.0 brought an enormous overhaul across the entire codebase—possibly the largest overhaul in almost two decades. There has been signficant work to insulate users from these changes: the bulk of these changes should only be visible to &cpp; programmers, but there are important behavioural changes that will affect everybody.

Some of these changes break backward compatibility.

If you are migrating from ®ina; ≤ 6.0.1, you should read the brief summary below so you understand the most important changes.

&cpp; and &python; programmers can find a more fine-grained explanation of the &api; changes on the ®ina; website.

### A new, more flexible file format

®ina;'s data file format has changed. ®ina; 7.0 and above can read your old data files, but ®ina; 6.0.1 and earlier will not be able to read files from newer versions of ®ina;.

If you need to export a file so that ®ina; ≤ 6.0.1 can read it, you use the command-line `regconvert` utility, or the File Export menu in the user interface.

A major advantage of the new file format is that different packets no longer depend on each other. In particular, if you create a normal surface, hypersurface or angle structure list from a triangulation, you can later change the triangulation, or move it to a separate location in the tree, or even delete it. The list will make its own copy of the original triangulation if this becomes necessary (which you can access through the header of the normal surface, hypersurface or angle structure viewer). Likewise, the list will bundle this copy of the original triangulation into the data file if necessary.

### Dimensions 9–15 removed by default

For several years, ®ina; has supported triangulations of dimensions 2–15. However, these higher dimensions add significant overhead (even if you are not using them), particularly for &python; users.

For this reason, ®ina; 7.0 and above now only includes dimensions 2–8 by default. In particular, if you open a data file containing triangulations of dimension 9–15 and then save the file again, these triangulations will be lost.

If you need to work with dimensions 9–15, you can make your own custom build of ®ina;; be sure to pass the option `-DHIGHDIM=1` to `cmake`. Also perhaps drop Ben an email so he knows that there are users who want these features.

### &python; is a first-class citizen

For the first time, &python; users now have access to essentially everything inside ®ina;'s &cpp; calculation engine. You can use functions that take callbacks (e.g., the exhaustive retriangulation code, census generation, and subgroup enumeration), and you can access low-level algorithms (e.g., the linear programming code, or the double description method and Hilbert basis enumeration).

&python; now supports iteration wherever &cpp; does, using lightweight iterator objects where possible:

    >>> for e in Example3.lens(8,3).edges():
    ...     print(e)
    ...
    Edge 0, internal, degree 4: 0 (01), 0 (20), 1 (10), 0 (13)
    Edge 1, internal, degree 4: 0 (03), 1 (02), 1 (31), 0 (21)
    Edge 2, internal, degree 4: 0 (23), 1 (30), 1 (23), 1 (12)

Almost all classes now provide a more informative &python; representation:

    >>> ExampleLink.trefoil().group()
    <regina.GroupPresentation: < a b | a^-2 b a b >>

The equality comparisons (`==` and `!=`) now compare their contents by value for most classes. The main exceptions are objects whose location in memory defines them (e.g., faces and simplices in triangulations, or crossings in links), and objects whose purpose is to manage an expensive computation (e.g., progress trackers or census managers); these still compare by reference. Each class has an `equalityType` constant that tells you how its objects are compared.

    >>> Example3.lens(8,3).homology() == AbelianGroup(0, [8])
    True
    >>> AbelianGroup.equalityType
    <EqualityType.BY_VALUE: 1>

In line with the &cpp; changes described below, ®ina; now throws exceptions upon error in some settings instead of returning `None` (e.g., `Triangulation3.fromIsoSig()`); see the &api; documentation for details on which exceptions each function might throw (if any).

Mathematical objects such as triangulations and links are no longer packets (i.e., they do not live in a packet tree or belong to a data file by default); this is for performance reasons. If you just want to work with a triangulation or link, you can use `Triangulation3` or `Link` as before; however, if you want to insert one of these objects into a packet tree then you will need to use the corresponding classes `PacketOfTriangulation3` or `PacketOfLink` (and so on for other types of object). These packet classes inherit from `Triangulation3`, `Link`, etc., and can be used in much the same way. You can use the new `make_packet()` functions to help you convert between the classes.

    >>> ExampleLink.figureEight()
    <regina.Link: 4-crossing knot: ++-- ( _0 ^1 _2 ^3 _1 ^0 _3 ^2 )>
    >>> make_packet(ExampleLink.figureEight())
    <regina.PacketOfLink: 4-crossing knot: ++-- ( _0 ^1 _2 ^3 _1 ^0 _3 ^2 )>

Finally, although there are far fewer changes to the &python; &api; than for &cpp;, there is one change that will likely affect most people: to enumerate normal surfaces or angle structures, you no longer use the old `enumerate()` functions. Instead, just create a new `NormalSurfaces` or `AngleStructures` object:

    >>> t = Example3.poincare()
    >>> s = NormalSurfaces(t, NormalCoords.Standard)
    >>> print(s)
    7 embedded, vertex surfaces (Standard normal (tri-quad))

### &cpp; embraces modern standards and value semantics

®ina; began in the late 1990s, before &cpp; was ever standardised. Since then, ®ina;'s &api; has slowly evolved as the language changed, incrementally making use of new language features, and removing old workarounds as they became no longer necessary.

One of the most important changes to the &cpp; language was the much improved value semantics that came with &cpp11;. When used with the new &cpp11; move operations, this made it both easy and efficient to pass large objects around by value, not by pointer. The resulting code reads more naturally, is typically less error-prone, avoids the need for manual memory management, and still retains the performance of the old pointer-based code.

In ®ina; 7.0, the &cpp; &api; underwent a complete overhaul from head to toe. The &api; switched to the &cpp17; standard (and has moved again to newer standards in subsequent releases). Widespread changes include:

- ®ina; now uses value semantics across the board. So, for example, `Triangulation<3>::fromIsoSig()` now returns a `Triangulation<3>` by value. Most of your objects should now be able to live on the stack; in general there should no need for manual memory management via `new` and `delete`. The main exceptions are objects that are defined by their locations in memory, such as faces and simplices in triangulations, or crossings in links: these are still passed by pointer, but their memory is safely managed by their enclosing triangulations or links.

- Likewise, functions that used to return newly-allocated pointers now return by value. If they used to return `null` when unexpected errors occurred, they typically now throw exceptions; if they used to return `null` in ordinary scenarios where there is no solution, they typically now return a `std::optional`.

- When returning polymorphic objects (such as `Packet` or `StandardTriangulation`), you cannot avoid returning by pointer since the exact type is not known at compile time. In such cases, ®ina; now returns a smart pointer (typically `std::shared_ptr` for packets and `std::unique_ptr` for other types of object).

- Functions that used to take arguments by pointer now typically take them either by value or by const reference. Many functions that used to return multiple values via reference arguments now return a `std::tuple` instead.

- The class hierarchies have been simplified considerably. Hopefully one side-effect of this is that the &api; documentation is easier to navigate.

- Functions that take callbacks (such as census generation or exhaustive retriangulation) are now more flexible, and can work with lambdas and arbitrary lists of properly-typed arguments. They no longer take function pointers with untyped `(void*)` arguments.

- Packets are now managed exclusively by shared pointers. You should never be holding on to to a raw pointer to a packet type. The large mathematical classes such as `Triangulation<dim>` and `Link` are no longer packet types, since this frees them from considerable overhead; if you need to insert them into a packet tree then you should use `PacketOf<Triangulation<3>>`, `PacketOf<Link>`, and so on. There is a new suite of `make_packet()` functions to help you with this.

Since ®ina; 7.0 was a “big release” that broke backward compatibility, this was a good time to clean up and simplify many other unwieldy parts of the &api;. These changes range from simple renamings (e.g., `StandardTriangulation::isStandardTriangulation` becomes `StandardTriangulation::recognise`) through to major semantic changes (e.g., each normal surface now stores an encoding, which is to some degree independent of the coordinate system that was used to create it).

If you are writing &cpp; code that links against ®ina;, you will need to change your code. Generally the issues should be flagged by the compiler (not discovered at runtime), and the necessary changes should be obvious. Some old functions have been kept but marked as deprecated to ease the transition; your compiler should warn you also if you are still using these.

### TONS removed temporarily

For a long time, ®ina; has offered “experimental” support for transversely oriented normal surfaces (TONS). This always came with large caveats and promises that things would break, and needed to be explicitly enabled before it could be used.

Now that the normal surface classes have undergone a major redesign, TONS no longer fits cleanly into the normal surface model (since in some fundamental sense they are not normal surfaces), and so this support has been removed completely from ®ina;.

The intention is to reimplement TONS “properly” in a future release, using their own separate suite of classes that more accurately reflect what they are and how they behave.

## Genealogy

In 1997 in Melbourne, David Letscher, Richard Rannard and Ben Burton under the guidance of J. Hyam Rubinstein planned out a program that would do normal surface theory and everything else besides. Much groundwork planning was done, epsilon code was written and then things kind of faded away. David Letscher revived the project on his own and in 1999 presented Normal 1.0. This program performed triangulation simplification and found vertex normal surfaces, was written in &java; and was a proof-of-concept program that normal surface theory was computationally feasible.

In March 1999, David and Ben sat down to write a new version of the program from scratch. The new version would have a calculation engine written in &cpp; for speed and would have a &java; GUI for portability. It would be carefully designed and written with rigour and extensibility in mind, allowing for the possibility of add-ons written by other people.

David however leads a busy life and pulled out of the project in late 2000, but remained to offer technical advice. In late 2000 a prerelease of the new program was ready and ®ina; 2.0 was uploaded to the web.

Since then, many more people have been involved in both small ways and large. ®ina; has also undergone some major structural changes over the years:

- In late 2003 the old &java; user interface was completely removed in favour of a faster and cleaner native &cpp; user interface using the &kde; libraries.

- In 2012 the interface was ported to &qt; with enormous help from William Pettersson; this offered a much cleaner experience on &macosx; and allowed ®ina; to run properly on &windows; for the first time.

- In 2016 the underlying &cpp; code was redeveloped in a much more generic style, merging the existing 3-manifolds code with a long-running project with Ryan Budney on 4-manifolds, and creating a new infrastructure for exploring triangulations in dimensions as high as 15.

- In 2021 the entire &cpp; codebase was redeveloped to support and embrace a cleaner style of programming that is supported by modern &cpp; standards, and the &python; interface was redeveloped to make &python; a “first class citizen”, with a consistent experience and full access to all of ®ina;'s internal code.

## Citing Regina

If you find ®ina; useful in your research, please consider citing it as you would any other paper that you use. A suggested form of reference is:

> Benjamin A. Burton, Ryan Budney, William Pettersson, et al., Regina: Software for low-dimensional topology, `http://regina-normal.github.io/`, 1999–2025.

A &bibtex; entry for this reference is included below.

    @misc{regina,
        author = {Benjamin A. Burton and Ryan Budney and William Pettersson and others},
        title = {Regina: Software for low-dimensional topology},
        howpublished = {{\tt http://\allowbreak regina-normal.\allowbreak
            github.\allowbreak io/}},
        year = {1999--2025}
    }

## Who is Regina?

This normal surface theory software has been named after Regina Basman who once told me she was the most normal person I knew. She's studied mathematics, reads interesting books, has a gorgeous child and likes running around rainforests in the dark.