Provided by: regina-normal_7.3-2_amd64 bug

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\bin\retriangulate.exe.

SEE ALSO

       regina-gui.

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)