tricensus-manager(1) 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).

AUTHOR

Regina was written by Ben Burton <[email protected]> with help from others; see the documentation for full details.

LAST SEARCHED