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 ] [ -p, --genpairs | -P, --usepairs ] output-file

tricensus --help

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.

-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.

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$

sigcensus, tricensus-manager, tricensus-mpi, regina-kde.

Regina was written by Ben Burton <bab@debian.org> with help from others; see the documentation for full details.