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 *).

       If you have frequently-used code, you can store it in a user library.  At the beginning of
       each  Python  session,  Regina  will automatically run all of the code in all of your user
       libraries.  The list of user libraries will be read from  the  text  file  ~/.regina-libs,
       which  should contain one library filename per line.  Blank lines and lines beginning with
       a hash (#) will be ignored.  You can also configure this list  of  libraries  through  the
       graphical user interface: see the Python options page.

       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  and  loading  any user libraries).  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.

       -n

       --nolibs
              Do not load any user  libraries  when  the  session  starts.   User  libraries  are
              discussed in the overview above.

       -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.NTriangulation, not just NTriangulation.

       -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.sourceforge.net/engine-docs/.

AUTHOR

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

                                          23 August 2014                         REGINA-PYTHON(1)