1
<sect1 id="featureset">
2
<title>What does Regina do?</title>
5
A list of ®ina;'s more noteworthy features is presented below.
8
<sect2 id="features-tri">
9
<title>Triangulations</title>
12
The primary objects that a user works with in ®ina; are
13
3-manifold triangulations. As such, a large part of
14
the software is devoted to the creation, analysis and manipulation of
18
<sect3 id="features-tricreation">
19
<title>Creation</title>
22
You can create 3-manifold triangulations in the following ways:
25
manual construction by entering
26
individual tetrahedron face gluings by hand;
29
automatic generation of several standard families of triangulations,
30
such as layered solid tori and layered lens spaces
31
<xref linkend="bib-0-efficiency"/>,
32
<xref linkend="bib-layeredlensspaces"/>,
33
and standard constructions of &sfslong;s over the sphere;
37
text-based isomorphism signatures <xref linkend="bib-burton-simps3"/>
38
and Callahan-Hildebrand-Weeks
39
dehydration strings <xref linkend="bib-cuspedcensus"/>;
42
importing triangulations from &snappeapylink; and &orburl;;
45
automatic construction of several ready-made example triangulations.
51
<sect3 id="features-trianalysis">
52
<title>Analysis</title>
54
You can compute the following properties of a 3-manifold triangulation:
57
detailed combinatorial information about the skeleton and
58
boundary components, including vertex links
59
and the shapes formed by the various triangulation faces;
62
a variety of homology and homotopy groups;
65
the quantum invariants of Turaev and Viro
66
<xref linkend="bib-turaevviro"/>;
69
the Kawauchi-Kojima invariants of the torsion linking form
70
<xref linkend="bib-kktorsionlinkingform"/>, and comments on
71
where the triangulation might be embeddable;
74
3-sphere and 3-ball recognition, as well as a complete connected sum
75
decomposition for closed orientable triangulations;
78
triangulation attributes relating to the existence of particular
79
types of normal surface, such as 0-efficiency <xref
80
linkend="bib-0-efficiency"/>
81
and the existence of splitting surfaces
82
(described <link linkend="features-splitting">below</link>);
85
geometric properties, courtesy of the &snappea; kernel;
88
a visual representation of the face pairing graph
89
<xref linkend="bib-burton-facegraphs"/>, with the help
93
text-based isomorphism signatures <xref linkend="bib-burton-simps3"/>,
94
which identify a triangulation uniquely up to combinatorial isomorphism;
97
Callahan-Hildebrand-Weeks dehydration strings
98
<xref linkend="bib-cuspedcensus"/>,
99
for those triangulations that can support them.
105
Pairs of triangulations can be tested for direct isomorphism, or for
106
whether one triangulation is isomorphic to a subcomplex of another. In
107
addition the software can recognise and identify a large variety of
108
well-formed structures within a
109
triangulation. These include common building blocks (such as the
110
layered solid tori mentioned above) as well as infinite families
111
of complete triangulations such as those described by
112
Burton <xref linkend="bib-burton-phd"/>, <xref linkend="bib-burton-nor7"/>,
113
<xref linkend="bib-burton-satblocks"/>,
114
Martelli and Petronio <xref linkend="bib-italian9"/> and
115
Matveev <xref linkend="bib-matveev6"/>. As a
116
result, ®ina; can frequently recognise the underlying 3-manifolds for
117
well-structured triangulations that it has not previously encountered.
121
<sect3 id="features-trimanipulation">
122
<title>Manipulation</title>
125
You can manipulate a 3-manifold triangulation using the following tools:
128
elementary moves (transformations local to a small
129
number of tetrahedra), such as Pachner moves and other
130
transformations described in <xref linkend="bib-burton-nor7"/>,
131
many of which were suggested by Letscher;
134
automated simplification in which the software attempts to use
135
a combination of these elementary moves to reduce the number of
136
tetrahedra as far as possible, though there is no
137
guarantee that the smallest possible number of tetrahedra will be
141
conversion to a 0-efficient triangulation where possible
142
for closed orientable 3-manifolds <xref linkend="bib-0-efficiency"/>;
145
barycentric subdivision and the truncation of ideal vertices
146
(vertices whose links are neither 2-spheres nor discs);
149
extension of the boundary to convert real boundary components into
153
conversion of a non-orientable triangulation to an orientable
157
cutting along normal surfaces within a triangulation
158
or crushing them to a point, as
159
described <link linkend="features-surfaces">below</link>.
166
<sect2 id="features-census">
167
<title>Census Creation</title>
169
®ina; can be used to form a census of all 3-manifold triangulations
170
satisfying a particular set of census constraints.
171
The command-line tool
172
<link linkend="man-tricensus"><command>tricensus</command></link>
173
is particularly well suited for this task.
176
The census algorithm is heavily optimised; see
177
<xref linkend="bib-burton-facegraphs"/>,
178
<xref linkend="bib-burton-nor10"/> and
179
<xref linkend="bib-burton-genus"/> for details.
180
There is also an &mpi; version that
181
can be distributed across a large number of machines for
182
use on high-performance clusters.
185
®ina; ships with a number of
186
prepackaged censuses, including closed 3-manifold triangulations
187
<xref linkend="bib-burton-nor8"/>, <xref linkend="bib-burton-nor10"/>,
188
<xref linkend="bib-burton-genus"/>, hyperbolic 3-manifolds
189
<xref linkend="bib-cuspedcensus"/>, <xref linkend="bib-closedhypcensus"/>,
190
and knot and link complements (tabulated by Joe Christy).
191
A census lookup facility for arbitrary triangulations is provided.
195
<sect2 id="features-surfaces">
196
<title>Normal Surfaces</title>
198
®ina; is capable of enumerating all vertex normal surfaces or almost
199
normal surfaces<footnote><para>Almost normal surfaces are closely related
200
to normal surfaces and are used by Rubinstein in his 3-sphere recognition
201
algorithm <xref linkend="bib-rubin-3sphere1"/>,
202
<xref linkend="bib-rubin-3sphere2"/>. ®ina; only considers octagonal
203
almost normal discs, and does not consider annular pieces.</para></footnote>
205
an operation required by most high-level topological algorithms that
206
utilise normal surface theory. The underlying enumeration algorithms
207
are highly optimised, and are described in detail in
208
<xref linkend="bib-burton-dd"/>,
209
<xref linkend="bib-burton-convert"/> and
210
<xref linkend="bib-burton-quadoct"/>.
213
This vertex enumeration can be performed in a variety of coordinate
214
systems. For an <replaceable>n</replaceable>-tetrahedron triangulation
215
this includes the 7<replaceable>n</replaceable>
216
standard triangle and quadrilateral coordinates, as well
217
as the smaller set of 3<replaceable>n</replaceable> quadrilateral-only
218
coordinates <xref linkend="bib-quadspace"/>.
219
Likewise, for almost normal surfaces
220
this includes the 10<replaceable>n</replaceable> standard coordinates
221
as well as the 6<replaceable>n</replaceable> quadrilateral-octagon
222
coordinates <xref linkend="bib-burton-quadoct"/>.
226
can be restricted to embedded normal surfaces or can be expanded to
227
include immersed and singular surfaces. Furthermore, elementary support
228
is present for spun normal surfaces, discussed in detail by
229
Tillmann <xref linkend="bib-tillus-spun"/>,
230
which are non-compact surfaces with infinitely many
231
discs found in ideal triangulations.
234
To analyse normal surfaces, you can:
237
view normal surfaces in a variety of coordinate systems,
238
including the standard and quadrilateral-only coordinates
239
discussed above as well as the edge weight coordinates introduced by
243
calculate basic properties of normal surfaces such as
244
Euler characteristic, orientability and one-sidedness;
247
test surfaces for incompressibility, using both exact techniques
248
<xref linkend="bib-jaco-oertel"/> and
249
fast heuristics <xref linkend="bib-weber-seifert"/>;
252
cut along a normal surface and retriangulate, or crush the surface
253
using the techniques of Jaco and Rubinstein
254
<xref linkend="bib-0-efficiency"/>;
257
recognise standard surfaces within a triangulation such
258
as splitting surfaces (described
259
<link linkend="features-splitting">below</link>)
260
and vertex and edge links;
263
test pairs of surfaces for local compatibility (compatible
264
quadrilaterals and/or octagons) and global compatibility (being
265
able to make the surfaces disjoint);
268
filter large lists of normal surfaces by various properties
269
such as Euler characteristic, orientability and boundary.
275
<sect2 id="features-angles">
276
<title>Angle Structures</title>
278
Angle structures, studied originally by Casson and then developed by
279
Lackenby <xref linkend="bib-lackenby-taut"/>,
280
<xref linkend="bib-lackenby-anglestruct"/> and
281
Rivin <xref linkend="bib-rivin-structures"/>,
282
<xref linkend="bib-rivin-combopt"/>,
284
algebraic generalisation of hyperbolic structures. An angle structure
285
on an ideal triangulation is formed by assigning an interior
286
dihedral angle to each edge of every tetrahedron in such a way that
287
a variety of linear equations and inequalities are satisfied.
290
Using similar techniques to normal surface enumeration
291
®ina; can enumerate all vertex angle structures in a triangulation,
292
or all taut structures (for which each dihedral angle is precisely 0
297
<sect2 id="features-splitting">
298
<title>Splitting Surfaces</title>
300
A splitting surface contains precisely one quadrilateral disc within
301
each tetrahedron and no other normal or almost normal discs.
302
These surfaces have some interesting combinatorial and topological
303
properties, described in detail in <xref linkend="bib-burton-phd"/>.
306
®ina; can detect whether splitting surfaces
307
occur within a triangulation. It also provides support for
308
splitting surface signatures, which are compact text-based representations
309
from which splitting surfaces and their enclosing 3-manifold
310
triangulations can be reconstructed. In addition, ®ina; can generate a
311
census of all possible splitting surface signatures of a given size.
315
<sect2 id="features-scripting">
316
<title>Scripting</title>
318
Users can interact with ®ina; at a lower level by writing and
319
running scripts in <ulink url="http://www.python.org/">&python;</ulink>.
320
These scripts are essentially high-level programs with immediate access
321
to the mathematical core of ®ina;, and are ideal for
322
performing repetitive tasks over large sets of data. Such tasks might
323
include performing a sequence of tests upon all triangulations in a
324
census, or testing a prototype for a new algorithm.
325
Scripts can be embedded in ®ina; data files or run from the
326
command line, and custom libraries of
327
routines can be written to share code between files.
331
<sect2 id="features-interfaces">
332
<title>Interfaces</title>
334
The usual method of running ®ina; is through a full
335
point-and-click graphical user interface.
336
Alternatively, for those requiring immediate access to the
337
mathematical core of the software, an interactive command-line interface
338
is available for users to control the program using
339
&python; scripting as described above.
340
Various other specialised command-line utility programs are also available.
343
The mathematical core of ®ina; is provided as a &cpp; library,
344
which means that programmers are able to access its low-level mathematical
345
routines directly from within their own code.
349
<sect2 id="features-docs">
350
<title>Documentation</title>
352
Significant effort has been spent on documentation for this software.
353
A full users' handbook is available for ®ina; (which you are reading now).
354
In addition, the graphical user interface offers extensive assistance
355
through tooltips and "What's This?" texts. Just hit
356
<keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo>
357
and click on any element of the user interface for immediate assistance.
360
For users writing &python; scripts or for &cpp; programmers seeking to
361
modify or extend the software, the full &api; for ®ina;'s
362
mathematical engine is also extensively documented.
363
You can access the &api; documentation by selecting
365
<guimenu>Help</guimenu>
366
<guimenuitem>Python API Reference</guimenuitem>
371
<sect2 id="features-datafiles">
372
<title>Data Files</title>
374
®ina; stores data in a well-organised hierarchical structure,
375
allowing a single data file to contain
376
multiple triangulations, normal surface lists and other topological
377
structures, along with supporting data such as text notes,
378
&python; scripts and &pdf; documents.
379
The file format is based on
380
compressed &xml;, an open and widely-supported text-based data
381
format. International characters are fully supported.
383
<para id="dataformat">
384
Again, this &xml; file format is extensively documented.
387
<guimenu>Help</guimenu>
388
<guimenuitem>File Format Reference</guimenuitem>
added
removed
kdeui/doc/regina/featureset.docbook
