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 ] outputfile
tricensus help
DESCRIPTION
Forms a census of all 3manifold or 2manifold triangulations that satisfy some set of conditions.
These conditions are specified using various commandline 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 3manifold triangulations. If you wish to enumerate 2manifold triangulations instead, you must pass dim2.
Each triangulation will be output precisely once up to combinatorial isomorphism. Invalid 3manifold 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 tricensusmpi, a more powerful tool that allows you to distribute a census across a highperformance 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 2manifold triangulations, not 3manifold
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 nonorientable 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 nonminimal.
This option uses a series of fast tests that try to eliminate nonminimal triangulations, but that are not always conclusive. If Regina cannot quickly tell whether a triangulation is nonminimal, it will place the triangulation in the census regardless.
 M, minprime

Do not include triangulations that are obviously nonminimal,
nonprime and/or discreducible.
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 nonminimal, nonprime or discreducible, 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 nonminimal,
nonprime, P2reducible and/or discreducible.
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 nonminimal, nonprime, P2reducible or discreducible, 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 finitevolume hyperbolic
3manifolds.
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 finitevolume hyperbolic 3manifold, 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 tricensusmpi to coordinate it for you on a highperformance 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 subcensuses 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 tricensusmpi.
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 tricensusmpi which can coordinate this process using MPI on a highperformance 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 3tetrahedron closed nonorientable 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 4tetrahedron 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 nonprime or nonminimal 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 5tetrahedron 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 3manifold 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 draganddrop 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 commandline 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.
AUTHOR
This utility was written by Benjamin Burton <[email protected]>. Many people have been involved in the development of Regina; see the users' handbook for a full list of credits.