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

       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.

                                                17 December 2021                                RETRIANGULATE(1)

       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  isomorphismsignatures
       and  knotsignatures  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 SimplificationpathsinthePachnergraphsofclosedorientable3-manifoldtriangulations, 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...

       The following 3-manifold triangulation is non-minimal, but it requires a bit of work to see this:

           example$ retriangulate-h2hLLAAkbdceefggdonxdjxn
           hLLAAkbdceefggdonxdjxn
           hLALPkbcbefgfghxwnxark
           Found 2 triangulation(s).
           example$ retriangulate-h3hLLAAkbdceefggdonxdjxn
           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$ retriangulategLLPQcdcefffqsjpunw
           gLLPQcdcefffqsjpunw
           fLAMcbbcdeedhwhxn
           Triangulation is non-minimal!
           Smaller triangulation: fLAMcbbcdeedhwhxn
           example$

       A little more probing shows this to be the cusped hyperbolic manifold m112:

           example$ censuslookupfLAMcbbcdeedhwhxn
           fLAMcbbcdeedhwhxn: 1 hit
               m112 : #2 -- Cusped hyperbolic census (orientable)

           example$

       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.

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

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

       regina-gui.

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

       The  command-line  utilities  are  installed  beneath  the ProgramFiles directory; on some machines this
       directory   is   called   ProgramFiles(x86).    You   can   start   this   utility    by    running
       c:\Program Files\Regina\Regina 7.0\bin\retriangulate.exe.