regina-python

REGINA-PYTHON(1)              The Regina Handbook             REGINA-PYTHON(1)



NAME
       regina-python - Regina's command-line Python interface

SYNOPSIS
       regina-python [ -q, --quiet | -v, --verbose ] [ -n, --nolibs ] [ -a,
       --noautoimport ]


       regina-python [ -q, --quiet | -v, --verbose ] [ -n, --nolibs ] [ -a,
       --noautoimport ] [ -i, --interactive ] script [ script-args ]


DESCRIPTION
       Regina is a software package for studying 3-manifold triangulations and
       normal surfaces.  Other key features include angle structures, census
       enumeration, combinatorial recognition of triangulations, and high-
       level tasks such as 3-sphere recognition and connected sum
       decomposition.  Regina comes with a full graphical user interface, and
       also offers Python bindings and a low-level C++ programming interface.

       This command starts an interactive Python session for Regina.  This
       will be a command-line Python session, with direct text input/output
       and no graphical user interface.  All of the objects, clases and
       methods from Regina's mathematical engine will be made available
       through the module regina, which will be imported on startup
       (effectively running import regina).  Moreover, unless the option
       --noautoimport is passed, all of Regina's objects, classes and methods
       will be imported directly into the current namespace (effectively
       running from regina import *).

       Instead of starting an interactive Python session, you can pass a
       Python script (with arguments if desired).  In this case Regina will
       run the script (after first importing the regina module).  If you pass
       --interactive, Regina will leave you at a Python prompt once the script
       finishes; otherwise it will exit Python and return you to the command
       line.

OPTIONS
       -q

       --quiet
              Start in quiet mode.  No output will be produced except for
              serious errors.  In particular, warnings will be suppressed.

              This is equivalent to setting the environment variable
              REGINA_VERBOSITY=0.

       -v

       --verbose
              Start in verbose mode.  Additional diagnostic information will
              be output.

              This is equivalent to setting the environment variable
              REGINA_VERBOSITY=2.

       -a

       --noautoimport
              Still import the regina module, but do not automatically import
              all of Regina's objects, classes and methods into the current
              namespace (that is, do not run from regina import *).  This
              means that (for example) the main 3-manifold triangulation class
              must be accessed as regina.Triangulation3, not just
              Triangulation3.

       -i

       --interactive
              Run the script in interactive mode.  After executing the given
              script, Regina will leave you in the Python interpreter to run
              your own additional commands.

              This option is only available when a script is passed.  If no
              script is passed, regina-python will always start in interactive
              mode.

ENVIRONMENT VARIABLES
       The following environment variables influence the behaviour of this
       program.  Each variable can also be set in the local configuration file
       ~/.regina-python using a line of the form option=value.  Environment
       variables will take precedence over values in the configuration file.

       REGINA_VERBOSITY
              Specifies how much output should be generated.  Recognised
              values are:

              0      Display errors only; this is equivalent to passing the
                     option --quiet.

              1      Display errors and warnings; this is the default.

              2      Display errors, warnings and diagnostic output; this is
                     equivalent to passing the option --verbose.

       REGINA_PYTHON
              The command used to start the Python interpreter.  By default,
              Regina tries to run the same version of Python that it was built
              against.

              In general you should use the same version of Python that Regina
              was built against; otherwise Python might not be able to load
              the regina module.

              In normal situations you should never need to set this option
              yourself.

       REGINA_HOME
              The directory in which Regina's data files are installed.  This
              should be the directory containing the icons/ subdirectory, the
              examples/ subdirectory and so on.

              If you are running Regina directly out of the source tree, this
              defaults to the top-level source directory.  If you are running
              Regina from a proper installation, this defaults to the
              corresponding installation directory.

              In normal situations you should never need to set this option
              yourself.

              Warning: When running from a proper installation, the default
              REGINA_HOME is hard-wired into the startup script (it is set at
              compile time).  If you install Regina into one directory but
              then move it by hand into another, the default REGINA_HOME will
              be incorrect.

       REGINA_PYLIBDIR
              The directory containing the Python module regina.so.

              If you are running Regina directly out of the source tree, this
              defaults to a directory within this source tree.  If you are
              running Regina from a proper installation, this defaults to the
              corresponding installation directory.

              If you have installed Regina's Python module in a standard
              Python location (i.e., Python can import it directly without
              extending sys.path), then REGINA_PYLIBDIR should be left empty
              or undefined.

              In normal situations you should never need to set this option
              yourself.

              Warning: Like REGINA_HOME, when running from a proper
              installation the default REGINA_PYLIBDIR is hard-wired into the
              startup script.  If you install Regina into one directory but
              then move it by hand into another, the default REGINA_PYLIBDIR
              will be incorrect.

MACOS X USERS
       If you downloaded a drag-and-drop app bundle, this utility is shipped
       inside it.  If you dragged Regina to the main Applications folder, you
       can run it as /Applications/Regina.app/Contents/MacOS/regina-python.

WINDOWS USERS
       The command regina-python is not available under Windows.  However, you
       can still use Python scripting in Regina's graphical user interface, by
       opening a graphical Python console or using script packets.

SEE ALSO
       regina-gui.

       Regina comes with thorough API documentation, which describes in detail
       all of the objects, classes and methods that Regina makes available to
       Python.  You can access this documentation via Help->Python API
       Reference in the graphical user interface, or read it online at
       http://regina-normal.github.io/engine-docs/.

AUTHOR
       Many people have been involved in the development of Regina; see the
       users' handbook for a full list of credits.



                               14 December 2016               REGINA-PYTHON(1)