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 ] [ -p, --genpairs | -P, --usepairs ]
output-file
tricensus --help
DESCRIPTION
Forms a census of all 3-manifold triangulations satisfying a particular
set of conditions.
The only condition that must be provided is the number of tetrahedra
used to build the triangulations. Additional constraints may be
specified on the command-line as described below.
Each triangulation will be output precisely once up to combinatorial
isomorphism. Invalid triangulations (triangulations with edges
identified to themselves in reverse or boundary vertices whose links
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 census
itself will be saved to the given file.
Note that options --genpairs and --usepairs may be used to split a
census into smaller pieces to be run simultaneously on different
machines. See also the tricensus-manager and tricensus-mpi utilities,
which can help coordinate these simultaneous processes.
Warning: A census with even a relatively small number of
tetrahedra can take an incredibly long time to run and 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 relative to your machine.
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.
-m, --minimal
Do not include triangulations that are obviously non-minimal.
A series of short tests will be run on each triangulation
produced; if a triangulation is found to be non-minimal it will
not be placed in the census.
Note that these tests are not capable of deciding that a
triangulation is minimal; at best the results will be
inconclusive (in which case the triangulation will be placed in
the census anyway).
-M, --minprime
Do not include triangulations that are obviously non-minimal,
non-prime and/or disc-reducible.
This option can significantly speed up the census and vastly
reduce the final number of triangulations produced.
A triangulation satisfying any of the above conditions might be
left out of the census, although not all such triangulations
will be ignored. What is guaranteed is that any triangulation
that is minimal, prime and disc-irreducible will certainly be
included in the census.
-N, --minprimep2
Do not include triangulations that are obviously non-minimal,
non-prime, P2-reducible and/or disc-reducible.
As with the --minprime option, this option can significantly
speed up the census and vastly reduce the final number of
triangulations produced.
A triangulation satisfying any of the above conditions might be
left out of the census, although not all such triangulations
will be ignored. What is guaranteed is that any triangulation
that is minimal, prime, P2-irreducible and disc-irreducible will
certainly be included in the census.
-p, --genpairs
Only generate face pairings, not triangulations.
The outermost layer of the census code involves pairing off the
faces of the individual tetrahedra without actually determining
the corresponding gluing permutations. For each face pairing
produced, all possible sets of gluing permutations are then
generated and corresponding triangulations created.
Face pairing generation consumes a very small fraction of the
total census runtime, and effectively divides the census into
multiple pieces. By using this option, one can quickly generate
a complete list of possible face pairings and then feed subsets
of this list to different machines to work on simultaneously in
order to produce an overall census of triangulations. See the
tricensus-manager and tricensus-mpi utilities for assistance in
coordinating these simultaneous processes.
The list of all face pairings will be written to the given
output file in text format (although in the special case of face
pairing generation you may omit the output file from the
command-line, in which case the pairings will be written to
standard output). This program can then be run with option
--usepairs to generate the actual triangulations corresponding
to different subsets of these face pairings.
Note that orientability, finiteness or minimality options may
not be supplied with this option; they should instead be
supplied when option --usepairs is used to process each subset
of face pairings.
Note also that when this option is used no progress reporting
will take place (although the face pairings should be generated
sufficiently quickly that the output file itself can be used to
track the state of progress).
-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.
Note that the face pairings generated by option --genpairs all
satisfy this condition.
Face pairings should be supplied on standard input, one per
line. They should be listed in the format produced by option
--genpairs.
This option is used to run only a subset of a particular census.
See option --genpairs for further details on how to split a
census into subsets to run simultaneously on different machines.
See also the tricensus-manager and tricensus-mpi utilities,
which can help coordinate these simultaneous processes.
Note that tetrahedron or boundary options may not be supplied
with this option; they should instead be supplied when option
--genpairs is used to split the full 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
Progress reports are periodic.
Not all face pairings used will be reported.
0:1 0:0 1:0 1:1 | 0:2 0:3 2:0 2:1 | 1:2 1:3 2:3 2:2
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
that are left out.
example$ tricensus -t 4 -oifM results.rga
Progress reports are periodic.
Not all face pairings used will be reported.
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 ...
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 where triangulations must 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. Note that the number of tetrahedra and boundary faces were
already specified in the previous command and do not need to be
supplied again. 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$
SEE ALSO
sigcensus, tricensus-manager, tricensus-mpi, regina-kde.
AUTHOR
Regina was written by Ben Burton <bab@debian.org> with help from
others; see the documentation for full details.
12 May 2009