Provided by: regina-normal-mpi_5.1-6ubuntu1_amd64 
NAME
tricensus-mpi - Distribute a triangulation census amongst several machines using MPI
SYNOPSIS
tricensus-mpi [ -D, --depth=levels ] [ -x, --dryrun ] [ -2, --dim2 | -4, --dim4 ] [ -o,
--orientable | -n, --nonorientable ] [ -f, --finite | -d, --ideal ] [ -m, --minimal | -M,
--minprime | -N, --minprimep2 | -h, --minhyp ] [ -s, --sigs ] pairs-file output-file-
prefix
CAUTION
The MPI utilities in Regina are deprecated, and will be removed from Regina in a future
release. If you wish to parallelise the generation of a census, we recommend splitting up
the input pairing files into chunks, and using typical queue systems (such as PBS) to
parallelise.
DESCRIPTION
Allows multiple processes, possibly running on a cluster of different machines, to
collaborate in forming a census of 2-, 3- or 4-manifold triangulations. Coordination is
done through MPI (the Message Passing Interface), and the entire census is run as a single
MPI job. This program is well suited for high-performance clusters.
The default behaviour is to enumerate 3-manifold triangulations. If you wish to enumerate
2-manifold or 4-manifold triangulations instead, you must pass --dim2 or --dim4
respectively.
To prepare a census for distribution amongst several processes or machines, the census
must be split into smaller pieces. Running tricensus with option --genpairs (which is
very fast) will create a list of facet pairings (e.g., tetrahedron face pairings for
3-manifold triangulations, triangle edge pairings for 2-manifold triangulations, and so
on). Each facet pairing must be analysed in order to complete the census.
The full list of facet pairings should be stored in a single file, which is passed on the
command-line as pairs-file. This file must contain one facet pairing per line, and each
of these facet pairings must be in canonical form (i.e., must be a minimal representative
of its isomorphism class). The facet pairings generated by tricensus --genpairs are
guaranteed to satisfy these conditions.
The tricensus-mpi utility has two modes of operation: default mode, and subsearch mode.
These are explained separately under modes of operation below.
In both modes, one MPI process acts as the controller and the remaining processes all act
as slaves. The controller reads the list of facet pairings from pairs-file, constructs a
series of tasks based on these, and farms these tasks out to the slaves for processing.
Each slave processes one task at a time, asking the controller for a new task when it is
finished with the previous one.
At the end of each task, if any triangulations were found then the slave responsible will
save these triangulations to an output file. The output file will have a name of the form
output-file-prefix_p.rga in default mode or output-file-prefix_p-s.rga in subsearch mode.
Here output-file-prefix is passed on the command line, p is the number of the facet
pairing being processed, and s is the number of the subsearch within that facet pairing
(both facet pairings and subsearches are numbered from 1 upwards). If no triangulations
were found then the slave will not write any output file at all.
The controller and slave processes all take the same tricensus-mpi options (excluding MPI-
specific options, which are generally supplied by an MPI wrapper program such as mpirun or
mpiexec). The different roles of the processes are determined solely by their MPI process
rank (the controller is always the process with rank 0). It should therefore be possible
to start all MPI processes by running a single command, as illustrated in the examples
below.
As the census progresses, the controller keeps a detailed log of each slave's activities,
including how long each slave task has taken and how many triangulations have been found.
This log is written to the file output-file-prefix.log. The utility tricensus-mpi-status
can parse this log and produce a shorter human-readable summary.
Important: It is highly recommended that you use the --sigs option. This will keep
output files small, and will significantly reduce the memory footprint of
tricensus-mpi itself.
MODES OF OPERATION
As discussed above, there are two basic modes of operation. These are default mode (used
when --depth is not passed), and subsearch mode (used when --depth is passed).
• In default mode, the controller simply reads the list of facet pairings and gives each
pairing to a slave for processing, one after another.
• In subsearch mode, more work is pushed to the controller and the slave tasks are
shorter. Here the controller reads one facet pairing at a time and begins processing
that facet pairing. A fixed depth is supplied in the argument --depth; each time that
depth is reached in the search tree, the subsearch from that point on is given as a task
to the next idle slave. Meanwhile the controller backtracks (as though the subsearch
had finished) and continues, farming the next subsearch out when the given depth is
reached again, and so on.
The modes can be visualised as follows. For each facet pairing, consider the
corresponding recursive search as a large search tree. In default mode, the entire tree
is processed at once as a single slave task. In subsearch mode, each subtree rooted at
the given depth is processed as a separate slave task (and all processing between the root
and the given depth is done by the controller).
The main difference between the different modes of operation is the lengths of the slave
tasks, which can have a variety of effects.
• In default mode the slave tasks are quite long. This means the parallelisation can
become very poor towards the end of the census, with some slaves sitting idle for a long
time as they wait for the remaining slaves to finish.
• As we move to subsearch mode with increasing depth, the slave tasks become shorter and
the slaves' finish times will be closer together (thus avoiding the idle slave
inefficiency described above). Moreover, with a more refined subsearch, the progress
information stored in the log will be more detailed, giving a better idea of how long
the census has to go. On the other hand, more work is pushed to the single-process
controller (risking a bottleneck if the depth is too great, with slaves now sitting idle
as they wait for new tasks). In addition the MPI overhead is greater, and the number of
output files can become extremely large.
In the end, experimentation is the best way to decide whether to run in subsearch mode and
at what depth. Be aware of the option --dryrun, which can give a quick overview of the
search space (and in particular, show how many subsearches are required for each facet
pairing at any given depth).
OPTIONS
The census options accepted by tricensus-mpi are identical to the options for tricensus
See the tricensus reference for details.
Some options from tricensus are not available here (e.g., tetrahedra and boundary
options), since these must be supplied earlier on when generating the initial list of
facet pairings.
There are new options specific to tricensus-mpi, which are as follows.
-D, --depth=levels
Indicates that subsearch mode should be used (instead of default mode). The
argument levels specifies at what depth in the search tree processing should pass
from the controller to a new slave task.
The given depth must be strictly positive (running at depth zero is equivalent to
running in default mode).
See the modes of operation section above for further information, as well as hints
on choosing a good value for levels.
-x, --dryrun
Specifies that a fast dry run should be performed, instead of a full census.
In a dry run, each time a slave accepts a task it will immediately mark it as
finished with no triangulations found. The behaviour of the controller remains
unchanged.
The result will be an empty census. The benefit of a dry run is the log file it
produces, which will show precisely how facet pairings would be divided into
subsearches in a real census run. In particular, the log file will show how many
subsearches each facet pairing produces (the utility tricensus-mpi-status can help
extract this information from the log).
At small subsearch depths, a dry run should be extremely fast. As the depth
increases however, the dry run will become slower due to the extra work given to
the controller.
This option is only useful in subsearch mode (it can be used in default mode, but
the results are uninteresting). See the modes of operation section above for
further details.
EXAMPLES
Suppose we wish to form a census of all 6-tetrahedron closed non-orientable 3-manifold
triangulations, optimised for prime minimal P2-irreducible triangulations (so some non-
prime, non-minimal or non-P2-irreducible triangulations may be omitted).
We begin by using tricensus to generate a full list of face pairings.
example$ tricensus --genpairs -t 6 -i > 6.pairs
Total face pairings: 97
example$
We now use tricensus-mpi to run the distributed census. A wrapper program such as mpirun
or mpiexec can generally be used to start the MPI processes, though this depends on your
specific MPI implementation. The following command runs a distributed census on 10
processors using the MPICH implementation of MPI.
example$ mpirun -np 10 /usr/bin/tricensus-mpi -Nnf 6.pairs 6-nor
example$
The current state of processing is kept in the controller log 6-nor.log. You can watch
this log with the help of tricensus-mpi-status.
example$ tricensus-mpi-status 6-nor.log
Pairing 1: done, 0 found
...
Pairing 85: done, 0 found
Pairing 86: done, 7 found
Pairing 87: running
Pairing 88: running
Still running, 15 found, last activity: Wed Jun 10 05:57:34 2009
example$
Once the census is finished, the resulting triangulations will be saved in files such as
6-nor_8.rga, 6-nor_86.rga and so on.
MACOS X AND WINDOWS USERS
This utility is not shipped with the drag-and-drop app bundle for MacOS X or with the
Windows installer.
SEE ALSO
censuslookup, regconcat, sigcensus, tricensus, tricensus-mpi-status, regina-gui.
AUTHOR
This utility was written by Benjamin Burton <bab@maths.uq.edu.au>. Many people have been
involved in the development of Regina; see the users' handbook for a full list of credits.
14 December 2016 TRICENSUS-MPI(1)