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

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

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

                                        11 September 2022                        RETRIANGULATE(1)