NAME
tricensus-manager - Distribute a triangulation census amongst several
machines
SYNOPSIS
tricensus-manager [ -o, --orientable | -n, --nonorientable ] [ -f,
--finite | -d, --ideal ] [ -m, --minimal | -M, --minprime | -N,
--minprimep2 ] pairs-file-prefix
DESCRIPTION
Allows multiple processes, possibly running on different machines, to
collaborate in forming a census of 3-manifold triangulations.
Coordination is done through a simple locking of files in a shared
directory, and each separate process must be started manually.
Note: This program makes no use of any formal cluster-like
infrastructure. For an MPI-enabled program better suited to
running on a cluster, see the tricensus-mpi utility instead.
Census generation must take place in a single directory. The different
processes are coordinated by locking files in this directory, and
progress reports and final results are stored in this directory also.
If the census is to be distributed amongst different machines (not just
different processors), this directory must be on a filesystem to which
they all have access.
In preparing a census to be distributed amongst several processes or
machines, it should first be split into several smaller pieces.
Running tricensus with option --genpairs (which is quite fast) will
create a list of face pairings, each of which must be analysed in order
to complete the census. The census is split into pieces by subdividing
this list of face pairings.
Note: Whereas tricensus-manager uses many small face pairings
files (with individual processes claiming individual files to
work on), the alternative tricensus-mpi uses a single large face
pairings file (with MPI handling the distribution of pairings to
individual processes).
A common file prefix (such as 6-or) should be selected. Each subset of
face pairings should be stored (one face pairing per line) in a file
whose name begins with this prefix and ends with .pairs. For instance,
if tricensus with option --genpairs produced 10 face pairings, these
might be split into five files, each with two lines representing two of
these face pairings, named 6-or-0.pairs, 6-or-1.pairs, 6-or-2.pairs,
6-or-3.pairs and 6-or-4.pairs respectively.
Warning: 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
tricensus with option --genpairs all satisfy this condition.
The tricensus-manager utility works as follows. It runs through all
files beginning with the given prefix and ending in .pairs, and assumes
each of these contains a subset of face pairings to process. If a
pairings file has already been taken by another process (i.e., if a
corresponding time file such as 6-or-3.time exists), it will be
skipped. Otherwise the pairings file will be claimed by this process
and the following actions will be taken.
· This process will write its own time file (such as 6-or-3.time)
indicating which machine and which tricensus-manager process has
claimed this particular subset of face pairings.
· Command tricensus will be run with this subset of face pairings to
analyse (using option --usepairs). Any other options given on the
tricensus-manager command-line will be passed directly through to
tricensus (these might include orientability or minimality options,
for instance). The time at which this subcensus began will be noted
in the time file.
· All output from the running subcensus will be redirected to a
corresponding progress file (such as 6-or-3.progress). In
particular, this allows the user at any given time to see which face
pairings from this particular subset have been processed.
· When this particular subcensus is complete, the results will be saved
in a corresponding topology data file (such as 6-or-3.rga). The time
at which the subcensus finished will be noted in the time file.
· At this point tricensus-manager will move on and look for another
subset of face pairings to process.
Each tricensus-manager process will have at most one child tricensus
process running at any given time. Thus, for instance, if you have
nine machines (all with access to the common census directory) and you
wish to have two census calculations running simultaneously on each of
these machines, you should start tricensus-manager a total of 18 times,
twice on each machine, each with an identical command-line. These 18
simultaneous processes will then effectively divide up the overall
census between them.
Note that the number of face pairings files does not need to equal the
number of processors. In fact, it is generally good to have a very
large number of small face pairings files (rather than a few larger
face pairings files). Different files may take significantly different
times to process, and so by using many smaller files the workload can
be distributed more evenly between the various processors.
Tip: Once the census is complete, the regconcat command may be
used to combine the many small topology data files into one
larger file for easier handling.
OPTIONS
Any census options that are passed to tricensus-manager will be passed
directly through to tricensus. See the tricensus reference for
details.
Note that some tricensus options are not available here (e.g.,
tetrahedra and boundary options), since these must be supplied earlier
on when generating the initial list of face pairings through tricensus
--genpairs.
The option --usepairs need not be given to tricensus-manager; this will
be automatically supplied to each child tricensus process.
Topology data output filenames must not be given to tricensus-manager
since these differ for each subcensus. Topology data filenames will be
automatically derived and supplied to each child tricensus process.
EXAMPLES
Suppose we wish to form a census of all 5-tetrahedron closed non-
orientable triangulations, where the census is optimised for prime
minimal P2-irreducible triangulations (and in particular, some
triangulations that are not prime, minimal and P2-irreducible may be
left out).
We begin by using tricensus to generate a full list of face pairings.
example$ tricensus --genpairs -t 5 -i > 5.pairs
Total face pairings: 28
example$
We now split the large face pairings file into several smaller files,
each containing 4 of the 28 pairings. The split command is useful for
this task. Don’t forget that these files must be renamed so that they
end in the extension .pairs.
example$ split -l 4 5.pairs 5-nor
example$ ls
5-noraa 5-norab 5-norac 5-norad 5-norae 5-noraf 5-norag 5.pairs
example$ prename ’s/$/.pairs/’ 5-nor*
example$ ls
5-noraa.pairs 5-norac.pairs 5-norae.pairs 5-norag.pairs
5-norab.pairs 5-norad.pairs 5-noraf.pairs 5.pairs
example$
Finally, on each individual machine that will join in the computation,
we use tricensus-manager to start a new process. The remaining census
options are passed here.
node_1$ tricensus-manager -nfN 5-nor
Trying 5-noraa.pairs ... taken and processing ...
node_2$ tricensus-manager -nfN 5-nor
Trying 5-noraa.pairs ... skipped.
Trying 5-norab.pairs ... taken and processing ...
node_3$ tricensus-manager -nfN 5-nor
Trying 5-noraa.pairs ... skipped.
Trying 5-norab.pairs ... skipped.
Trying 5-norac.pairs ... taken and processing ...
Note that we pass a prefix of 5-nor to avoid catching the master file
5.pairs. It is possibly safer simply to move 5.pairs out of the way
(or rename it so it does not have the .pairs extension and therefore
will not be picked up).
SEE ALSO
regconcat, sigcensus, tricensus, tricensus-mpi, regina-kde.
AUTHOR
Regina was written by Ben Burton <bab@debian.org> with help from
others; see the documentation for full details.
12 May 2009