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

NAME

       tricensus - Form a census of triangulations

SYNOPSIS

       tricensus  [  -t, --tetrahedra=tetrahedra ] [ -2, --dim2 | -4, --dim4 ] [ -b, --boundary |
       -i, --internal | -B, --bdryfaces=triangles ] [ -o, --orientable | -n, --nonorientable ]  [
       -f,  --finite  |  -d,  --ideal ] [ -m, --minimal | -M, --minprime | -N, --minprimep2 | -h,
       --minhyp ] [ --allowinvalid ] [ -s, --sigs | -S,  --canonical  |  -e,  --encodings  |  -c,
       --subcontainers  ]  [  -p, --genpairs | -P, --usepairs ] [ --threads=num_threads ] output-
       file

       tricensus { -v, --version | -?, --help }

DESCRIPTION

       Forms a census of all 2-, 3-  or  4-manifold  triangulations  that  satisfy  some  set  of
       conditions.

       These  conditions  are specified using various command-line arguments.  The only condition
       that you must provide is the number of top-dimensional  simplices  (e.g.,  the  number  of
       tetrahedra for 3-manifolds), but there are many other options available.

       The default behaviour is to enumerate 3-manifold triangulations.  If you wish to enumerate
       2-manifold  or  4-manifold  triangulations  instead,  you  must  pass  --dim2  or   --dim4
       respectively.

       Each triangulation will be output precisely once up to combinatorial isomorphism.  Invalid
       triangulations (for 3-manifolds,  this  means  triangulations  with  edges  identified  to
       themselves  in  reverse, or vertices whose links have boundary but are not discs) will not
       be output at all.

       As the census progresses, the state of progress  will  be  written  (slowly)  to  standard
       output.   Once  the  census is complete, the full census will be saved to the given output
       file.

       You can use the options --genpairs and --usepairs to split a census into smaller pieces.

              Caution:

              A census with even  a  small  number  of  top-dimensional  simplices  can  take  an
              incredibly  long  time  to  run,  and can chew up massive amounts of memory.  It is
              recommended that you try very small  censuses  to  begin  with  (such  as  3  or  4
              simplices), and work upwards to establish the limits of your machine.

              For  very  large  census runs, it is highly recommended that you use the either the
              --sigs  or  --encodings  option,  which  will  keep  the  output  file  small   and
              significantly reduce the memory footprint.

OPTIONS

       -t, --tetrahedra=tetrahedra
              Specifies the number of top-dimensional simplices used to build the triangulations.
              For  2-manifolds,  3-manifolds  and  4-manifolds,  this  specifies  the  number  of
              triangles, tetrahedra or pentachora respectively.

       -2, --dim2
              Build a census of 2-manifold triangulations, not 3-manifold triangulations.

              This  is  incompatible with several options; for other options it simply translates
              the relevant constraint into  two  dimensions.   See  each  individual  option  for
              details on how it interacts with --dim2.

              This option cannot be used with --dim4.

       -4, --dim4
              Build a census of 4-manifold triangulations, not 3-manifold triangulations.

              This  is  incompatible with several options; for other options it simply translates
              the relevant constraint into four  dimensions.   See  each  individual  option  for
              details on how it interacts with --dim4.

              This option cannot be used with --dim2.

       -b, --boundary
              Only produce triangulations with at least one boundary triangle.

              For  2-manifolds  or 4-manifolds, this option ensures at least one boundary edge or
              boundary tetrahedron respectively.

       -i, --internal
              Only produce triangulations with all triangles internal  (i.e.,  with  no  boundary
              triangles).

              For  2-manifolds  or  4-manifolds, this option ensures that all edges or tetrahedra
              respectively are internal.

       -B, --bdryfaces=triangles
              Only  produce  triangulations  with  the  precise  number  of  boundary   triangles
              specified.

              For  2-manifolds  or  4-manifolds,  this  specifies the number of boundary edges or
              boundary tetrahedra respectively.

       -o, --orientable
              Only produce orientable triangulations.

       -n, --nonorientable
              Only produce non-orientable triangulations.

       -f, --finite
              Only produce finite triangulations (triangulations with no ideal vertices).

              This option cannot be used with --dim2.

       -d, --ideal
              Only produce triangulations with at least one ideal vertex.  There might  or  might
              not be internal vertices (whose links are spheres) as well.

              This option cannot be used with --dim2.

       -m, --minimal
              Do not include triangulations that are obviously non-minimal.

              This  option  uses  a  series  of  fast  tests  that  try  to eliminate non-minimal
              triangulations, but that are not always conclusive.  If Regina cannot quickly  tell
              whether  a  triangulation  is  non-minimal,  it will place the triangulation in the
              census regardless.

              This option cannot be used with --dim4.

       -M, --minprime
              Do not include triangulations that  are  obviously  non-minimal,  non-prime  and/or
              disc-reducible.

              This  can  significantly  speed up the census and vastly reduce the final number of
              triangulations produced.

              As above, this option uses a series of fast tests that are not  always  conclusive.
              If  Regina cannot quickly tell whether a triangulation is non-minimal, non-prime or
              disc-reducible, it will place the triangulation in the census regardless.

              This option cannot be used with --dim2 or --dim4.

       -N, --minprimep2
              Do  not  include  triangulations  that  are   obviously   non-minimal,   non-prime,
              P2-reducible and/or disc-reducible.

              This  can  significantly  speed up the census and vastly reduce the final number of
              triangulations produced, even more so than --minprime.

              As above, this option uses a series of fast tests that are not  always  conclusive.
              If  Regina  cannot  quickly tell whether a triangulation is non-minimal, non-prime,
              P2-reducible or disc-reducible, it will  place  the  triangulation  in  the  census
              regardless.

              This option cannot be used with --dim2 or --dim4.

       -h, --minhyp
              Do  not  include triangulations that are obviously not minimal ideal triangulations
              of cusped finite-volume hyperbolic 3-manifolds.

              This can significantly speed up the census and vastly reduce the  final  number  of
              triangulations produced.

              As  above,  this option uses a series of fast tests that are not always conclusive.
              If  Regina  cannot  quickly  tell  whether  a  triangulation  is  a  minimal  ideal
              triangulation  of  a  cusped finite-volume hyperbolic 3-manifold, it will place the
              triangulation in the census regardless.

              This option is designed for use with ideal triangulations only (so,  for  instance,
              combining  it  with  --finite  or  --boundary will produce an error message).  This
              option also cannot be used with --dim2 or --dim4.

       --allowinvalid
              Normally, tricensus will test each triangulation that is constructed  for  validity
              before  including it in the final output.  If you pass --allowinvalid however, then
              these validity tests will not be performed.

              As a result, the output may include some invalid triangulations.  However, it  will
              not  include  all  invalid  triangulations  of  the  given size, since some invalid
              constructions are pruned at earlier  levels  of  the  search  tree  by  the  census
              algorithm  (as  opposed  to  being  detected  by  the  validity test when each full
              triangulation has been constructed).  For example, edges that are  identified  with
              themselves  in  reverse  are  detected  and pruned earlier in this way, and so will
              never appear in the census output, even with the --allowinvalid option.

              The one guarantee that you do get from this option is that the census will  include
              all  invalid  triangulations  that  could  appear  as  a  subcomplex  of some valid
              triangulation.  For example, if  a  3-dimensional  triangulation  is  invalid  only
              because  it  has  vertices whose links are spheres with multiple punctures, then it
              will be included in the output.

              This option cannot be used with finite/ideal options or minimality options.

       -s, --sigs
              Instead of writing a full Regina data file,  just  output  a  list  of  isomorphism
              signatures.

              The  output  file  will  be a plain text file.  Each line will be a short string of
              letters, digits and/or punctuation that uniquely  encodes  a  triangulation  up  to
              combinatorial  isomorphism.   You  can  import this text file from within Regina by
              selecting File->Import->Isomorphism Signature List from the menu.

              This option is highly recommended for large census enumerations.  First, the output
              file  will  be  considerably  smaller.   More  importantly, the memory footprint of
              tricensus will also be much smaller: triangulations can be written  to  the  output
              file  and  forgotten  immediately,  instead  of being kept in memory to construct a
              final Regina data file.

       -S, --canonical
              A variant of --sigs that outputs  a  list  of  isomorphism  signatures  along  with
              matching isomorphisms.

              The  output  file  will  be  a  plain  text file.  Each line will contain two short
              strings, separated  by  a  single  space.   The  first  string  will  be  the  same
              isomorphism  signature  that  is  output  by  --sigs.  The second string encodes an
              isomorphism F with the property that, if we reconstruct a  triangulation  from  the
              isomorphism signature and apply the isomorphism F, then the resulting triangulation
              will have a canonical facet pairing.

              Here canonical has the same meaning as described below under the --usepairs option:
              a  facet  pairing  is  in  canonical  form if it is a minimal representative of its
              isomorphism class.

              The isomorphisms themselves will be encoded  using  tight  encodings,  which  (like
              isomorphisms  signatures)  are short strings of letters, digits and/or punctuation.
              Currently you will need to use either C++ or Python to decode these;  for  example,
              in dimension 3 you would call Isomorphism<3>::tightDecoding().

              If  you  do  not  need  these  isomorphisms,  then  you should use the simpler (and
              slightly faster) option --sigs instead.

       -e, --encodings
              Instead of writing a full Regina data file, just output a list of tight encodings.

              The output file will be a plain text file.  Each line will be  a  short  string  of
              letters,  digits  and/or punctuation that uniquely encodes a labelled triangulation
              as a tight encoding.

              Tight encodings differ from isomorphism signatures (as output  by  --sigs)  in  the
              following ways:

              • The  main reason for using tight encodings is that they preserve the labelling of
                simplices and their vertices (unlike isomorphism signatures, which only encode  a
                triangulation up to combinatorial isomorphism).

              • In  general, tight encodings use slightly more characters and are slightly faster
                to compute than isomorphism signatures.

              • Tight encodings are more difficult to work with.  They use  a  wider  variety  of
                punctuation symbols (which makes them inappropriate for filenames, and awkward to
                use as hard-coded strings in source code).  Moreover, at present you need to  use
                either  C++  or  Python  to reconstruct triangulations from them; for example, in
                dimension 3 you would call Triangulation<3>::tightDecoding().
       If you are not sure whether to use  isomorphism  signatures  or  tight  encodings,  it  is
       recommended that you choose isomorphism signatures (--sigs).

       Like  --sigs,  this option performs much better in large census enumerations than saving a
       full Regina data file: the output file  will  be  considerably  smaller,  and  the  memory
       footprint  of  tricensus  will  also  be  much smaller.  See the --sigs option for further
       details.

       You can also use --encodings with --genpairs, in which case the  facet  pairings  will  be
       written  using  tight  encodings  instead  of  human-readable text representations.  Tight
       encodings of facet pairings cannot be used as input with --usepairs, and  again  you  will
       need to use C++ or Python to reconstruct facet pairings from them.

       -c, --subcontainers
              For   each   facet  pairing,  a  new  container  will  be  created,  and  resultant
              triangulations will be placed into these  containers.   These  containers  will  be
              created even if the facet pairing results in no triangulations.

              See --genpairs below for further information on facet pairings.

              This option cannot be used with --sigs, --canonical or --encodings.

       -p, --genpairs
              Only  generate  facet  pairings,  not triangulations.  A facet pairing stores which
              facets of top-dimension simplices are glued to which others, but it does not  store
              the  precise  rotations  and/or  reflections  that  are  used for each gluing.  For
              3-manifolds a  facet  pairing  represents  a  pairing  of  tetrahedron  faces,  for
              2-manifolds  it  represents  a  pairing  of  triangle edges, and for 4-manifolds it
              represents a pairing of pentachoron facets.

              The outermost layer  of  the  census  code  involves  pairing  off  the  facets  of
              individual  top-dimensional  simplices without determining the corresponding gluing
              permutations.  For each such facet pairing that is produced, Regina will  try  many
              different   sets   of   gluing   permutations   and   generated  the  corresponding
              triangulations.

              Facet pairing generation consumes  a  very  small  fraction  of  the  total  census
              runtime,  and  effectively  divides  the  census into multiple pieces.  This option
              allows you to quickly generate a complete list of possible facet pairings, so  that
              you can feed subsets of this list to different machines to work on simultaneously.

              The  list of all facet pairings will be written to the given output file in a plain
              text format (though you may omit the output file from the command  line,  in  which
              case  the  facet  pairings  will  be  written to standard output).  By default, the
              output format will be a space-separated numerical format,  suitable  for  use  with
              --usepairs  (see  below).   However, if you pass --encodings then the output format
              will use tight encodings (which are shorter, contain no spaces, and are much harder
              for humans to read).  See --encodings for further details on tight encodings.

              If  you  are  coordinating  your  sub-censuses  manually,  you  can  use the option
              --usepairs to generate triangulations from a subset of these  facet  pairings.   In
              this  case,  the  facet pairings will need to be presented using the default space-
              separated numerical format (not tight encodings).

              Options for orientability, finiteness or minimality cannot be used with --genpairs;
              instead you should use them later with --usepairs.

              This  option  does  not come with progress reporting, though typically it runs fast
              enough that this does not matter.  You can always track the state  of  progress  by
              counting lines in the output file.

       -P, --usepairs
              Use only the given subset of facet pairings to build the triangulations.

              Each  facet  pairing  that  is processed must be in canonical form, i.e., must be a
              minimal representative of its isomorphism  class.   All  facet  pairings  generated
              using --genpairs are guaranteed to satisfy this condition.

              Facet  pairings should be supplied on standard input, one per line.  They should be
              presented using  the  space-separated  numerical  format  produced  by  the  option
              --genpairs.

              This  option  effectively lets you run a subset of a larger census.  See --genpairs
              for  further  details  on  how  to  split  a  census  into  subsets  that  can  run
              simultaneously on different machines.

              Options  for  the  number  of  top-dimensional  simplices  (i.e.,  --tetrahedra) or
              boundary facets (i.e., --boundary or --bdryfaces) cannot be used  with  --usepairs.
              Instead  you should pass these options earlier along with --genpairs when you split
              the original census into pieces.

       --threads=num_threads
              Run the census in parallel using the given number of threads.  This parallelisation
              is  typically very effective (particularly for larger censuses), in that the speed-
              up factor is usually close to the theoretical maximum num_threads.

              The way the parallelisation currently works is as  follows.   For  each  individual
              facet pairing, the corresponding search tree is broken into a many smaller subtrees
              (i.e., subsearches), each of which can  be  processed  independently  by  different
              threads.

              This has two consequences:

              • The --threads option cannot be used with --genpairs, since the facet pairings are
                still enumerated in serial.

              • The output that writes each facet pairing to the console will appear  deceptively
                fast.   This  is  because  each  facet  pairing  will be written as soon as it is
                constructed by the main thread, and its many subsearches  will  be  placed  in  a
                queue  for  other  threads  to process while the main thread moves on to the next
                facet pairing.  Once all of the pairings have been output, you may still  face  a
                long  wait  while  the  threads  together  work  their  way  through the queue of
                subsearches that has accumulated.

       -v, --version
              Show which version of Regina is being used, and exit immediately.

       -?, --help
              Display brief usage information, and exit immediately.

EXAMPLES

       The following command forms a census of all 3-tetrahedron closed non-orientable 3-manifold
       triangulations,   and   puts  the  results  in  the  file  results.rga.   To  ensure  that
       triangulations are closed we use the options -i (no boundary triangles) and -f  (no  ideal
       vertices).

           example$ tricensus -t 3 -nif results.rga
           Starting census generation...
           0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 2:3 2:2
           0:1 0:0 1:0 2:0 | 0:2 1:2 1:1 2:1 | 0:3 1:3 2:3 2:2
           0:1 0:0 1:0 2:0 | 0:2 2:1 2:2 2:3 | 0:3 1:1 1:2 1:3
           1:0 1:1 2:0 2:1 | 0:0 0:1 2:2 2:3 | 0:2 0:3 1:2 1:3
           Finished.
           Total triangulations: 5
           example$

       The  following  command  forms  a  census  of  4-tetrahedron  closed orientable 3-manifold
       triangulations, where the census creation is optimised for prime  minimal  triangulations.
       Although all prime minimal triangulations will be included, there may be some non-prime or
       non-minimal triangulations in the census also.

           example$ tricensus -t 4 -oifM results.rga
           Starting census generation...
           0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
           0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 3:0 | 1:2 2:2 2:1 3:1 | 1:3 ...
           ...
           1:0 1:1 2:0 3:0 | 0:0 0:1 2:1 3:1 | 0:2 1:2 3:2 3:3 | 0:3 ...
           Finished.
           Total triangulations: 17
           example$

       The following command generates all face pairings for a 5-tetrahedron census of 3-manifold
       triangulation in which all triangulations have precisely two boundary triangles.  The face
       pairings will be written to pairings.txt, whereupon they can be broken up and  distributed
       for processing at a later date.

           example$ tricensus --genpairs -t 5 -B 2 pairings.txt
           Total face pairings: 118
           example$

       The  face  pairings  generated in the previous example can then be fleshed out into a full
       census of all 3-manifold triangulations  with  five  tetrahedra,  precisely  two  boundary
       triangles  and  no  ideal  vertices  as  follows.   The  number of tetrahedra and boundary
       triangles were already specified in the previous command, and  cannot  be  supplied  here.
       The  face pairings will be read from pairings.txt, and the final census will be written to
       results.rga.

           example$ tricensus --usepairs -f results.rga < pairings.txt
           Trying face pairings...
           0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
           0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 3:0 3:1 | 2:2 ...
           ...
           ... (running through all 118 face pairings)
           ...
           1:0 2:0 3:0 4:0 | 0:0 2:1 3:1 4:1 | 0:1 1:1 3:2 4:2 | 0:2 ...
           Total triangulations: 5817
           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/tricensus.

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\tricensus.exe.

SEE ALSO

       censuslookup, sigcensus, 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                              TRICENSUS(1)