Provided by: regina-normal_7.0-2build1_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 ] [ -s, --sigs | -c, --subcontainers ]  [  -p,  --genpairs  |  -P,  --usepairs  ]
       output-file

       tricensus --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  --sigs
              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.

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

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

       -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 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).  If you are coordinating
              your  sub-censuses  manually,  you  can  use  the  option  --usepairs  to  generate
              triangulations from a subset of these facet pairings.

              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
              listed in the 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.

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.0\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.

                                         17 December 2021                            TRICENSUS(1)