.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\"
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng .
.TH "RETRIANGULATE" "1" "14 March 2023" "" "The Regina Handbook"
.SH NAME
retriangulate \- Exhaustively search through triangulations or knot diagrams using local moves
.SH SYNOPSIS
\fBretriangulate\fR [ \fB-h, --height=\fIheight\fB\fR ] [ \fB-t, --threads=\fIthreads\fB\fR ] [ \fB-3, --dim3\fR | \fB-4, --dim4\fR | \fB-k, --knot\fR ] [ \fB-a, --anysig\fR ] [ \fB--\fR ] \fB\fIsignature\fB\fR
\fBretriangulate\fR { \fB-v, --version\fR | \fB-?, --help\fR }
.SH "DESCRIPTION"
.PP
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.
.PP
Specifically, suppose the input triangulation or knot diagram contains
\fIn\fR 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
\fIn\fR\~+\~\fIheight\fR
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).
.PP
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.
.PP
The input is assumed to represent a 3-manifold
triangulation unless one of the options \fB--dim4\fR or
\fB--knot\fR is passed.
.PP
The program will output each triangulation or knot diagram that it finds
of the same size \fIn\fR (including the original input
triangulation/diagram). If it ever finds a
\fBsmaller\fR 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 \fIn\fR
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.
.PP
All triangulations or knot diagrams, both input and output, are described
using \fIisomorphism signatures\fR and
\fIknot signatures\fR 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).
.PP
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 \fBt.isoSig()\fR
for a triangulation \fBt\fR\&.
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 \fBk.knotSig()\fR
for a knot \fBk\fR\&.
.PP
For a full and precise specification of isomorphism signatures for
3-manifolds, see
\fBSimplification paths in the Pachner graphs of closed
orientable 3-manifold triangulations\fR, Burton, 2011,
arXiv:1110.6080.
.sp
.RS
.B "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 \fB--\fR immediately before it: this indicates
that all command-line options have finished, and whatever comes next should
be treated as the input signature.
.nf
example$ \fBretriangulate -h1 -- -b-LLvALwvM...\fR
.fi
.RE
.SH "OPTIONS"
.TP
\fB-h, --height=\fIheight\fB\fR
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 \fIn\fR 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
\fIn\fR\~+\~\fIheight\fR
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 \fBsmaller\fR 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.
.sp
.RS
.B "Warning:"
In general, the running time can grow
\fBsuperexponentially\fR with
\fIheight\fR\&. 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.
.RE
.TP
\fB-t, --threads=\fIthreads\fB\fR
Specifies the degree to which this utility uses parallel processing.
Specifically, this program will use
\fIthreads\fR 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 \fIk\fR threads should
approximately divide the running time by \fIk\fR\&.
If not specified, this option defaults to 1
(i.e., single-threaded processing, with no parallelism).
.TP
\fB-3, --dim3 (default)\fR
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 \fB--dim3\fR, \fB--dim4\fR or
\fB--knot\fR is passed.
.TP
\fB-4, --dim4\fR
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.
.TP
\fB-k, --knot\fR
Indicates that the given signature is a knot signature.
The local moves used will be the Reidemeister moves.
.TP
\fB-a, --anysig\fR
Indicates that the output is not required to be
classic isomorphism signatures.
Regina\~7.0 introduced alternate \fBtypes\fR
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
\fBclassic signatures\fR; 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 \fB--anysig\fR, 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
\fBnot\fR 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).
.sp
.RS
.B "Warning:"
The internal signature type is subject to change in future versions
of Regina. That is, if you do use \fB--anysig\fR,
then you may get different output depending upon which version of
Regina you are using.
.RE
.sp
.RS
.B "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.
.RE
.TP
\fB--\fR
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.
.TP
\fB-v, --version\fR
Show which version of Regina is being used, and exit
immediately.
.TP
\fB-?, --help\fR
Display brief usage information, and exit immediately.
.SH "EXAMPLES"
.PP
The following 3-manifold triangulation is non-minimal, but it requires a bit
of work to see this:
.nf
example$ \fBretriangulate -h2 hLLAAkbdceefggdonxdjxn\fR
hLLAAkbdceefggdonxdjxn
hLALPkbcbefgfghxwnxark
Found 2 triangulation(s).
example$ \fBretriangulate -h3 hLLAAkbdceefggdonxdjxn\fR
hLLAAkbdceefggdonxdjxn
hLALPkbcbefgfghxwnxark
hLLMMkbcdfefgglcghtchj
gLLPQcdcefffqsjpunw
Triangulation is non-minimal!
Smaller triangulation: gLLPQcdcefffqsjpunw
example$
.fi
.PP
Although the program stopped as soon as it found a smaller
triangulation, this can be simplified even further:
.nf
example$ \fBretriangulate gLLPQcdcefffqsjpunw\fR
gLLPQcdcefffqsjpunw
fLAMcbbcdeedhwhxn
Triangulation is non-minimal!
Smaller triangulation: fLAMcbbcdeedhwhxn
example$
.fi
.PP
A little more probing shows this to be the cusped hyperbolic
manifold m112:
.nf
example$ \fBcensuslookup fLAMcbbcdeedhwhxn\fR
fLAMcbbcdeedhwhxn: 1 hit
m112 : #2 -- Cusped hyperbolic census (orientable)
example$
.fi
.SH "MACOS USERS"
.PP
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\&.
.SH "WINDOWS USERS"
.PP
The command-line utilities are installed beneath the
\fIProgram\~Files\fR directory; on some
machines this directory is called
\fIProgram\~Files\~(x86)\fR\&.
You can start this utility by running
c:\\Program\~Files\\Regina\\Regina\~7.3\\bin\\retriangulate.exe\&.
.SH "SEE ALSO"
.PP
regina-gui\&.
.SH "AUTHOR"
.PP
This utility was written by Benjamin Burton
\&.
Many people have been involved in the development
of Regina; see the users' handbook for a full list of credits.