# Command Line: Specialised Utilities

The main applications `regina-gui` and `regina-python` are documented in the previous chapter. This chapter documents some additional command-line utilities that ®ina; provides for specialised mathematical and logistical tasks.

censuslookup

1

censuslookup

Search for triangulations in ®ina;'s census databases

        censuslookup
        isosig

        censuslookup
        &versionhelpopts;

### Description

This utility searches for the given 3-manifold triangulations in the various census databases that are shipped with®ina;.

You should present the trianguations using their isomorphism signatures. These are short text strings that identify the triangulation uniquely up to combinatorial isomorphism (i.e., up to relabellings of the tetrahedra and/or their vertices).

From the graphical user interface, you can view the isomorphism signature of a triangulation by switching to the Composition tab in the triangulation viewer. From &python; you can fetch the isomorphism signature of the triangulation `x` by calling `x.isoSig()`. For a full and precise specification of isomorphism signatures, see Simplification paths in the Pachner graphs of closed orientable 3-manifold triangulations, Burton, 2011, arXiv:1110.6080.

All database matches (if any) will be written to standard output.

### Options

&versionhelpdesc;

### Environment Variables

The following environment variables influence the behaviour of this program.

`REGINA_HOME`

- The directory beneath which ®ina;'s data files are installed. This utility will look for the census databases in the subdirectory ``$REGINA_HOME`/data/census/`.

  Normally you should not need to set this option yourself. This utility should know how to find its census databases in standard situations, which include fixed filesystem installations (e.g., &linux; and &windows;), relocatable app bundles (e.g., &macosx;), and running directly from the source tree.

### Example

        example$ censuslookup fvPQcdecedekrsnrs dLQbcccajqs cPcbbbiht
        fvPQcdecedekrsnrs: 1 hit
            SFS [S2: (2,1) (3,1) (5,-4)] : #1 -- Closed census (orientable)

        dLQbcccajqs: 0 hits

        cPcbbbiht: 2 hits
            m004 : #1 -- Cusped hyperbolic census (orientable)
            L104001 -- Hyperbolic knot and link complements

        example$

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/censuslookup`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\censuslookup.exe`.

### See Also

regina-gui. trisetcmp,

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

katie

1

katie

Triangulate a 3-manifold or 4-manifold from a decorated link

        katie
        pd_code
        framing_vector

         -3, --dim3
         -4, --dim4

        -g, --graph
        -V, --verbose

        katie
        &versionhelpopts;

### Description

This utility builds a triangulation or coloured graph of a 3-manifold or 4-manifold from a decorated link.

For 3-manifolds, the manifold constructed is the one obtained by performing integer Dehn surgery on the given link.

For 4-manifolds, the manifold constructed is the one obtained by attaching 4-dimensional 1- and 2-handles to the 4-ball along the dotted and framed link components, respectively.

&katie; expects two arguments at runtime: the underlying (undecorated) link, and a list of space-separated decorations (framing coefficients and/or 1-handle "markers").

- The link should be given in the format of a planar diagram (PD) code, specifically, in the same format as used by &snappy;. The simplest way to achieve this is to draw the link in &snappy;'s &plink; editor, and copy the PD code generated by &snappy; via the Info PD Code menu option in the editor.

- Within the framing sequence, use `'x'` or `'.'` to denote 1-handles.

The PD code and the framing sequence must appear as the first two arguments. If you are running &katie; from a shell, you will need to wrap both of these arguments in quotation marks.

For more information, see the full &katie; manual, available from .

### Options

`-3, --dim3`

- Build the 3-manifold obtained from integer Dehn surgery on the input link.

  If you do not pass either `--dim3` or `--dim4`, the default is to build a 4-manifold.

`-4, --dim4`

- Build the 4-manifold obtained by attaching 1- and 2-handles along the components of the decorated link to the 4-ball.

  This option is the default if you do not pass either `--dim3` or `--dim4`.

`-g, --graph`

- Output an edge list of the edge-coloured graph associated to the manifold. Each node of the graph corresponds to a tetrahedron in the case of 3-manifolds or to a pentachoron in the case of 4-manifolds. Two nodes are connected by a `c`-coloured edge if the two corresponding top-dimensional simplices of the triangulation have the facets opposite to the vertex labelled `c` identified.

`-V, --verbose`

- Display information during the construction.

&versionhelpdesc;

### Examples

The following builds the &poincare; homology 3-sphere obtained by +1 surgery along the right handed trefoil knot.

        example$ katie "[(6,4,1,3),(4,2,5,1),(2,6,3,5)]" "1" -3
        Writhes:
        Component 0: 2-handle, writhe 1

        Here is the isomorphism signature:
        GLvvQvPvALvzMAQAvAQQQPccgfekjp...
        example$

The following builds the complex projective plane by attaching a single 2-handle to the 4-ball along a +1 framed unknot.

        example$ katie "[(1,1,2,2)]" "1"
        Writhes:
        Component 0: 2-handle, writhe 1

        Here is the isomorphism signature:
        mLvAwAQAPQQcfffhijgjgjkkklklll...
        example$

The following builds a 4-manifold containing both a 1- and a 2-handle.

        example$ katie "[(4,8,1,9),(9,3,10,4),(1,5,2,6),(6,2,7,3),(7,5,8,10)]" "x 0"
        Writhes:
        Component 0: 1-handle (0)
        Component 1: 2-handle, writhe 0

        Here is the isomorphism signature:
        SLvAvAAwvvALMQQPvPvPMQwQAQMAvQ...
        example$

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/katie`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\katie.exe`.

### Author

This utility was written by Rhuaidi Burke rhuaidi.burke@uq.edu.au. &manpageack;

regconcat

1

regconcat

Combine several ®ina; data files

        regconcat
        -o output-file
        input-file

        regconcat
        &versionhelpopts;

### Description

This utility combines several individual ®ina; data files into a single larger data file. The new file will have a container as its top-level packet, and beneath this container will be the packet trees from each of the input files that you supply.

If an output file is specified through option `-o`, the new file will be written as compressed &xml; to this output file. Otherwise the new file will be written as uncompressed &xml; to standard output.

### Options

`-o` `output-file`

- Specifies that the new combined data file should be written as compressed &xml; to the given output file.

&versionhelpdesc;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/regconcat`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\regconcat.exe`.

### See Also

regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

regconvert

1

regconvert

Convert between different ®ina; file formats

        regconvert

         -2
         -3

         -x
         -u

        old-file
        new-file

        regconvert
        &versionhelpopts;

### Description

This utility converts back and forth between different ®ina; file formats.

®ina;'s file formats include:

Third-generation &xml;

This is the modern &xml; format introduced in ®ina; 7.0. Older versions of ®ina; (6.0.1 and below) cannot read it at all.

Second-generation &xml;

This is the original &xml; format that was used in ®ina; 3.0–6.0.1 (from 2002–2021). Current versions of ®ina; can still read and write this format if required.

First-generation binary format

This is the ancient binary format that was used in ®ina; 2.x (from 2000–2002). Support for this format was dropped completely in September 2013, and modern versions of ®ina; cannot read or write it.

If you still have ancient files that use this format, you will need to find a copy of ®ina; 3.0–4.93 (from 2002–2012), which can convert these old binary files to the second-generation &xml; format.

The argument `old-file` should be the file to read and convert; the argument `new-file` should be the name of the new converted file to write. These two filenames may be the same, in which case the old file will be replaced with the new.

If the argument `new-file` is missing then the new file will be written to standard output, which forces the output to be uncompressed &xml; (see option `-u`).

### Options

`-2`

- Convert to the older second-generation &xml; format, as used in ®ina; 3.0–6.0.1.

`-3` (default)

- Convert to the modern third-generation &xml; format, introduced in ®ina; 7.0.

`-x` (default)

- Write the output as compressed &xml;.

`-u`

- Write the output as uncompressed (plain text) &xml;.

&versionhelpdesc;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/regconvert`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\regconvert.exe`.

### See Also

regfiletype, regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

regfiledump

1

regfiledump

Dump the contents of a ®ina; data file

        regfiledump

         -f
         -l
         -n

        -c
        file
        packet-label

        regfiledump
        &versionhelpopts;

### Description

This utility dumps the contents of the given ®ina; data file to standard output in a human-readable format.

If a list of packet labels is given on the command-line, only those packets will be output. Otherwise all packets in the given file will be output.

### Options

`-f` (default)

- Output full packet details. The output for each packet will cover several lines, beginning with basic details (such as the packet label and type) followed by the packet's long description.

`-l`

- Output a list of packet labels and types only, one packet per line.

`-n`

- Don't output any packets at all; this option forces a packet count (see option `-c`).

`-c`

- Finish the output with a total count of all packets in the file.

&versionhelpdesc;
&submani18n;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/regfiledump`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\regfiledump.exe`.

### See Also

regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

regfiletype

1

regfiletype

Identify the formats of ®ina; data files

        regfiletype
        file

        regfiletype
        &versionhelpopts;

### Description

This utility determines which file format a given ®ina; data file is in. You may pass multiple files on the command line; the format of each file will be written to standard output.

Only ®ina;'s modern &xml;-based file formats are recognised (both compressed and uncompressed). In its very early years, ®ina; used an impenetrable and undocumented binary format; this was replaced with &xml; in 2002 (®ina; 3.0), and support for this format was removed completely in 2013 (®ina; 4.94). If you still need to recognise and/or read files in this ancient binary format, you will need to download ®ina; 4.93.

### Options

&versionhelpdesc;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/regfiletype`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\regfiletype.exe`.

### See Also

regconvert, regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

retriangulate

1

retriangulate

Exhaustively search through triangulations or knot/link diagrams using local moves

        retriangulate
        -h, --height=height
        -t, --threads=threads

         -3, --dim3
         -4, --dim4
         -k, --knot

        -l, --all
        -a, --anysig

         -c, --classical
         -V, --virtual

        --
        signature

        retriangulate
        &versionhelpopts;

### Description

Given a 3-manifold triangulation, 4-manifold triangulation or link diagram, this utility uses local moves to exhaustively search for other triangulations/diagrams of the same manifold/link that are the same size or smaller. Here “local moves” means Pachner moves for triangulations, or Reidemeister moves for links.

Specifically, suppose the input triangulation or link diagram contains `n` tetrahedra/pentachora/crossings (for a 3-manifold, 4-manifold or link respectively). Then this utility will exhaustively modify the triangulation or link diagram using local moves, without ever exceeding `n` + `height` tetrahedra/pentachora/crossings in total. Moreover, all such triangulations/diagrams are guaranteed to be found, each once and only once (up to an appropriate notion of combinatorial isomorphism).

Regarding what constitutes a “local move”:

- For 3-manifold triangulations, this utility will only attempt 2-3 and 2-3 Pachner moves, never 1-4 or 4-1 moves.

- For 4-manifold triangulations, this utility will use all types of Pachner moves.

- For link diagrams, this utility will use all of the classical (planar) Reidemeister moves. There is also the option to use the virtual (non-planar) type II move, which adds two crossings by pushing any two strands over one another from any direction, and which could thereby add a handle to the surface in which the diagram is embedded. By default, the virtual type II move is considered only if the input diagram has positive virtual genus (i.e., is not a classical diagram); this behaviour can be modified using the options `--classical` and `--virtual`.

The input is assumed to represent a 3-manifold triangulation unless one of the options `--dim4` or `--knot` is passed.

The program will output each triangulation or link diagram that it finds of the same size `n` (including the original input triangulation/diagram). If it ever finds a smaller triangulation or diagram (thereby proving the original to be non-minimal), it will output that smaller triangulation/diagram and then stop immediately. Otherwise it will continue outputting triangulations or diagrams of size `n` until no more can be found. Although the program also finds larger triangulations/diagrams as part of its exhaustive search using local moves, these larger triangulations/diagrams (of which there are typically many) will not be output unless the option `--all` is passed.

All triangulations or link diagrams, both input and output, are described using isomorphism signatures and knot/link signatures respectively. These are short text strings that identify a triangulation or link diagram uniquely up to combinatorial isomorphism (which includes relabellings of tetrahedra/pentachora/crossings, relabellings of the vertices of tetrahedra/pentachora vertices, and various rotation/reflection/reversal operations on link diagrams).

To view the isomorphism signature of a triangulation: in ®ina;'s graphical user interface you can find this in the Composition tab in the triangulation viewer, and in &python; you can call `t.isoSig()` for a triangulation `t`. To view a knot/link signature: in ®ina;'s graphical user interface this is available through the Codes tab in the knot/link viewer, and in &python; you can call `d.sig()` for a link diagram `d`.

For a full and precise specification of isomorphism signatures for 3-manifolds, see Simplification paths in the Pachner graphs of closed orientable 3-manifold triangulations, Burton, 2011, arXiv:1110.6080.

Very large triangulations or links have signatures that begin with a dash (`-`). Such a signature could be mistaken for an option when passing it on the command line. To avoid this, you can pass the special option `--` immediately before it: this indicates that all command-line options have finished, and whatever comes next should be treated as the input signature.

        example$ retriangulate -h1 -- -b-LLvALwvM...

### Options

`-h, --height=``height`

- Specifies the number of additional tetrahedra, pentachora or crossings (for a 3-manifold, 4-manifold or link respectively) that we allow during intermediate stages of retriangulation. That is, if the input triangulation or link diagram has `n` tetrahedra/pentachora/crossings, then this utility will exhaustively search through all triangulations or link diagrams that it can reach via local moves that do not exceed `n` + `height` tetrahedra/pentachora/crossings in total.

  Note that these larger intermediate triangulations or diagrams will not be written to output; however, a larger height may allow the program to access additional smaller triangulations or diagrams that were otherwise inaccessible.

  The given height must be a non-negative integer. In addition, for 3-manifolds it must be strictly positive, and for 4-manifolds it must be even.

  If not specified, this option defaults to 1 when working with 3-manifolds or link diagrams, and it defaults to 2 when working with 4-manifolds.

  In general, the running time can grow superexponentially with `height`. It is strongly suggested that you begin with `--height=1` (or 2 for 4-manifolds) and increase it one step at a time until the performance becomes unacceptable.

`-t, --threads=``threads`

- Specifies the degree to which this utility uses parallel processing. Specifically, this program will use `threads` simultaneous threads of execution as it works its way through the different retriangulations or diagrams of the input manifold or link.

  This program is typically able to use parallelism effectively, and so running with `k` threads should approximately divide the running time by `k`.

  If not specified, this option defaults to 1 (i.e., single-threaded processing, with no parallelism).

`-3, --dim3` (default)

- Indicates that the given signature is the isomorphism signature of a 3-manifold triangulation. The local moves used will be 2-3 and 3-2 Pachner moves.

  This is the default if none of the arguments `--dim3`, `--dim4` or `--knot` is passed.

`-4, --dim4`

- Indicates that the given signature is the isomorphism signature of a 4-manifold triangulation. The local moves used will be 1-5, 2-4, 3-3, 4-2 and 5-1 Pachner moves.

`-k, --knot`

- Indicates that the given signature is a knot/link signature. The local moves used will be the Reidemeister moves, possibly including the virtual type II move; see `--classical` and `--virtual` for details.

`-l, --all`

- Output the signatures of all triangulations or link diagrams that are visited, including those that are larger than the original.

  By default, larger triangulations or link diagrams (of which there may be very many) are not included in the output.

`-a, --anysig`

- Indicates that the output is not required to be classic isomorphism signatures.

  ®ina; 7.0 introduced alternate types of isomorphism signatures. Like the original isomorphism signatures that were introduced many years earlier, each type of signature uniquely identifies a triangulation up to combinatorial isomorphism. Moreover, ®ina; can reconstruct a triangulation or link from a signature of any type.

  Internally, this utility uses one of the newer, alternate types of signature that is faster to compute. However, it still outputs classic signatures; that is, the same isomorphism signatures that were originally introduced back in 2011. This conversion from alternate to classic signatures adds extra overhead to the running time.

  If you pass the option `--anysig`, ®ina; will not convert its output back to classic signatures; instead it will output whatever alternate signature type it uses internally. This will be faster, and you can still use these alternate signatures to reconstruct triangulations; the only reason not to do this is if you neeed to ensure compatibility with the original classical signatures (e.g., for matching against a list of signatures that was generated elsewhere).

  The internal signature type is subject to change in future versions of ®ina;. That is, if you do use `--anysig`, then you may get different output depending upon which version of ®ina; you are using.

  Currently ®ina; only uses alternate signature types with triangulations. For knot/link signatures, it still uses classic signatures, though again this is subject to change in future version of ®ina;.

`-c, --classical`

- For link diagrams, only use the classical type I, II and III Reidemeister moves. This is the default behaviour when the input is a classical (planar) link diagram.

  This option can only be used with `--knot`.

`-V, --virtual`

- For link diagrams, use the classical type I, II and III Reidemeister moves as well as the virtual type II move. The virtual type II move is like the classical type II move to add two crossings, except that we are allowed to push any two strands over one another from any direction; as a consequence, this could add a handle to the surface in which the link diagram is embedded. This option is the default behaviour when the input is a link diagram with positive virtual genus (i.e., a non-classical link diagram).

  This option can only be used with `--knot`.

`--`

- Indicates that all other options have finished, and whatever comes next on the command line should be treated as the input signature.

  This is useful when your signature begins with a dash, to avoid confusing your input signature with a regular command line option.

&versionhelpdesc;

### Examples

The following 3-manifold triangulation is non-minimal, but it requires a bit of work to see this:

        example$ retriangulate -h2 hLLAAkbdceefggdonxdjxn
        hLLAAkbdceefggdonxdjxn
        hLALPkbcbefgfghxwnxark
        Found 2 triangulation(s).
        example$ retriangulate -h3 hLLAAkbdceefggdonxdjxn
        hLLAAkbdceefggdonxdjxn
        hLALPkbcbefgfghxwnxark
        hLLMMkbcdfefgglcghtchj
        gLLPQcdcefffqsjpunw
        Triangulation is non-minimal!
        Smaller triangulation: gLLPQcdcefffqsjpunw
        example$

Although the program stopped as soon as it found a smaller triangulation, this can be simplified even further:

        example$ retriangulate gLLPQcdcefffqsjpunw
        gLLPQcdcefffqsjpunw
        fLAMcbbcdeedhwhxn
        Triangulation is non-minimal!
        Smaller triangulation: fLAMcbbcdeedhwhxn
        example$

A little more probing shows this to be the cusped hyperbolic manifold `m112`:

        example$ censuslookup fLAMcbbcdeedhwhxn
        fLAMcbbcdeedhwhxn: 1 hit
            m112 : #2 -- Cusped hyperbolic census (orientable)

        example$

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/retriangulate`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\retriangulate.exe`.

### See Also

regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

sigcensus

1

sigcensus

Form a census of splitting surface signatures

        sigcensus
        order

        sigcensus
        &versionhelpopts;

### Description

Forms a census of all splitting surface signatures of the given order. The order is the number of quadrilaterals in the resulting splitting surface.

The signatures will be written to standard output, one per line, followed by a count of the total number of signatures found.

Each signature will be output precisely once up to equivalence. Signatures are considered equivalent if they are related by some combination of:

- relabelling symbols;

- rotating an individual cycle;

- inverting an individual cycle (i.e., reversing the cycle and changing the case of each symbol in the cycle);

- reversing all cycles without changing the case of any symbols.

Upper-case symbols in signatures are not yet supported; this program will only output signatures whose symbols are all lower-case.

For more information on splitting surface signatures, see Burton's PhD thesis at ®manburtonthesisurl;.

### Options

&versionhelpdesc;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/sigcensus`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\sigcensus.exe`.

### See Also

censuslookup, tricensus, regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

tricensus

1

tricensus

Form a census of triangulations

        tricensus
        -t, --tetrahedra=tetrahedra

         -2, --dim2
         -4, --dim4

         -b, --boundary
         -i, --internal
         -B, --bdryfaces=triangles

         -o, --orientable
         -n, --nonorientable

         -f, --finite
         -d, --ideal

         -m, --minimal
         -M, --minprime
         -N, --minprimep2
         -h, --minhyp

        --allowinvalid

         -s, --sigs
         -S, --canonical
         -e, --encodings
         -c, --subcontainers

         -p, --genpairs
         -P, --usepairs

        --threads=num_threads
        output-file

        tricensus
        &versionhelpopts;

### Description

Forms a census of all 2-, 3- or 4-manifold triangulations that satisfy some set of conditions.

These conditions are specified using various command-line arguments. The only condition that you must provide is the number of top-dimensional simplices (e.g., the number of tetrahedra for 3-manifolds), but there are many other options available.

The default behaviour is to enumerate 3-manifold triangulations. If you wish to enumerate 2-manifold or 4-manifold triangulations instead, you must pass `--dim2` or `--dim4` respectively.

Each triangulation will be output precisely once up to combinatorial isomorphism. Invalid triangulations (for 3-manifolds, this means triangulations with edges identified to themselves in reverse, or vertices whose links have boundary but are not discs) will not be output at all.

As the census progresses, the state of progress will be written (slowly) to standard output. Once the census is complete, the full census will be saved to the given output file.

You can use the options `--genpairs` and `--usepairs` to split a census into smaller pieces.

A census with even a small number of top-dimensional simplices can take an incredibly long time to run, and can chew up massive amounts of memory. It is recommended that you try very small censuses to begin with (such as 3 or 4 simplices), and work upwards to establish the limits of your machine.

For very large census runs, it is highly recommended that you use the either the `--sigs` or `--encodings` option, which will keep the output file small and significantly reduce the memory footprint.

### Options

`-t, --tetrahedra=``tetrahedra`

- Specifies the number of top-dimensional simplices used to build the triangulations. For 2-manifolds, 3-manifolds and 4-manifolds, this specifies the number of triangles, tetrahedra or pentachora respectively.

`-2, --dim2`

- Build a census of 2-manifold triangulations, not 3-manifold triangulations.

  This is incompatible with several options; for other options it simply translates the relevant constraint into two dimensions. See each individual option for details on how it interacts with `--dim2`.

`-4, --dim4`

- Build a census of 4-manifold triangulations, not 3-manifold triangulations.

  This is incompatible with several options; for other options it simply translates the relevant constraint into four dimensions. See each individual option for details on how it interacts with `--dim4`.

`-b, --boundary`

- Only produce triangulations with at least one boundary triangle.

  For 2-manifolds or 4-manifolds, this option ensures at least one boundary edge or boundary tetrahedron respectively.

`-i, --internal`

- Only produce triangulations with all triangles internal (i.e., with no boundary triangles).

  For 2-manifolds or 4-manifolds, this option ensures that all edges or tetrahedra respectively are internal.

`-B, --bdryfaces=``triangles`

- Only produce triangulations with the precise number of boundary triangles specified.

  For 2-manifolds or 4-manifolds, this specifies the number of boundary edges or boundary tetrahedra respectively.

`-o, --orientable`

- Only produce orientable triangulations.

`-n, --nonorientable`

- Only produce non-orientable triangulations.

`-f, --finite`

- Only produce finite triangulations (triangulations with no ideal vertices).

  This option cannot be used with `--dim2`.

`-d, --ideal`

- Only produce triangulations with at least one ideal vertex. There might or might not be internal vertices (whose links are spheres) as well.

  This option cannot be used with `--dim2`.

`-m, --minimal`

- Do not include triangulations that are obviously non-minimal.

  This option uses a series of fast tests that try to eliminate non-minimal triangulations, but that are not always conclusive. If ®ina; cannot quickly tell whether a triangulation is non-minimal, it will place the triangulation in the census regardless.

  This option cannot be used with `--dim4`.

`-M, --minprime`

- Do not include triangulations that are obviously non-minimal, non-prime and/or disc-reducible.

  This can significantly speed up the census and vastly reduce the final number of triangulations produced.

  As above, this option uses a series of fast tests that are not always conclusive. If ®ina; cannot quickly tell whether a triangulation is non-minimal, non-prime or disc-reducible, it will place the triangulation in the census regardless.

  This option cannot be used with `--dim2` or `--dim4`.

`-N, --minprimep2`

- Do not include triangulations that are obviously non-minimal, non-prime, P2-reducible and/or disc-reducible.

  This can significantly speed up the census and vastly reduce the final number of triangulations produced, even more so than `--minprime`.

  As above, this option uses a series of fast tests that are not always conclusive. If ®ina; cannot quickly tell whether a triangulation is non-minimal, non-prime, P2-reducible or disc-reducible, it will place the triangulation in the census regardless.

  This option cannot be used with `--dim2` or `--dim4`.

`-h, --minhyp`

- Do not include triangulations that are obviously not minimal ideal triangulations of cusped finite-volume hyperbolic 3-manifolds.

  This can significantly speed up the census and vastly reduce the final number of triangulations produced.

  As above, this option uses a series of fast tests that are not always conclusive. If ®ina; cannot quickly tell whether a triangulation is a minimal ideal triangulation of a cusped finite-volume hyperbolic 3-manifold, it will place the triangulation in the census regardless.

  This option is designed for use with ideal triangulations only (so, for instance, combining it with `--finite` or `--boundary` will produce an error message). This option also cannot be used with `--dim2` or `--dim4`.

`--allowinvalid`

- Normally, `tricensus` will test each triangulation that is constructed for validity before including it in the final output. If you pass `--allowinvalid` however, then these validity tests will not be performed.

  As a result, the output may include some invalid triangulations. However, it will not include all invalid triangulations of the given size, since some invalid constructions are pruned at earlier levels of the search tree by the census algorithm (as opposed to being detected by the validity test when each full triangulation has been constructed). For example, edges that are identified with themselves in reverse are detected and pruned earlier in this way, and so will never appear in the census output, even with the `--allowinvalid` option.

  The one guarantee that you do get from this option is that the census will include all invalid triangulations that could appear as a subcomplex of some valid triangulation. For example, if a 3-dimensional triangulation is invalid only because it has vertices whose links are spheres with multiple punctures, then it will be included in the output.

  This option cannot be used with finite/ideal options or minimality options.

`-s, --sigs`

- Instead of writing a full ®ina; data file, just output a list of isomorphism signatures.

  The output file will be a plain text file. Each line will be a short string of letters, digits and/or punctuation that uniquely encodes a triangulation up to combinatorial isomorphism. You can import this text file from within ®ina; by selecting &menuimportsigs; from the menu.

  This option is highly recommended for large census enumerations. First, the output file will be considerably smaller. More importantly, the memory footprint of `tricensus` will also be much smaller: triangulations can be written to the output file and forgotten immediately, instead of being kept in memory to construct a final ®ina; data file.

`-S, --canonical`

- A variant of `--sigs` that outputs a list of isomorphism signatures along with matching isomorphisms.

  The output file will be a plain text file. Each line will contain two short strings, separated by a single space. The first string will be the same isomorphism signature that is output by `--sigs`. The second string encodes an isomorphism `F` with the property that, if we reconstruct a triangulation from the isomorphism signature and apply the isomorphism `F`, then the resulting triangulation will have a canonical facet pairing.

  Here canonical has the same meaning as described below under the `--usepairs` option: a facet pairing is in canonical form if it is a minimal representative of its isomorphism class.

  The isomorphisms themselves will be encoded using tight encodings, which (like isomorphisms signatures) are short strings of letters, digits and/or punctuation. Currently you will need to use either &cpp; or &python; to decode these; for example, in dimension 3 you would call `Isomorphism<3>::tightDecoding()`.

  If you do not need these isomorphisms, then you should use the simpler (and slightly faster) option `--sigs` instead.

`-e, --encodings`

- Instead of writing a full ®ina; data file, just output a list of tight encodings.

  The output file will be a plain text file. Each line will be a short string of letters, digits and/or punctuation that uniquely encodes a labelled triangulation as a tight encoding.

  Tight encodings differ from isomorphism signatures (as output by `--sigs`) in the following ways:

  - The main reason for using tight encodings is that they preserve the labelling of simplices and their vertices (unlike isomorphism signatures, which only encode a triangulation up to combinatorial isomorphism).

  - In general, tight encodings use slightly more characters and are slightly faster to compute than isomorphism signatures.

  - Tight encodings are more difficult to work with. They use a wider variety of punctuation symbols (which makes them inappropriate for filenames, and awkward to use as hard-coded strings in source code). Moreover, at present you need to use either &cpp; or &python; to reconstruct triangulations from them; for example, in dimension 3 you would call `Triangulation<3>::tightDecoding()`.

  If you are not sure whether to use isomorphism signatures or tight encodings, it is recommended that you choose isomorphism signatures (`--sigs`).

  Like `--sigs`, this option performs much better in large census enumerations than saving a full ®ina; data file: the output file will be considerably smaller, and the memory footprint of `tricensus` will also be much smaller. See the `--sigs` option for further details.

  You can also use `--encodings` with `--genpairs`, in which case the facet pairings will be written using tight encodings instead of human-readable text representations. Tight encodings of facet pairings cannot be used as input with `--usepairs`, and again you will need to use &cpp; or &python; to reconstruct facet pairings from them.

`-c, --subcontainers`

- For each facet pairing, a new container will be created, and resultant triangulations will be placed into these containers. These containers will be created even if the facet pairing results in no triangulations.

  See `--genpairs` below for further information on facet pairings.

  This option cannot be used with `--sigs`, `--canonical` or `--encodings`.

`-p, --genpairs`

- Only generate facet pairings, not triangulations. A facet pairing stores which facets of top-dimension simplices are glued to which others, but it does not store the precise rotations and/or reflections that are used for each gluing. For 3-manifolds a facet pairing represents a pairing of tetrahedron faces, for 2-manifolds it represents a pairing of triangle edges, and for 4-manifolds it represents a pairing of pentachoron facets.

  The outermost layer of the census code involves pairing off the facets of individual top-dimensional simplices without determining the corresponding gluing permutations. For each such facet pairing that is produced, ®ina; will try many different sets of gluing permutations and generated the corresponding triangulations.

  Facet pairing generation consumes a very small fraction of the total census runtime, and effectively divides the census into multiple pieces. This option allows you to quickly generate a complete list of possible facet pairings, so that you can feed subsets of this list to different machines to work on simultaneously.

  The list of all facet pairings will be written to the given output file in a plain text format (though you may omit the output file from the command line, in which case the facet pairings will be written to standard output). By default, the output format will be a space-separated numerical format, suitable for use with `--usepairs` (see below). However, if you pass `--encodings` then the output format will use tight encodings (which are shorter, contain no spaces, and are much harder for humans to read). See `--encodings` for further details on tight encodings.

  If you are coordinating your sub-censuses manually, you can use the option `--usepairs` to generate triangulations from a subset of these facet pairings. In this case, the facet pairings will need to be presented using the default space-separated numerical format (not tight encodings).

  Options for orientability, finiteness or minimality cannot be used with `--genpairs`; instead you should use them later with `--usepairs`.

  This option does not come with progress reporting, though typically it runs fast enough that this does not matter. You can always track the state of progress by counting lines in the output file.

`-P, --usepairs`

- Use only the given subset of facet pairings to build the triangulations.

  Each facet pairing that is processed must be in canonical form, i.e., must be a minimal representative of its isomorphism class. All facet pairings generated using `--genpairs` are guaranteed to satisfy this condition.

  Facet pairings should be supplied on standard input, one per line. They should be presented using the space-separated numerical format produced by the option `--genpairs`.

  This option effectively lets you run a subset of a larger census. See `--genpairs` for further details on how to split a census into subsets that can run simultaneously on different machines.

  Options for the number of top-dimensional simplices (i.e., `--tetrahedra`) or boundary facets (i.e., `--boundary` or `--bdryfaces`) cannot be used with `--usepairs`. Instead you should pass these options earlier along with `--genpairs` when you split the original census into pieces.

`--threads=``num_threads`

- Run the census in parallel using the given number of threads. This parallelisation is typically very effective (particularly for larger censuses), in that the speed-up factor is usually close to the theoretical maximum `num_threads`.

  The way the parallelisation currently works is as follows. For each individual facet pairing, the corresponding search tree is broken into a many smaller subtrees (i.e., subsearches), each of which can be processed independently by different threads.

  This has two consequences:

  - The `--threads` option cannot be used with `--genpairs`, since the facet pairings are still enumerated in serial.

  - The output that writes each facet pairing to the console will appear deceptively fast. This is because each facet pairing will be written as soon as it is constructed by the main thread, and its many subsearches will be placed in a queue for other threads to process while the main thread moves on to the next facet pairing. Once all of the pairings have been output, you may still face a long wait while the threads together work their way through the queue of subsearches that has accumulated.

&versionhelpdesc;

### Examples

The following command forms a census of all 3-tetrahedron closed non-orientable 3-manifold triangulations, and puts the results in the file `results.rga`. To ensure that triangulations are closed we use the options `-i` (no boundary triangles) and `-f` (no ideal vertices).

        example$ tricensus -t 3 -nif results.rga
        Starting census generation...
        0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 2:3 2:2
        0:1 0:0 1:0 2:0 | 0:2 1:2 1:1 2:1 | 0:3 1:3 2:3 2:2
        0:1 0:0 1:0 2:0 | 0:2 2:1 2:2 2:3 | 0:3 1:1 1:2 1:3
        1:0 1:1 2:0 2:1 | 0:0 0:1 2:2 2:3 | 0:2 0:3 1:2 1:3
        Finished.
        Total triangulations: 5
        example$

The following command forms a census of 4-tetrahedron closed orientable 3-manifold triangulations, where the census creation is optimised for prime minimal triangulations. Although all prime minimal triangulations will be included, there may be some non-prime or non-minimal triangulations in the census also.

        example$ tricensus -t 4 -oifM results.rga
        Starting census generation...
        0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
        0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 3:0 | 1:2 2:2 2:1 3:1 | 1:3 ...
        ...
        1:0 1:1 2:0 3:0 | 0:0 0:1 2:1 3:1 | 0:2 1:2 3:2 3:3 | 0:3 ...
        Finished.
        Total triangulations: 17
        example$

The following command generates all face pairings for a 5-tetrahedron census of 3-manifold triangulation in which all triangulations have precisely two boundary triangles. The face pairings will be written to `pairings.txt`, whereupon they can be broken up and distributed for processing at a later date.

        example$ tricensus --genpairs -t 5 -B 2 pairings.txt
        Total face pairings: 118
        example$

The face pairings generated in the previous example can then be fleshed out into a full census of all 3-manifold triangulations with five tetrahedra, precisely two boundary triangles and no ideal vertices as follows. The number of tetrahedra and boundary triangles were already specified in the previous command, and cannot be supplied here. The face pairings will be read from `pairings.txt`, and the final census will be written to `results.rga`.

        example$ tricensus --usepairs -f results.rga < pairings.txt
        Trying face pairings...
        0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
        0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
        ...
        ... (running through all 118 face pairings)
        ...
        1:0 2:0 3:0 4:0 | 0:0 2:1 3:1 4:1 | 0:1 1:1 3:2 4:2 | 0:2 ...
        Total triangulations: 5817
        example$

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/tricensus`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\tricensus.exe`.

### See Also

censuslookup, sigcensus, regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

trisetcmp

1

trisetcmp

Compare triangulations between two ®ina; data files

        trisetcmp

         -m
         -n

        -s
        file1
        file2

        trisetcmp
        &versionhelpopts;

### Description

Compares all triangulations in the first file against all triangulations in the second file, looking for pairs of triangulations that are combinatorially isomorphic.

The two given files must be ®ina; data files. A full list of matches (or a full list of non-matches if `-n` is passed) is written to standard output. A match occurs when some triangulation from `file1` is combinatorially isomorphic to some triangulation from `file2` (i.e., identical up to a relabelling of tetrahedra and their vertices).

This utility can also do subcomplex testing instead of full isomorphism testing. See the option `-s` for details.

This utility compares both 3-manifold and 4-manifold triangulations (but no other dimensions at present). However, it will only compare triangulations of the same dimension—it will not test whether some 3-manifold triangulation appears as a subcomplex of some other 4-manifold triangulation.

### Options

`-m` (default)

- Output matches only. All isomorphic matches between triangulations in `file1` and triangulations in `file2` will be listed.

`-n`

- Output non-matches only. All triangulations from `file1` with no isomorphic match in `file2` will be listed, and vice versa.

  If `-s` is passed then non-matches are tested in one direction only, not both; see below for details.

`-s`

- Instead of testing triangulations for isomorphism, test whether one triangulation is isomorphic to a subcomplex of the other.

  In the default case of `-m` (output matches only), this program outputs all instances where a triangulation from `file1` is isomorphic to a subcomplex of a triangulation from `file2`.

  In the case of `-n` (output non-matches only), this program outputs all triangulations from `file1` that are not isomorphic to a subcomplex of any triangulation from `file2`.

&versionhelpdesc;
&submani18n;

### &macosx; Users

If you downloaded a drag-and-drop app bundle, this utility is shipped inside it. If you dragged ®ina; to the main Applications folder, you can run it as `/Applications/Regina.app/Contents/MacOS/trisetcmp`.

### &windows; Users

The command-line utilities are installed beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. You can start this utility by running `c:\Program Files\Regina\Regina ®version;\bin\trisetcmp.exe`.

### See Also

censuslookup, regina-gui.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

## Command Line: Compiling and Linking

The main applications `regina-gui` and `regina-python` are documented in a previous chapter. This chapter documents some specialised command-line tools that can help with compiling and linking your own programs against ®ina;.

regina-engine-config

1

regina-engine-config

Get compiler and linker flags to build software against ®ina;

        regina-engine-config
        --prefix
        --version
        --cflags
        --libs

### Description

This utility tells you which compiler and linker flags should be used to build the mathematical engine of ®ina; into your own programs. ®ina;'s mathematical engine is typically installed in the library `libregina-engine.so`.

This utility is only available in some settings:

- If you are using &linux; and you have ®ina; installed in a system location (e.g., beneath `/usr/` or `/usr/local/`), then `regina-engine-config` should be included with your installation, and it should output compiler/linker flags relative to this system installation.

- If you are building ®ina; yourself from the source tree (on any platform), then you can run `regina-engine-config` from the source tree, and it should output compiler/linker flags relative to the same source tree. In particular, you do not need to install ®ina; for these compiler/linker flags to work.

- If you are using pre-built packages for ®ina; on &macosx; or &windows;, then `regina-engine-config` will not be included in your installation.

Instead of using `regina-engine-config` as part of the compilation process, you may find it easier to create a Makefile using `regina-helper` and then just use `make` instead.

### Options

`--prefix`

- Prints the installation prefix where ®ina; has been installed.

`--version`

- Prints the currently installed version of ®ina;. This will include any `BUILD_INFO` string that was set when ®ina; was built.

`--cflags`

- Print the compiler flags that are required to compile a program that uses the ®ina; calculation engine.

`--libs`

- Print the linker flags that are required to link a program against the ®ina; calculation engine.

### Example

        example$ regina-engine-config --cflags
        -std=c++20
        -I/usr/include/regina-normal -I/usr/include -I/usr/include/libxml2
        example$

### See Also

regina-helper.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;

This script was long ago based on `gtk-config`, though very little of that remains nowadays. The original `gtk-config` was Copyright © 1998 Owen Taylor and used an MIT-style license; see the `regina-engine-config` script for full details.

regina-helper

1

regina-helper

Helper utility for working with a ®ina; installation

        regina-helper
        action
        args

        regina-helper
        action
        --help

### Description

This utility understands the layout of your ®ina; installation, and it can help you with a variety of tasks that require this knowledge. For example, it can create Makefiles and/or sample &cpp; code for you, or help you run ®ina;'s test suite.

The first argument to `regina-helper` should be an action, indicating what you want the utility to do. The available actions are described in detail below. To learn more about what an action does, you can run `regina-helper `action` --help`.

This utility is available in most but not all settings:

- If you are using &linux; and you have ®ina; installed in a system location (e.g., beneath `/usr/` or `/usr/local/`), then `regina-helper` should be included with your installation, and any output it produces should be relative to this system installation.

- If you are using &macosx; and you are running ®ina; from an app bundle (which might be under `/Applications/` or might be somewhere else), then you can run `regina-helper` from within the app bundle (`.../Regina.app/Contents/MacOS/regina-helper`), and any output it produces should be relative to this app bundle.

- If you are building ®ina; yourself from the source tree (on any platform), then you can run `regina-helper` from the source tree, and any output it produces should be relative to this same source tree. In particular, it will not assume that you have actually installed ®ina;.

- If you are using pre-built packages for ®ina; on &windows;, then `regina-helper` will not be included in your installation.

### Actions

The first argument to `regina-helper` should be one of the following actions:

`installtype`

- Writes a single token to standard output identifying the type of ®ina; installation.

          example$ regina-helper installtype
          XDG
          example$

  The output will be one of the following:

  XDG

  Indicates that you are running ®ina; from an installation in a fixed location that follows the freedesktop.org layout. This is seen with ®ina;'s &linux; packages, as well as local CMake builds with no special arguments.

  HPC

  Indicates that you are running ®ina; from a slimmed-down installation (e.g., no &gui; or &html; docs), which is installed in a fixed but possibly non-standard location, suitable for builds on high-performance computing systems. This is typically seen with local CMake builds where `REGINA_INSTALL_TYPE` was explicitly set to `HPC`.

  Bundle

  Indicates that you are running ®ina; from within a &macosx; app bundle.

  Windows

  Indicates that you are running ®ina; from within ®ina;'s &windows; app. It is unlikely that you will see this of course, since `regina-helper` is not shipped with &windows; installations.

  Source

  Indicates that you are running ®ina; directly from the source tree (i.e., a local build that has not necessarily been installed).

  The `installtype` action takes no additional arguments.

`makefile`

- Creates a Makefile in the current directory, suitable for compiling &cpp; programs against ®ina;. In particular, once you have your Makefile in place, you can (for example) compile a &cpp; program `foo.cc` just by running `make foo`.

  The main reason for using this Makefile is that it includes compiler and linker flags for accessing ®ina;'s &cpp; calculation engine. (In particular, using this Makefile is a simpler alternative to extracting compiler and linker flags from `regina-engine-config`.)

  The `makefile` action accepts the optional arguments `--force` and/or `--rpath`; these are described below.

`cc`, `cpp`

- Creates a Makefile in the current directory that is suitable for compiling &cpp; programs against ®ina;, as well as a sample &cpp; program that can be used as a starting point for your own code.

          example$ regina-helper cc
          Writing sample.cc...
          Preparing Makefile...
          example$ ls
          Makefile  sample.cc
          example$

  See the `makefile` action above for further discussion of how you can use this Makefile.

  The &cpp; source file will be called either `sample.cc` or `sample.cpp`, depending on whether you gave `cc` or `cpp` as the action argument to `regina-helper`.

  The `cc` / `cpp` action accepts the optional arguments `--force` and/or `--rpath`; these are described below.

`test`

- Runs ®ina;'s detailed &cpp; calculation engine test suite.

  ®ina; has a large and thorough test suite, designed to guard against system incompatibilities and/or unforseen bugs. This test suite includes several components that target the &cpp; calculation engine, the &python; bindings, and the command-line utilities. The bulk of the tests are for the &cpp; calculation engine, and those are the tests that will be run here.

          example$ regina-helper test
          Running C++ test suite from the installation beneath /usr/local/.

          [==========] Running 522 tests from 53 test suites.
          [----------] Global test environment set-up.
          [----------] 2 tests from AbelianGroupTest
          [ RUN      ] AbelianGroupTest.incrementalBuild
          [       OK ] AbelianGroupTest.incrementalBuild (0 ms)
          [ RUN      ] AbelianGroupTest.tightEncoding
          [       OK ] AbelianGroupTest.tightEncoding (0 ms)
          [----------] 2 tests from AbelianGroupTest (1 ms total)

          [----------] 6 tests from CoversTest
          [ RUN      ] CoversTest.trivial
          [       OK ] CoversTest.trivial (2 ms)
          ...

  The &cpp; test suite uses the Google Test framework, which supports many different arguments to customise your test suite run. Any additional arguments that you supply with the `test` action will be passed directly through to Google Test. You can run `regina-helper test --help` to see what all of these possible arguments are.

`help`

- Outputs usage information for the `regina-helper` utility.

  This action takes no additional arguments.

### Options

`--force`

- Overwrites any existing files (such as `Makefile`, or `sample.cc`). By default, `regina-helper` will not overwrite a file that already exists.

  This option is used with the `makefile` and `cc` / `cpp` actions.

`--rpath`

- Always uses an rpath option in the linker flags within the Makefile that is created. This is useful for when your ®ina; installation is not on the standard library path.

  If your program compiles and links correctly but crashes when you run it because it cannot find the library `libregina-engine.so`, then the `--rpath` option might solve your problem. (You will of course need to rebuild your program after updating the Makefile.)

  By default, an rpath option will only be used if you are running ®ina; directly out of the source tree.

  This option is used with the `makefile` and `cc` / `cpp` actions.

`--help`

- Outputs detailed usage information for a particular `regina-helper` action.

          example$ regina-helper test --help
          Usage: /usr/local/bin/regina-helper test [testsuite_args...]

          Runs Regina's C++ test suite.
          ...

### See Also

regina-engine-config.

### Author

This utility was written by Benjamin Burton bab@maths.uq.edu.au. &manpageack;