NAME¶
tricensus - Form a census of 3-manifold triangulations
SYNOPSIS¶
tricensus [
-t, --tetrahedra=tetrahedra ] [
-b,
--boundary |
-i, --internal |
-B,
--bdryfaces=faces ] [
-o, --orientable |
-n,
--nonorientable ] [
-f, --finite |
-d, --ideal ] [
-m,
--minimal |
-M, --minprime |
-N, --minprimep2 ] [
-s,
--sigs= ] [
-p, --genpairs |
-P, --usepairs ]
output-file
tricensus --help
DESCRIPTION¶
Forms a census of all 3-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.
Each triangulation will be output precisely once up to combinatorial
isomorphism. Invalid 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.
- -b, --boundary
- Only produce triangulations with at least one boundary
face.
- -i, --internal
- Only produce triangulations with all faces internal (i.e.,
with no boundary faces).
- -B, --bdryfaces=faces
- Only produce triangulations with the precise number of
boundary faces specified.
- -o, --orientable
- Only produce orientable triangulations.
- -n, --nonorientable
- Only produce non-orientable triangulations.
- -f, --finite
- Only produce finite triangulations (triangulations with no
ideal vertices).
- -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.
- -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.
- -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.
- -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 3-manifold
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.
- -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.
- -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 faces cannot be used with
--usepairs; instead you should pass them 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
triangulations and puts the results in the file
results.rga. To ensure
that triangulations are closed we use the options
-i (no boundary
faces) 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 faces. 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 faces and no ideal vertices as follows. The number of tetrahedra
and boundary faces 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.93\bin\tricensus.exe.
SEE ALSO¶
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.