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, cen-
       sus enumeration, combinatorial recognition of triangulations, and high-level tasks such as 3-sphere recognition and connected sum  decompo-
       sition.	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 names-
	      pace  (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 internal/	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  com-
	      pile  time).  If you install Regina into one directory but then move it by hand into another, the default REGINA_HOME will be incor-
	      rect.

       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.

	      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  incor-
	      rect.

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/regconcat.

WINDOWS USERS

       The command regina-python is not available under Windows.  However, you can still use Python scripting in Regina's  graphical  user  inter-
       face, 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.

								    28 May 2012 						  REGINA-PYTHON(1)