The Regina Handbook

Benjamin Burton

Revision 5.1 (2016-12-19)

Both Regina and this handbook are licensed under the terms of the GNU General Public License.

Regina is a software package for 3-manifold and 4-manifold topologists, with a focus on triangulations, normal surfaces and angle structures. For 3-manifolds, it includes high-level tasks such as 3-sphere recognition, connected sum decomposition and Hakenness testing, comes with a rich database of census manifolds, and incorporates the SnapPea kernel for working with hyperbolic manifolds. For 4-manifolds, it offers a range of combinatorial and algebraic tools, plus support for normal hypersurfaces. Regina comes with a full graphical user interface, as well as Python bindings and a low-level C++ programming interface.

This handbook is current as of Regina 5.1.

Tip: You can also browse the alphabetical index of tasks.

Table of Contents

1. Introduction
Getting Started
What does Regina do?
3-Manifold Triangulations
4-Manifold Triangulations
Higher Dimensions
Census Creation and Lookup
Normal Surfaces and Hypersurfaces
Angle Structures
Splitting Surfaces
Data Files
Citing Regina
Who is Regina?
2. Working with Packets
The Packet Tree
Uneditable Packets
Different Packet Types
Container Packets
2-Manifold Triangulations
3-Manifold Triangulations
SnapPea Triangulations
4-Manifold Triangulations
Higher-Dimensional Triangulations
Normal Surface Lists
Normal Hypersurface Lists
Angle Structure Lists
Surface Filters
Text Packets
Script Packets
PDF Documents
General Operations on Packets
Creating New Packets
Cloning Packets
Renaming Packets
Deleting Packets and Subtrees
Moving Around the Tree
3. Triangulations
New Triangulations
Importing Triangulations
Creating a Census
Identifying the Manifold (2-D and 3-D)
Validity, Orientability and Other Basic Properties (All Dimensions)
Viewing Facet Gluings (All Dimensions)
Skeletal Information (All Dimensions)
Algebraic Invariants (3-D and 4-D)
Combinatorial Composition (3-D)
High-Level Recognition Routines (3-D)
SnapPea Calculations (3-D)
Decomposition (All Dimensions)
Triangulating Vertex Links (3-D and 4-D)
Triangulating Boundary Components (4-D)
Editing Gluings (All Dimensions)
Automatic Simplification (3-D and 4-D)
Manual Simplification: Elementary Moves (3-D and 4-D)
0-Efficiency (3-D)
Switching Between Real and Ideal (3-D and 4-D)
Subdivision (All Dimensions)
Orienting Triangulations and Double Covers (All Dimensions)
Puncturing and Drilling (3-D)
Building Connected Sums (3-D)
Cutting Along and Crushing Normal Surfaces (3-D)
4. SnapPea Triangulations
Converting from a Regina Triangulation
New SnapPea Triangulations
Importing Triangulations
Analysis and Modification
Volume, Solution Type and Other Basic Properties
Cusps, Fillings and Tetrahedron Shapes
Homology and Fundamental Group
Exporting to Other Formats
5. Normal Surfaces and Hypersurfaces
Enumerating Normal Surfaces and Hypersurfaces
Summary of (Hyper)surfaces
Details of Individual (Hyper)surfaces
Original Matching Equations
Compatibility Between (Hyper)surfaces
Crushing and Cutting
Triangulating Hypersurfaces
Filtering Surfaces (3-D)
Creating Filters
Filtering by Surface Properties
Combining Several Filters
6. Angle Structures
Strict Angle Structures
Enumerating Angle Structures
Details of Individual Angle Structures
7. Importing and Exporting Data
Regina Data Files
SnapPea Triangulations
Orb / Casson Triangulations
Isomorphism Signature Lists
Dehydrated Triangulation Lists
PDF Documents
Python Scripts
Regina Data Files
SnapPea Triangulations
3-Manifold Recogniser Triangulations
C++ Source Code
Spreadsheet-Readable (CSV) Surface Lists
PDF Documents
Python Scripts
8. Python Scripting
Starting a Python Session
Graphical Python Consoles
Command-Line Sessions
Script Packets
Accessing Regina from Python
Caveats and Traps
Uneditable Packets
International and Special Characters
Talking with SnapPy
Sample Python Sessions
Working with a triangulation
Working with a packet tree
Reporting progress of long operations
9. Configuration
General Options
Python Options
Tools Options
10. Compiling Regina Into Your Projects
Installing the Development Files
Compiler and Linker Flags
API Documentation
11. Troubleshooting and FAQ
12. Bug Tracking and Feature Requests
A. Command Line: Main Applications
regina-gui - Regina's graphical user interface
regina-python - Regina's command-line Python interface
B. Command Line: Specialised Utilities
censuslookup - Search for triangulations in Regina's census databases
regconcat - Combine several Regina data files
regconvert - Convert between different Regina file formats
regfiledump - Dump the contents of a Regina data file
regfiletype - Identify the formats of Regina data files
sigcensus - Form a census of splitting surface signatures
tricensus - Form a census of triangulations
tricensus-mpi - Distribute a triangulation census amongst several machines using MPI
tricensus-mpi-status - Summarise the log file of an MPI census of triangulations
trisetcmp - Compare triangulations between two Regina data files
C. Version History
D. Authors and License
License Details
Copying and Modification
External Software