.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\"
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng .
.TH "TRICENSUS" "1" "14 March 2023" "" "The Regina Handbook"
.SH NAME
tricensus \- Form a census of triangulations
.SH SYNOPSIS
\fBtricensus\fR [ \fB-t, --tetrahedra=\fItetrahedra\fB\fR ] [ \fB-2, --dim2\fR | \fB-4, --dim4\fR ] [ \fB-b, --boundary\fR | \fB-i, --internal\fR | \fB-B, --bdryfaces=\fItriangles\fB\fR ] [ \fB-o, --orientable\fR | \fB-n, --nonorientable\fR ] [ \fB-f, --finite\fR | \fB-d, --ideal\fR ] [ \fB-m, --minimal\fR | \fB-M, --minprime\fR | \fB-N, --minprimep2\fR | \fB-h, --minhyp\fR ] [ \fB--allowinvalid\fR ] [ \fB-s, --sigs\fR | \fB-S, --canonical\fR | \fB-e, --encodings\fR | \fB-c, --subcontainers\fR ] [ \fB-p, --genpairs\fR | \fB-P, --usepairs\fR ] [ \fB--threads=\fInum_threads\fB\fR ] \fB\fIoutput-file\fB\fR
\fBtricensus\fR { \fB-v, --version\fR | \fB-?, --help\fR }
.SH "DESCRIPTION"
.PP
Forms a census of all 2-, 3- or 4-manifold triangulations that satisfy
some set of conditions.
.PP
These conditions are specified using various command-line arguments.
The only condition that you \fBmust\fR provide is
the number of top-dimensional simplices (e.g., the number of tetrahedra
for 3-manifolds), but there are many other options available.
.PP
The default behaviour is to enumerate 3-manifold triangulations.
If you wish to enumerate 2-manifold or 4-manifold triangulations instead,
you must pass \fB--dim2\fR or \fB--dim4\fR
respectively.
.PP
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.
.PP
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.
.PP
You can use the options \fB--genpairs\fR and
\fB--usepairs\fR to split a census into smaller pieces.
.sp
.RS
.B "Caution:"
.PP
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.
.PP
For very large census runs, it is \fBhighly recommended\fR
that you use the either the \fB--sigs\fR or
\fB--encodings\fR option, which will keep
the output file small and significantly reduce the memory footprint.
.RE
.SH "OPTIONS"
.TP
\fB-t, --tetrahedra=\fItetrahedra\fB\fR
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.
.TP
\fB-2, --dim2\fR
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
\fB--dim2\fR\&.
This option cannot be used with \fB--dim4\fR\&.
.TP
\fB-4, --dim4\fR
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
\fB--dim4\fR\&.
This option cannot be used with \fB--dim2\fR\&.
.TP
\fB-b, --boundary\fR
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.
.TP
\fB-i, --internal\fR
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.
.TP
\fB-B, --bdryfaces=\fItriangles\fB\fR
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.
.TP
\fB-o, --orientable\fR
Only produce orientable triangulations.
.TP
\fB-n, --nonorientable\fR
Only produce non-orientable triangulations.
.TP
\fB-f, --finite\fR
Only produce finite triangulations (triangulations with no
ideal vertices).
This option cannot be used with \fB--dim2\fR\&.
.TP
\fB-d, --ideal\fR
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 \fB--dim2\fR\&.
.TP
\fB-m, --minimal\fR
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 \fB--dim4\fR\&.
.TP
\fB-M, --minprime\fR
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 \fB--dim2\fR
or \fB--dim4\fR\&.
.TP
\fB-N, --minprimep2\fR
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 \fB--minprime\fR\&.
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 \fB--dim2\fR
or \fB--dim4\fR\&.
.TP
\fB-h, --minhyp\fR
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
\fB--finite\fR or \fB--boundary\fR
will produce an error message).
This option also cannot be used with \fB--dim2\fR
or \fB--dim4\fR\&.
.TP
\fB--allowinvalid\fR
Normally, \fBtricensus\fR will test each triangulation that
is constructed for validity before including it in the final output.
If you pass \fB--allowinvalid\fR however, then these
validity tests will not be performed.
As a result, the output may include some invalid triangulations.
However, it will not include \fBall\fR 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 \fB--allowinvalid\fR option.
The one guarantee that you \fBdo\fR get from this option
is that the census will include all invalid triangulations that could
appear as a \fBsubcomplex\fR 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.
.TP
\fB-s, --sigs\fR
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
\fBtricensus\fR 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.
.TP
\fB-S, --canonical\fR
A variant of \fB--sigs\fR 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 \fB--sigs\fR\&. The second string encodes an
isomorphism \fIF\fR with the property that,
if we reconstruct a triangulation from the isomorphism signature
and apply the isomorphism \fIF\fR, then
the resulting triangulation will have a canonical facet pairing.
Here \fIcanonical\fR has the same meaning as
described below under the \fB--usepairs\fR 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
\fItight encodings\fR, 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 \fB--sigs\fR
instead.
.TP
\fB-e, --encodings\fR
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
\fItight encoding\fR\&.
Tight encodings differ from isomorphism signatures (as output by
\fB--sigs\fR) in the following ways:
.RS
.TP 0.2i
\(bu
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).
.TP 0.2i
\(bu
In general, tight encodings use slightly more characters and
are slightly faster to compute than isomorphism signatures.
.TP 0.2i
\(bu
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()\&.
.RE
If you are not sure whether to use isomorphism signatures or
tight encodings, it is recommended that you choose isomorphism
signatures (\fB--sigs\fR).
Like \fB--sigs\fR, 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 \fBtricensus\fR will also be much smaller.
See the \fB--sigs\fR option for further details.
You can also use \fB--encodings\fR with
\fB--genpairs\fR, 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 \fB--usepairs\fR, and again you
will need to use C++ or Python to reconstruct facet pairings
from them.
.TP
\fB-c, --subcontainers\fR
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 \fB--genpairs\fR below for further information on
facet pairings.
This option cannot be used with \fB--sigs\fR,
\fB--canonical\fR or \fB--encodings\fR\&.
.TP
\fB-p, --genpairs\fR
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
\fB--usepairs\fR (see below). However, if you pass
\fB--encodings\fR then the output format will use
tight encodings (which are shorter, contain no spaces, and are
much harder for humans to read). See \fB--encodings\fR
for further details on tight encodings.
If you are coordinating your sub-censuses manually, you can
use the option \fB--usepairs\fR 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 \fB--genpairs\fR; instead you should use them
later with \fB--usepairs\fR\&.
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.
.TP
\fB-P, --usepairs\fR
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
\fB--genpairs\fR 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 \fB--genpairs\fR\&.
This option effectively lets you run a subset of a larger census.
See \fB--genpairs\fR 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., \fB--tetrahedra\fR) or boundary facets
(i.e., \fB--boundary\fR or \fB--bdryfaces\fR)
cannot be used with \fB--usepairs\fR\&.
Instead you should pass these options earlier
along with \fB--genpairs\fR when you split the original
census into pieces.
.TP
\fB--threads=\fInum_threads\fB\fR
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 \fInum_threads\fR\&.
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:
.RS
.TP 0.2i
\(bu
The \fB--threads\fR option cannot be used with
\fB--genpairs\fR, since the facet pairings are still
enumerated in serial.
.TP 0.2i
\(bu
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.
.RE
.TP
\fB-v, --version\fR
Show which version of Regina is being used, and exit
immediately.
.TP
\fB-?, --help\fR
Display brief usage information, and exit immediately.
.SH "EXAMPLES"
.PP
The following command forms a census of all 3-tetrahedron closed
non-orientable 3-manifold triangulations, and puts the results in the file
\fIresults.rga\fR\&. To ensure that triangulations are
closed we use the options \fB-i\fR (no boundary triangles)
and \fB-f\fR (no ideal vertices).
.nf
example$ \fBtricensus -t 3 -nif results.rga\fR
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$
.fi
.PP
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.
.nf
example$ \fBtricensus -t 4 -oifM results.rga\fR
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$
.fi
.PP
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
\fIpairings.txt\fR, whereupon they can be broken up
and distributed for processing at a later date.
.nf
example$ \fBtricensus --genpairs -t 5 -B 2 pairings.txt\fR
Total face pairings: 118
example$
.fi
.PP
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
\fIpairings.txt\fR, and the final census will be
written to \fIresults.rga\fR\&.
.nf
example$ \fBtricensus --usepairs -f results.rga < pairings.txt\fR
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$
.fi
.SH "MACOS USERS"
.PP
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\&.
.SH "WINDOWS USERS"
.PP
The command-line utilities are installed beneath the
\fIProgram\~Files\fR directory; on some
machines this directory is called
\fIProgram\~Files\~(x86)\fR\&.
You can start this utility by running
c:\\Program\~Files\\Regina\\Regina\~7.3\\bin\\tricensus.exe\&.
.SH "SEE ALSO"
.PP
censuslookup,
sigcensus,
regina-gui\&.
.SH "AUTHOR"
.PP
This utility was written by Benjamin Burton
\&.
Many people have been involved in the development
of Regina; see the users' handbook for a full list of credits.