.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "RETRIANGULATE" "1" "11 February 2021" "" "The Regina Handbook"

.SH NAME
retriangulate \- Exhaustively retriangulate a given manifold
.SH SYNOPSIS

\fBretriangulate\fR [ \fB-h, --height=\fIheight\fB\fR ] [ \fB-t, --threads=\fIthreads\fB\fR ] [ \fB-4, --dim4\fR ] \fB\fIisosig\fB\fR


\fBretriangulate\fR \fB--help\fR

.SH "DESCRIPTION"
.PP
Given a 3-manifold or 4-manifold triangulation,
this utility uses Pachner moves to exhaustively search
for other triangulations of the same manifold that are the
same size or smaller.
.PP
Specifically, suppose the input triangulation contains
\fIn\fR tetrahedra (for a 3-manifold)
or pentachora (for a 4-manifold).  Then this utility will
exhaustively retriangulate the manifold using repeated Pachner moves,
without ever exceeding
\fIn\fR\~+\~\fIheight\fR
tetrahedra/pentachora in total.
Moreover, all such retriangulations are guaranteed to be found, each
once and only once.
.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, all types of Pachner moves are used
(1-5, 2-4, 3-3, 4-2, and 5-1).
.PP
The program will output each triangulation that it finds of the same
size \fIn\fR (including the original input
triangulation).  If it ever finds a
\fBsmaller\fR triangulation (thereby proving the
original to be non-minimal), it will output that smaller
triangulation and then stop immediately.  Otherwise it will continue
outputting triangulations of size \fIn\fR until
no more can be found.  Although the program also finds larger
triangulations as part of its exhaustive search using Pachner moves,
these larger triangulations (of which there are typically many) will
not be output at all.
.PP
All triangulations, both input and output, are described using
\fIisomorphism signatures\fR\&.  These are short text
strings that identify a triangulation uniquely up to combinatorial
isomorphism (i.e., up to relabellings of the tetrahedra/pentachora
and their vertices).
The input triangulation will be interpreted as the isomorphism
signature of a 3-manifold unless you pass the option
\fB--dim4\fR (in which case it will be treated as a
4-manifold instead).
.PP
From Regina's 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 \fBx\fR
by calling \fBx.isoSig()\fR\&.
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.
.SH "OPTIONS"
.TP
\fB-h, --height=\fIheight\fB\fR
Specifies the number of additional tetrahedra (for a 3-manifold)
or pentachora (for a 4-manifold) that we allow during intermediate
stages of retriangulation.  That is, if the input triangulation
has \fIn\fR tetrahedra (or pentachora), then
this utility will exhaustively search through all triangulations
that it can reach via Pachner moves that do not exceed
\fIn\fR\~+\~\fIheight\fR
tetrahedra (or pentachora) in total.

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

The given height must be positive, and for 4-manifolds it must
also be even.
If not specified, this option defaults to 1 for 3-manifolds
(if \fB--dim4\fR is not passed), or 2 for 4-manifolds
(if \fB--dim4\fR is passed).
.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 of the
input manifold.

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-4, --dim4\fR
Indicates that the given isomorphism signature describes a
4-manifold triangulation.  If this argument is not given, then by
default the argument is assumed to describe a 3-manifold triangulation.
.SH "EXAMPLES"
.PP
The 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\\~X 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\~6.0.1\\bin\\retriangulate.exe\&.
.SH "SEE ALSO"
.PP
regina-gui\&.
.SH "AUTHOR"
.PP
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.