.\" 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 December 2016" "" "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-s, --sigs\fR | \fB-c, --subcontainers\fR ] [ \fB-p, --genpairs\fR | \fB-P, --usepairs\fR ] \fB\fIoutput-file\fB\fR \fBtricensus\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. See also \fBtricensus-mpi\fR, a more powerful tool that allows you to distribute a census across a high-performance computing cluster. .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 \fB--sigs\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-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 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-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\&. .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. You can coordinate this manually, or you can use \fBtricensus-mpi\fR to coordinate it for you on a high-performance cluster. The list of all facet 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 facet pairings will be written to standard output). 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. Options for orientability, finiteness or minimality cannot be used with \fB--genpairs\fR; instead you should use them later with \fB--usepairs\fR, or pass them to \fBtricensus-mpi\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 listed in the 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, or \fBtricensus-mpi\fR which can coordinate this process using MPI on a high-performance cluster. 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. .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\\~X 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\~5.1\\bin\\tricensus.exe\&. .SH "SEE ALSO" .PP censuslookup, sigcensus, tricensus-mpi, 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.