tricensus

TRICENSUS(1)                  The Regina Handbook                 TRICENSUS(1)



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.  See also tricensus-mpi, a more powerful tool that
       allows you to distribute a census across a high-performance computing
       cluster.

              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.  You can coordinate this manually, or you can
              use tricensus-mpi to coordinate it for you on a high-performance
              cluster.

              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, or pass them to tricensus-mpi.

              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, or tricensus-mpi which can coordinate this process
              using MPI on a high-performance cluster.

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

SEE ALSO
       censuslookup, sigcensus, tricensus-mpi, 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 December 2016                   TRICENSUS(1)