![]() | tricensus |
Prev | Command Line: Specialised Utilities | Next |
tricensus — Form a census of 3-manifold triangulations
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
}
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 tr iangulations (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.
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.
-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 → → 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