Chapter 10. Troubleshooting and FAQ

10.1. Running Regina
10.1.1. I cannot edit a triangulation. I can view it but I can't change anything.
10.1.2. I cannot open the Regina handbook. I try selecting Regina Handbook from the Help menu but I get an error message.
10.1.3. How do I view PDF packets? I click on the packet but I just see a box with an error message.
10.2. Python Scripting
10.2.1. Regina tells me that Python scripting has been disabled.
10.2.2. While working with a Python object I receive a TypeError with the message "bad argument type for built-in operation". I know the object is valid since I've used it earlier without problems.
10.2.3. While calling a Python function I receive a Boost.Python.ArgumentError with the message "Python argument types did not match C++ signature". I'm fairly sure I'm passing the right arguments.
10.3. Regina on MacOS X
10.3.1. Can I put Regina on my dock?
10.3.2. Whenever I open or save a file, I get strange errors like “Could not find mime type ...”.
10.3.3. The file open/save dialog is ugly, and I cannot read any of the file or directory names.
10.3.4. I cannot view PDF packets. I just see a big empty grey box.
10.4. Miscellaneous
10.4.1. I am having trouble compiling Regina.
10.4.2. What is the test suite, and how do I run it?
10.4.3. 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.

10.1. Running Regina

10.1.1. I cannot edit a triangulation. I can view it but I can't change anything.
10.1.2. I cannot open the Regina handbook. I try selecting Regina Handbook from the Help menu but I get an error message.
10.1.3. How do I view PDF packets? I click on the packet but I just see a box with an error message.

10.1.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 small padlock in the packet tree, as seen with the figure eight knot complement below.

10.1.2.

I cannot open the Regina handbook. I try selecting Regina Handbook from the Help menu but I get an error message.

First, remember that if all else fails you can download the handbook directly from the Regina website (follow the documentation links). You can even read it online.

Otherwise: visit Regina's general options and uncheck the box marked “Open handbook in KDE Help Center”. Regina should now try to open the Regina handbook in your favourite web browser.

If you have done this and the web browser starts but it cannot find index.html, you might have the handbook installed in the wrong location. Please mail us for assistance, so we can try to make it work out of the box for you in a future release.

10.1.3.

How do I view PDF packets? I click on the packet but I just see a box with an error message.

If you use MacOS X, see this question.

If you use GNU/Linux, the easiest solution is to visit Regina's PDF options, switch off the embedded PDF viewer, and set the external PDF viewer to your favourite application (such as Xpdf or Evince). Regina can usually find a suitable viewer automatically, but if your installation is unusual then you may need to provide Regina with the full path to your PDF viewer (such as /usr/local/bin/xpdf).

If you wish to use the embedded PDF viewer, you will need to have Okular installed. Okular should be shipped with your GNU/Linux distrubition; it may be offered as its own package, or it may be part of the kdegraphics bundle.

If you are still having trouble getting PDF support working, please let us know so we can fix the problem in a future release.

10.2. Python Scripting

10.2.1. Regina tells me that Python scripting has been disabled.
10.2.2. While working with a Python object I receive a TypeError with the message "bad argument type for built-in operation". I know the object is valid since I've used it earlier without problems.
10.2.3. While calling a Python function I receive a Boost.Python.ArgumentError with the message "Python argument types did not match C++ signature". I'm fairly sure I'm passing the right arguments.

10.2.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 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.
-----------------------------------------------------------------------------
   * Boost.Python  <http://www.boost.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 for assistance, including your CMakeCache.txt if possible to help diagnose the problem.

10.2.2.

While working with a Python object I receive a TypeError with the message "bad argument type for built-in operation". I know the object is valid since I've used it earlier without problems.

You may have run into an unusual boost.python issue regarding ownership semantics. If you have been using tree insertion routines such as NPacket.insertChildFirst(), NPacket.insertChildLast() or NPacket.insertChildAfter(), this is particularly likely.

See the Python scripting notes for a full discussion of this problem and how to work around it.

10.2.3.

While calling a Python function I receive a Boost.Python.ArgumentError with the message "Python argument types did not match C++ signature". I'm fairly sure I'm passing the right arguments.

You may have run into the same unusual ownership issue with boost.python discussed in the previous question. Again, if you have been using tree insertion routines such as NPacket.insertChildFirst(), NPacket.insertChildLast() or NPacket.insertChildAfter(), this is particularly likely.

See the Python scripting notes for a full discussion of this problem and how to work around it.

On the other hand, you may just be calling a function incorrectly. You might wish to check the API documentation, which describes all of Regina's functions and what arguments they should take.

10.3. Regina on MacOS X

10.3.1. Can I put Regina on my dock?
10.3.2. Whenever I open or save a file, I get strange errors like “Could not find mime type ...”.
10.3.3. The file open/save dialog is ugly, and I cannot read any of the file or directory names.
10.3.4. I cannot view PDF packets. I just see a big empty grey box.

10.3.1.

Can I put Regina on my dock?

Yes you can. Open /sw/opt/kde4/mac/bin/ in the Finder. You should see regina-kde (complete with the brown tetrahedron icon), and you can drag it straight onto your dock.

10.3.2.

Whenever I open or save a file, I get strange errors like “Could not find mime type ...”.

These errors are irritating but harmless. Unfortunately they happen from time to time with all KDE applications on MacOS X, not just Regina. They are easy to get rid of: just run /sw/opt/kde4/mac/bin/kbuildsycoca4 from the command prompt.

example:~> /sw/opt/kde4/mac/bin/kbuildsycoca4
kbuildsycoca4(1476)/kdecore (kdelibs) getBundle: getBundle( "/sw/opt/kde4/mac/lib/kde4/libexec/drkonqi" ,  false ) called
...
... (lots of output)
...
example:~>

This should make the mime type errors stop (at least for now). Hopefully this will be fixed permanently in later releases of KDE 4 on MacOS X.

10.3.3.

The file open/save dialog is ugly, and I cannot read any of the file or directory names.

Again this seems to be an issue across the board with KDE on MacOS X. This is easily fixed: change your file dialog from Short View to Detailed View (in fact anything other than Short View will do).

The result should be a clear and readable file dialog, and KDE will remember your new view type from now on.

10.3.4.

I cannot view PDF packets. I just see a big empty grey box.

At the time of writing, KDE's PDF viewer (Okular) does not work on MacOS X, which means the embedded PDF viewer will not work in Regina.

Visit Regina's PDF settings and make sure the embedded viewer is switched off. This will make Regina use an external PDF viewer instead (which is what you want).

As for which external viewer: you can leave this empty, and Regina will know what to do. Alternatively you can suggest /usr/bin/open, which will tell Regina to use whatever PDF viewer is your default under MacOS X.

10.4. Miscellaneous

10.4.1. I am having trouble compiling Regina.
10.4.2. What is the test suite, and how do I run it?
10.4.3. 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.

10.4.1.

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 cmake options tailored to your specific type of machine.

10.4.2.

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: NBitmaskTest::sizes... ok.
2: NBitmaskTest::firstLastBit... ok.
2: NBitmaskTest::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).

10.4.3.

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 SourceForge services such as the bug tracking system and mailing lists 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.