1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
.\" This manpage has been automatically generated by docbook2man
.\" from a DocBook document. This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
.\" Please send any bug reports, improvements, comments, patches,
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "TRICENSUS-MANAGER" "1" "01 May 2006" "" "Specialised Utilities"
.SH NAME
tricensus-manager \- Distribute a triangulation census amongst several machines
.SH SYNOPSIS
\fBtricensus-manager\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\fIpairs-file-prefix\fB\fR
.SH "DESCRIPTION"
.PP
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.
.sp
.RS
.B "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
\fBtricensus-mpi\fR
utility instead.
.RE
.PP
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.
.PP
In preparing a census to be distributed amongst several processes or
machines, it should first be split into several smaller pieces.
Running \fBtricensus\fR
with option \fB--genpairs\fR (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.
.sp
.RS
.B "Note:"
Whereas \fBtricensus-manager\fR
uses many small face pairings files (with individual processes
claiming individual files to work on),
the alternative \fBtricensus-mpi\fR uses a single large face
pairings file (with MPI handling the distribution of pairings to
individual processes).
.RE
.PP
A common file prefix (such as \fI6-or\fR) 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 \fI\&.pairs\fR\&. For instance, if
\fBtricensus\fR with option \fB--genpairs\fR
produced 10 face pairings, these might be split into five files, each
with two lines representing two of these face pairings, named
\fI6-or-0.pairs\fR, \fI6-or-1.pairs\fR,
\fI6-or-2.pairs\fR, \fI6-or-3.pairs\fR and
\fI6-or-4.pairs\fR respectively.
.sp
.RS
.B "Warning:"
Each face pairing that is processed \fBmust\fR be
in canonical form, i.e., must be a minimal representative of its
isomorphism class. Note that the face pairings generated by
\fBtricensus\fR
with option \fB--genpairs\fR all satisfy this condition.
.RE
.PP
The \fBtricensus-manager\fR utility works as follows.
It runs through all files beginning with the given prefix and ending
in \fI\&.pairs\fR, 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
\fI6-or-3.time\fR exists), it will be skipped.
Otherwise the pairings file will be claimed by this process and the
following actions will be taken.
.TP 0.2i
\(bu
This process will write its own time file (such as
\fI6-or-3.time\fR) indicating which machine and
which \fBtricensus-manager\fR process has claimed
this particular subset of face pairings.
.TP 0.2i
\(bu
Command \fBtricensus\fR will be run with this subset
of face pairings to analyse (using option \fB--usepairs\fR).
Any other options given on the \fBtricensus-manager\fR
command-line will be passed directly through to
\fBtricensus\fR (these might include orientability or
minimality options, for instance). The time at which this
subcensus began will be noted in the time file.
.TP 0.2i
\(bu
All output from the running subcensus will be redirected to a
corresponding progress file (such as
\fI6-or-3.progress\fR). In particular, this allows
the user at any given time to see which face pairings from this
particular subset have been processed.
.TP 0.2i
\(bu
When this particular subcensus is complete, the results will be
saved in a corresponding topology data file (such as
\fI6-or-3.rga\fR). The time at which the subcensus
finished will be noted in the time file.
.TP 0.2i
\(bu
At this point \fBtricensus-manager\fR will move on
and look for another subset of face pairings to process.
.PP
Each \fBtricensus-manager\fR process will have at most
one child \fBtricensus\fR 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 \fBtricensus-manager\fR
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.
.PP
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.
.sp
.RS
.B "Tip:"
Once the census is complete, the
\fBregconcat\fR
command may be used to combine the many small topology data files
into one larger file for easier handling.
.RE
.SH "OPTIONS"
.PP
Any census options that are passed to
\fBtricensus-manager\fR will be passed directly through to
\fBtricensus\fR\&. See the
\fBtricensus\fR reference
for details.
.PP
Note that some \fBtricensus\fR 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 \fBtricensus --genpairs\fR\&.
.PP
The option \fB--usepairs\fR need not be given to
\fBtricensus-manager\fR; this will be automatically
supplied to each child \fBtricensus\fR process.
.PP
Topology data output filenames must not be given to
\fBtricensus-manager\fR since these differ for each
subcensus. Topology data filenames will be automatically
derived and supplied to each child \fBtricensus\fR process.
.SH "EXAMPLES"
.PP
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).
.PP
We begin by using \fBtricensus\fR to generate a full
list of face pairings.
.nf
example$ \fBtricensus --genpairs -t 5 -i > 5.pairs\fR
Total face pairings: 28
example$
.fi
.PP
We now split the large face pairings file into several smaller
files, each containing 4 of the 28 pairings. The
\fBsplit\fR command is useful for this task. Don't
forget that these files \fBmust\fR be renamed
so that they end in the extension \fI\&.pairs\fR\&.
.nf
example$ \fBsplit -l 4 5.pairs 5-nor\fR
example$ \fBls\fR
5-noraa 5-norab 5-norac 5-norad 5-norae 5-noraf 5-norag 5.pairs
example$ \fBprename 's/$/.pairs/' 5-nor*\fR
example$ \fBls\fR
5-noraa.pairs 5-norac.pairs 5-norae.pairs 5-norag.pairs
5-norab.pairs 5-norad.pairs 5-noraf.pairs 5.pairs
example$
.fi
.PP
Finally, on each individual machine that will join in the
computation, we use \fBtricensus-manager\fR to start a
new process. The remaining census options are passed here.
.nf
node_1$ \fBtricensus-manager -nfN 5-nor\fR
Trying 5-noraa.pairs ... taken and processing ...
.fi
.nf
node_2$ \fBtricensus-manager -nfN 5-nor\fR
Trying 5-noraa.pairs ... skipped.
Trying 5-norab.pairs ... taken and processing ...
.fi
.nf
node_3$ \fBtricensus-manager -nfN 5-nor\fR
Trying 5-noraa.pairs ... skipped.
Trying 5-norab.pairs ... skipped.
Trying 5-norac.pairs ... taken and processing ...
.fi
.PP
Note that we pass a prefix of \fI5-nor\fR to avoid
catching the master file \fI5.pairs\fR\&. It is
possibly safer simply to move \fI5.pairs\fR out of
the way (or rename it so it does not have the
\fI\&.pairs\fR extension and therefore will not be
picked up).
.SH "SEE ALSO"
.PP
regconcat,
sigcensus,
tricensus,
tricensus-mpi,
regina-kde\&.
.SH "AUTHOR"
.PP
\fBRegina\fR was written by Ben Burton <bab@debian.org> with help from others;
see the documentation for full details.
|
