# Troubleshooting and FAQ

## Running ®ina;

How do I start ®ina;?

If you use &linux;, look for ®ina; 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 ®ina; from the command line by running `regina-gui`.

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

If you use &windows;, you can find ®ina; in the Start menu. Look for All Programs Regina ®version; ®ina; .

How can I run `regina-python` or the other command-line tools?

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

        example$ regina-python
        Regina 7.4
        Software for low-dimensional topology
        Copyright (c) 1999-2025, The Regina development team
        >>>

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

        example$ /Applications/Regina.app/Contents/MacOS/regina-python
        Regina 7.4
        Software for low-dimensional topology
        Copyright (c) 1999-2025, The Regina development team
        >>>

If you use &windows;, the tool `regina-python` is not available. &windows;. However, you can still use &python; scripting in ®ina;'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 ®version;\bin\`.

        example$ "c:\Program Files\Regina\Regina ®version;\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
        ...

## &python; Scripting

®ina; tells me that &python; scripting has been disabled.

This means that whoever built your version of ®ina; did not include &python; support in the build.

The best solution is to download a ready-made package from the ®ina; website. All of the ready-made packages should have &python; support built in.

If you need to build ®ina; yourself from source, make sure you have the &python; development files installed. If not, ®ina; 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 &mailtheauthors; for assistance, including your `CMakeCache.txt` if possible to help diagnose the problem.

&snappy; has stopped working in ®ina;'s graphical &python; consoles. 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; 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 ®ina; authors are currently working to find a suitable workaround.

## Miscellaneous

I am having trouble compiling ®ina;.

If you can, it is best to install ®ina; from a ready-made package. See the ®ina; website for a list of &linux; distributions that have packages available.

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

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, ®ina; ships with a rich test suite. The test suite asks ®ina; to perform different calculations that isolate different portions of its mathematical code, and it verifies that ®ina; gets all the answers correct.

The test suite is split into several sections, including simpler &python; and command-line utilities tests, as well as rich and detailed &cpp; calculation engine tests. The detailed &cpp; test suite is shipped with every full installation of ®ina;, whereas the other parts (&python; and command-line utilities tests) are only available when building ®ina; from source.

If you have a full installation (e.g., you installed one of ®ina;'s binary packages), then you can run the &cpp; test suite by typing `regina-helper test`. If you are building ®ina; from source, you can run all sections of the test suite (&python;, utilities and &cpp; tests) by moving into your main build directory and typing `make test ARGS=-V`.

    example:~/source/regina/build> make test ARGS=-V
    Running tests...
    ...
    ... (some initial output)
    ...
    1: Test command: /home/bab/git/regina/build/engine/testsuite/regina-testsuite
    1: Test timeout computed to be: 10000000
    1: [==========] Running 201 tests from 29 test suites.
    1: [----------] Global test environment set-up.
    1: [----------] 2 tests from AbelianGroupTest
    1: [ RUN      ] AbelianGroupTest.incrementalBuild
    1: [       OK ] AbelianGroupTest.incrementalBuild (0 ms)
    1: [ RUN      ] AbelianGroupTest.tightEncoding
    1: [       OK ] AbelianGroupTest.tightEncoding (0 ms)
    1:
    1: [----------] 6 tests from CoversTest
    1: [ RUN      ] CoversTest.trivial
    1: [       OK ] CoversTest.trivial (7 ms)
    ...
    ... (more output)
    ...
    2: ----------------------------------------------
    2: Test suite for Regina's command-line utilities
    2: ----------------------------------------------
    2:
    2: Running censuslookup.test ... ok
    2: Running regconcat.test (with filter) ... ok
    ...
    ... (more output)
    ...
    3: ---------------------------------------
    3: Test suite for Regina's python bindings
    3: ---------------------------------------
    3:
    3: Running alltypes.test ... ok
    3: Running angles.test ... ok
    ...
    ... (more output)
    ...
    3: Regina calculation engine test suite
    3:
    3: AbelianGroupTest::incrementalBuild... ok.
    3: AngleStructuresTest::empty... ok.
    3: AngleStructuresTest::oneTet... ok.
    ...
    ... (lots and lots of output)
    ...
    4: ----------------------------------------------------------------
    4: Test suite for python bindings with a basic embedded interpreter
    4: ----------------------------------------------------------------
    4:
    4: Running alltypes.test ... ok
    4: Running angles.test ... ok
    ...
    ... (more output)
    ...
    100% tests passed, 0 tests failed out of 4

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

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

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.