Ubuntu Manpage: tricensus - Form a census of triangulations

Provided by: regina-normal_7.3.1-1_amd64

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

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)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

MACOS USERS

WINDOWS USERS

SEE ALSO

AUTHOR