Provided by: regina-normal_4.96-2.1build2_amd64 
NAME
tricensus - Form a census of 3-manifold triangulations
SYNOPSIS
tricensus [ -t, --tetrahedra=tetrahedra ] [ -2, --dim2 ] [ -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 3-manifold or 2-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 tetrahedra, but there are many other options
available.
The default behaviour is to enumerate 3-manifold triangulations. If you wish to enumerate
2-manifold triangulations instead, you must pass --dim2.
Each triangulation will be output precisely once up to combinatorial isomorphism. Invalid
3-manifold triangulations (i.e., 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 tetrahedra 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 tetrahedra), 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 tetrahedra used to build the triangulations.
If --dim2 is passed, this same option must be used to specify the number of
triangles instead.
-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.
-b, --boundary
Only produce triangulations with at least one boundary triangle.
If --dim2 is passed, this specifies at least one boundary edge.
-i, --internal
Only produce triangulations with all triangles internal (i.e., with no boundary
triangles).
If --dim2 is passed, this indicates that all edges must be internal.
-B, --bdryfaces=triangles
Only produce triangulations with the precise number of boundary triangles
specified.
If --dim2 is passed, this specifies the number of boundary edges.
-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.
-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.
-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.
-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.
-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 face pairing, a new container will be created, and resultant
triangulations will be placed into these containers. These containers will be
created even if the face pairing results in no triangulations.
This option cannot be used with --sigs.
-p, --genpairs
Only generate face pairings, not triangulations.
The outermost layer of the census code involves pairing off the faces of individual
tetrahedra without determining the corresponding gluing permutations. For each
face pairing that is produced, Regina will try many different sets of gluing
permutations and generated the corresponding triangulations.
Face 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 face 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 face 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 face 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 face 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.
If --dim2 is passed, this generates edge pairings accordingly.
-P, --usepairs
Use only the given subset of face pairings to build the triangulations.
Each face pairing that is processed must be in canonical form, i.e., must be a
minimal representative of its isomorphism class. All face pairings generated using
--genpairs are guaranteed to satisfy this condition.
Face 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 tetrahedra or boundary triangles cannot be used with --usepairs;
instead you should pass them earlier along with --genpairs when you split the
original census into pieces.
If --dim2 is passed, this takes a list of edge pairings accordingly.
EXAMPLES
The following command forms a census of all 3-tetrahedron closed non-orientable
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 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 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 4.96\bin\tricensus.exe.
SEE ALSO
censuslookup, sigcensus, tricensus-mpi, regina-gui.
AUTHOR
This utility was written by Benjamin Burton <bab@debian.org>. Many people have been
involved in the development of Regina; see the users' handbook for a full list of credits.
23 August 2014 TRICENSUS(1)