Ubuntu Manpage: retriangulate - Exhaustively search through triangulations or knot diagrams using local moves

Provided by: regina-normal_7.3.1-1_amd64

NAME

       retriangulate - Exhaustively search through triangulations or knot diagrams using local moves

SYNOPSIS

       retriangulate  [ -h, --height=height ] [ -t, --threads=threads ] [ -3, --dim3 | -4, --dim4 | -k, --knot ]
       [ -a, --anysig ] [ -- ] signature

       retriangulate { -v, --version | -?, --help }

DESCRIPTION

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

Specifically, suppose the input triangulation or knot diagram contains n tetrahedra/pentachora/crossings
(for a 3-manifold, 4-manifold or knot respectively). Then this utility will exhaustively modify the
triangulation or knot 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).

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 or knot diagrams, it will use all types of Pachner moves or
Reidemeister moves respectively.

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 knot 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 at all.

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

To view the isomorphism signature of a triangulation: in Regina'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 signature: in Regina's graphical user interface this is available
through the Codes tab in the knot/link viewer, and in Python you can call k.knotSig() for a knot k.

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.

Tip: Very large triangulations or knots 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 knot respectively) that we allow during intermediate stages of retriangulation.
That is, if the input triangulation or knot diagram has n tetrahedra/pentachora/crossings, then
this utility will exhaustively search through all triangulations or knot 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 knot diagrams, and it
defaults to 2 when working with 4-manifolds.

Warning: 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 knot.

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 signature. The local moves used will be the
Reidemeister moves.

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

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

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

Note: Currently Regina only uses alternate signature types with triangulations. For knot
signatures, it still uses classic signatures, though again this is subject to change in future
version of Regina.

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

-v, --version
Show which version of Regina is being used, and exit immediately.

-?, --help
Display brief usage information, and exit immediately.

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$

MACOS USERS

       If you downloaded a drag-and-drop app bundle, this utility is shipped inside it.  If you  dragged  Regina
       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 7.3.1\bin\retriangulate.exe.

AUTHOR

       This utility was written by Benjamin Burton <bab@maths.uq.edu.au>.  Many people have been involved in the
       development of Regina; see the users' handbook for a full list of credits.

                                                  14 March 2023                                 RETRIANGULATE(1)