Using Regina - various ways

The Regina software has various ways in which you can interact with it.  This can lead to some confusion as to precisely what it can do and how a person can get it to do those things.  I'll outline here the primary ways of interacting with Regina, assuming you are familiar with mathematics and using software on your computer.  I'll also assume you know a little bit about programming but are not familiar with the languages used in Regina. 

1) You can use Regina as a complete black box tool.  Download the GUI here, and you can get started provided you have one of the operating systems we currently build for.  At present this means most standard flavours of Linux, Windows, plus desktop Mac products.  The main source of help in using Regina is the handbook and the API documentation.  The GUI also has a built-in help system that works slightly differently in different operating systems.   Hovering over a button will typically give you a brief description of what it does.  Also on the "Help" dialogue there is a "What's this?" button.  Click on what you are interested in and you will get further details. 

The handbook gives documentation for all the executables you will receive in your download from the "Regina Download Page".  The handbook focuses on how to use the GUI, but it does give brief descriptions of the other executables, even how to use Regina as a library in your C++ or Python code (see the bottom of the documentation).  If you want to use the GUI to access any information that isn't available in a dialogue box, what you will have to do is invoke the Python (a programming language) interface.  For this you will want to start with the Python Scripting part of the handbook.  This gives you a sense for how to start interacting with Regina via Python. 

Keep in mind that Python is basically a middle-man between you and Regina, which at its core is largely a C++ (another programming language) program.  So some features of Regina are implemented in Python, and some are not.  The reason for this is mainly that it takes time to build Python interfaces for C++ code and some of the authors (like, say, myself) are not particularly good at this.  But once you start using Python to interact with Regina, you will soon want to know the answer to the question: what can I do now?  That is answered by the API documentation.  API stands for Application Programming Interface and is perhaps not the best choice of name on our part.  The API documentation is documentation that is automatically generated from our C++ code.  So you should view this documentation as the source-code documentation, but reformatted to be more pleasant to look at. 

The API documentation tells you what parts of Regina have Python interfaces, and which do not.  Specifically, look at the NGenericIsomorphism page.  At the bottom it states clearly that this object is not available in Python.  Generally that's how it works.  If we don't comment, you can assume it is implemented.  If we do comment, it tends to only be in the negative.  If you encounter something else, please let me know.  

2) If you find the GUI too clunky and would prefer to interact with Regina directly through Python, one can do that too.  My impression is this is the most popular way to interact with Regina among people who are not actively developing Regina (and even among some who are developers... just not me).  Ben gives good examples of how one does this (interactively) here.  But one does not need to use Python interactively.  Alternatively, one could write a Regina-Python script and ask Python to "run" it.   I find this much easier to do than using the interactive Python interface.  The two processes are very similar. For example, here is how one would ask Regina to find all the knots in the knot tables that fiber. Create a script file fiber.py with the contents:

#!/usr/local/bin/regina-python
## I'm assuming you are using Linux or a Mac here, regina-python is at present
## not available for Windows.  /Applications/Regina.app/Contents/MacOS/regina-python
## is the Mac installation location. 
from regina import *
import sys
 
## this program will try to show that a list of 3-manifolds fibers over the
## circle.  Below we will use the knot and link census, please change to 
## whichever fully-qualified directory your installation puts 
## knot-link-census.rga, or any other 3-manifold list you are interested in.
filename = "/usr/local/share/regina/examples/knot-link-census.rga"
 
dat = readFileMagic(filename)
if dat == None:
    print 'ERROR: Could not read ' + filename
    sys.exit(1)
 
print 'Searching for manifolds that fiber over the circle in: ' + filename
print
## we will use the Stallings criterion, so we attempt to write the fundamental
## group as a semi-direct product of Z with a finitely-presented group. 
 
p = dat
while p != None:
    if p.getPacketType() == NTriangulation.packetType:
        ## I want to single out the knot exteriors to simplify the search
        if p.getHomologyH1().str() == 'Z':
            g = p.getFundamentalGroup()
            g.intelligentSimplify()
            s = g.recogniseGroup()
            ## the string s describes the monodromy of the group extension
            ## but let's not output that, we will split it off.
            sc = s.split(' ')[0]
            if s.find("Z~") >= 0:
                print p.getFullName() + " fibers since the group is " + sc
            ## we could check the Alexander polynomial at this stage to try
            ## and confirm the knot does not fiber, but that module is in the
            ## NCellularData class, which (as of September 2014) is not
            ## part of the main Regina distribution yet.
    p = p.nextTreePacket()
    ## done!
print "The other manifolds perhaps do not fiber, but we have not verified this."
 
You will need to make the above file executable (chmod u+x) and then you can execute it directly from the command line.  If you run the program and compare against the known list of fibered knots, you'll see the above code does not find all the fibered knots.  Since we're using the Stallings test, we're working with group presentations.  As group presentations are largely things that can not be dealt with algorithmically (which includes finding semi-direct product decompositions) the code is bound to only give partial results.  When it does find the extension, it tells you.  When it does not, it does not tell you anything. I will slowly populate this thread with example Python and C++ Regina scripts for people to see how one makes Regina work. 
 

3) Lastly, one can do what I usually do.  Write directly in C++.  This has the advantage that essentially every feature of Regina is at your fingertips.  It also allows you to use the development versions of Regina, where some extensions of Regina are in development.  The stable version of Regina is available from the download site.  The developmental versions of Regina are all present at the GIT repository. The GIT repository code tends to be more in flux, and sometimes contains buggy code.  So user beware.   Usually the author of the code is aware of its limitations, so if you are interested, do contact the relevant author.  

 

#!/usr/local/bin/regina-python
from regina import *
import sys
filename = "/usr/local/share/regina/examples/knot-link-census.rga"
dat = readFileMagic(filename)
if dat == None:
    print 'ERROR: Could not read ' + filename
    sys.exit(1)
print 'Searching for manifolds that fiber over the circle in: ' + filename
print
p = dat
while p != None:
    if p.getPacketType() == NTriangulation.packetType:
        if p.getHomologyH1().str() == 'Z':
            g = p.getFundamentalGroup()
            g.intelligentSimplify()
            s = g.recogniseGroup()
            sc = s.split(' ')[0]
            if s.find("Z~") >= 0:
                print p.getFullName() + " fibers since the group is " + sc
    p = p.nextTreePacket()
print "The other manifolds perhaps do not fiber, but we have not verified this."