# Troubleshooting and FAQ

## Chapter 11. Troubleshooting and FAQ

11.1. Running Regina
  11.1.1. How do I start Regina?
  11.1.2. How can I run regina-python or the other command-line tools?
  11.1.3. On MacOS, do I need Fink any more?
11.2. The User Interface
  11.2.1. On Ubuntu, none of the keyboard shortcuts work.
  11.2.2. On Ubuntu, the “What’s this?” help just gives me an empty yellow box.
  11.2.3. On Ubuntu, I sometimes receive a crash report when I exit Regina.
11.3. Python Scripting
  11.3.1. Regina tells me that Python scripting has been disabled.
  11.3.2. Python scripting does not work on MacOS. Instead I get a TypeError saying “No Python class registered for C++ class regina::Packet”, and/or a message that Regina “could not set the root variable”.
  11.3.3. SnapPy has stopped working in the graphical user interface. When I import SnapPy and try to create a manifold, I receive a TypeError with the message “isinstance() arg 2 must be a class, type, or tuple of classes and types”.
11.4. Miscellaneous
  11.4.1. I cannot edit a triangulation. I can view it but I can't change anything.
  11.4.2. I am having trouble compiling Regina.
  11.4.3. What is the test suite, and how do I run it?
  11.4.4. Something else not described in this list has gone wrong.

### 11.1. Running Regina

11.1.1. How do I start Regina?
11.1.2. How can I run regina-python or the other command-line tools?
11.1.3. On MacOS, do I need Fink any more?

11.1.1. | How do I start Regina?

If you use GNU/Linux, look for Regina in your applications menu (for instance, the main GNOME or KDE menu). It might be classified under Science or Education. If all else fails, you can always start Regina from the command line by running regina-gui.

If you use MacOS, you should have downloaded a drag-and-drop app bundle. You can start Regina simply by opening this app from wherever you dragged it to (typically the Applications folder).

If you use Windows, you can find Regina in the Start menu. Look for All Programs→Regina 5.1→Regina.

11.1.2. | How can I run regina-python or the other command-line tools?

If you downloaded a GNU/Linux package, these tools should all be in `/usr/bin/`. You can run them directly from the command line:

        example$ regina-python
        Regina 4.95
        Software for 3-manifold topology and normal surface theory
        Copyright (c) 1999-2013, The Regina development team
        >>>

If you downloaded a drag-and-drop app bundle for MacOS, these tools are all shipped inside it. If you dragged Regina to the main Applications folder, you can find them in `/Applications/Regina.app/Contents/MacOS/`.

        example$ /Applications/Regina.app/Contents/MacOS/regina-python
        Regina 4.95
        Software for 3-manifold topology and normal surface theory
        Copyright (c) 1999-2013, The Regina development team
        >>>

If you use Windows, the tool regina-python is not available. Windows. However, you can still use Python scripting in Regina's graphical user interface, by opening a graphical Python console or using script packets.

The other command-line tools (such as regfiledump, tricensus and so on) are installed under Windows beneath the `Program Files` directory; on some machines this directory is called `Program Files (x86)`. Specifically, the command-line tools are stored in the subdirectory `c:\Program Files\Regina\Regina 5.1\bin\`.

        example$ "c:\Program Files\Regina\Regina 5.1\bin\tricensus.exe" -t2 output.rga
        Starting census generation...
        0:1 0:0 1:0 1:1 | 0:2 0:3 1:3 1:2
        0:1 0:0 1:0 1:1 | 0:2 0:3 bdry bdry
        ...

11.1.3. | On MacOS, do I need Fink any more?
| No! As of version 4.92, Regina ships as a standalone app bundle that you can drag and drop straight into your Applications folder. If you installed Fink for an earlier version of Regina and you do not use it for anything else, you can remove it: simply delete `/sw` and everything beneath it.

### 11.2. The User Interface

11.2.1. On Ubuntu, none of the keyboard shortcuts work.
11.2.2. On Ubuntu, the “What’s this?” help just gives me an empty yellow box.
11.2.3. On Ubuntu, I sometimes receive a crash report when I exit Regina.

11.2.1. | On Ubuntu, none of the keyboard shortcuts work.

This is due to a larger bug in Ubuntu that affects not just Regina but all programs that use the Qt libraries. It is not clear if/when Ubuntu will fix this problem.

In the meantime, if it bothers you greatly then you can try uninstalling the `appmenu-qt5` package. This will fix the keyboard shortcuts, but at a cost: all Qt-based applications will lose the unified menu bar at the top of the screen, and instead will put their menus inside their own windows.

11.2.2. | On Ubuntu, the “What’s this?” help just gives me an empty yellow box.
| If you look closely, you might see that the box is full of white text on a bright yellow background (which of course is impossible to read). Unfortunately this is another long-standing bug in Ubuntu, which affects not only Regina but all Qt-based applications. It is not clear how Regina can work around this problem; hopefully Ubuntu will fix this issue soon.
11.2.3. | On Ubuntu, I sometimes receive a crash report when I exit Regina.

The problem itself is harmless (but annoying), and you can simply ignore it. Any tasks you asked Regina to perform (such as saving your data files) will still be completed successfully.

It is not clear if/how this problem can be fixed, since it seems to be a wider problem with the Qt toolkit (in particular, the version of Qt that ships with some recent versions of Ubuntu).

This most likely affects other GNU/Linux distributions as well; you will simply notice it on Ubuntu because Ubuntu comes with a crash handler that notifies the user of such events. In other distributions the problem is invisible (and harmless) because the crash only occurs when you are exiting Regina anyway.

### 11.3. Python Scripting

11.3.1. Regina tells me that Python scripting has been disabled.
11.3.2. Python scripting does not work on MacOS. Instead I get a TypeError saying “No Python class registered for C++ class regina::Packet”, and/or a message that Regina “could not set the root variable”.
11.3.3. SnapPy has stopped working in the graphical user interface. When I import SnapPy and try to create a manifold, I receive a TypeError with the message “isinstance() arg 2 must be a class, type, or tuple of classes and types”.

11.3.1. | Regina tells me that Python scripting has been disabled.

This means that whoever built your version of Regina did not include Python support in the build.

The best solution is to download a ready-made package from the Regina website. All of the ready-made packages should have Python support built in.

If you need to build Regina yourself from source, make sure you have the Python and boost.python development files installed. If not, Regina will warn you about this when you run cmake:

    example:~/source/regina/build> cmake ..
    -- The C compiler identification is GNU
    -- The CXX compiler identification is GNU
    ...
    ... (lots of output)
    ...
    -----------------------------------------------------------------------------
    -- The following OPTIONAL packages could NOT be located on your system.
    -- Consider installing them to enable more features from this software.
    -----------------------------------------------------------------------------
       * Python development  <http://www.python.org/>
         Build Python bindings for Regina

    -----------------------------------------------------------------------------

    -- Configuring done
    -- Generating done
    -- Build files have been written to: /Users/bab/source/regina/build
    example:~/source/regina/build>

If you are stuck, please mail the authors for assistance, including your `CMakeCache.txt` if possible to help diagnose the problem.

11.3.2. | Python scripting does not work on MacOS. Instead I get a `TypeError` saying “No Python class registered for C++ class `regina::Packet`”, and/or a message that Regina “could not set the root variable”.

If you have a second, hand-built version of Regina installed on your system, then this can conflict with the standalone app that you download from Regina's website.

Look for a second copy of Regina's Python module on your system. It will be a directory called `regina`, containing the files `engine.so` and `__init__.py`. On a modern MacOS system using the standard system Python, a hand-built version of Regina will typically install this module in `/Library/Python/2.7/site-packages/regina`.

The next release of Regina (version 5.1) will allow two such installations to work happily side-by-side. In the meantime, you can fix the problem by manually removing the hand-built Python module that you found.

11.3.3. | SnapPy has stopped working in the graphical user interface. When I import SnapPy and try to create a manifold, I receive a `TypeError` with the message “isinstance() arg 2 must be a class, type, or tuple of classes and types”.

At the time of writing, SnapPy (version 2.4) is not compatible with multiple interpreters. If you run the graphical user interface and import the `snappy` module in more than one Python console, SnapPy will stop working.

A workaround is to open one console, import `snappy` within it, and then leave that console open. You can then use SnapPy in as many different consoles as you like: SnapPy will only break after you close that first console.

If you are not working directly with a data file, another option is to use the regina-python command-line tool. This only runs one instance of Python, and so avoids the problem.

The problem appears to be rooted in Cython, which SnapPy uses for its Python bindings. The SnapPy and Regina authors are currently working to find a suitable workaround.

### 11.4. Miscellaneous

11.4.1. I cannot edit a triangulation. I can view it but I can't change anything.
11.4.2. I am having trouble compiling Regina.
11.4.3. What is the test suite, and how do I run it?
11.4.4. Something else not described in this list has gone wrong.

11.4.1. | I cannot edit a triangulation. I can view it but I can't change anything.

If a triangulation has any normal surface lists or angle structure lists beneath it, that triangulation must not change. This is because normal surfaces and angle structures store their coordinates relative to the triangulation, and any changes to the triangulation will invalidate these coordinates.

If you wish to modify the triangulation, try cloning it (not the subtree, just the triangulation itself). Then you can edit the clone instead.

Triangulations that cannot be edited will be marked with a padlock in the triangulation viewer, as illustrated below.

11.4.2. | I am having trouble compiling Regina.

If you can, it is best to install Regina from a ready-made package. See the Regina website for a list of GNU/Linux distributions that have packages available.

If you do need to build Regina yourself, the website offers help on building Regina from source. There is also a page on building Regina on different distributions, which suggests specific cmake options tailored to your particular type of machine.

11.4.3. | What is the test suite, and how do I run it?

Sometimes building an application on different hardware or against different versions of libraries can produce unforseen bugs that do not appear on the developer's machine(s). To help guard against such problems, Regina ships with a rich test suite. The test suite asks Regina to perform different calculations that isolate different portions of its mathematical code, and it verifies that Regina gets all the answers correct.

You can only run the test suite if you are building Regina from source yourself. If you download a ready-made package, the person who built the package should have already verified that Regina passes the test suite (as all of the packages on the Regina website do).

You will also need CppUnit installed. Otherwise the test suite will run but only with the simpler Python tests, not the rich and detailed C++ calculation engine tests.

To run the test suite, move into your main build directory and type `make test ARGS=-V`. You should see the individual tests being run, as illustrated below.

    example:~/source/regina/build> make test ARGS=-V
    Running tests...
    ...
    ... (some initial output)
    ...
    1: ---------------------------------------
    1: Test suite for Regina's python bindings
    1: ---------------------------------------
    1:
    1: Running euler.test ... ok
    1: Running file.test ... ok
    ...
    ... (more output)
    ...
    2: Regina calculation engine test suite
    2:
    2: BitmaskTest::sizes... ok.
    2: BitmaskTest::firstLastBit... ok.
    2: BitmaskTest::truncate... ok.
    ...
    ... (lots and lots of output)
    ...
    100% tests passed, 0 tests failed out of 2

    Total Test time (real) =  19.48 sec
    example:~/source/regina/build>

We see from the output above that Regina passed all of its tests (and hopefully this is what you will see too).

11.4.4. | Something else not described in this list has gone wrong.

Perhaps something crashed. Maybe the program gave the wrong answer. Or it could be just a little too slow?

Please! - mail the authors and let us know. You are welcome to write to us directly (our email addresses are here). Or even better, use the GitHub issue tracking system so that the problem you report is publicly archived.

This program is permanently in development. There is a very long TODO list, and chances are your problem is on it. And then again chances are it's not. So please, let us know what you think can be fixed or improved.