2. Installation

TuLiP works with Python 3. The Python versions supported are defined as the argument of parameter python_requires, within setup.py. To install with pip from PyPI:

$ pip install tulip

or from source:

$ pip install .

pip installs Python dependencies automatically. They are listed in install_requires within setup.py. The only Python packages that you may want to install yourself, in order to link them properly are:

The following are optional dependencies, listed with a summary of dependent features:

  • Matplotlib – many visualization features

  • Graphviz – to plot graphs, for example discrete state machines

  • CVXOPT – construction and manipulation of discrete abstractions

  • GLPK – fast linear programming solver

_images/tulip_dependencies.svg

For computing discrete abstractions from hybrid system descriptions, it is highly recommended that you install both CVXOPT and GLPK. Note that you need to install GLPK before installing CVXOPT, and follow the CVXOPT installation instructions to link CVXOPT to GLPK. (If you use MacPorts, please note that MacPorts does not do this linking automatically.)

The latest release of TuLiP can be downloaded also from SourceForge.

2.1. Alternative discrete synthesis tools

The default synthesis tool for GR(1) and Rabin(1) specifications is omega (installed by pip).

TuLiP can use other tools for formal synthesis. Those for which an interface is available are listed below. Also consult Specifications concerning relevant syntax and summaries of the specification languages. Generally, direct interfaces are defined as modules in the subpackage tulip.interfaces. However, these tools can be accessed indirectly, by appropriately setting parameters for various functions in TuLiP, such as tulip.synth.synthesize().

These are optional dependencies. TuLiP is useful without having them installed, but certain functionality is only available when they are.

2.1.1. GR(1)

2.1.2. LTL

2.2. Testing your installation

TuLiP is distributed with tests for itself that, like those for NumPy, provide a way to check that TuLiP is behaving as expected. To perform basic tests that should pass on any TuLiP installation, from the command-line try

$ ./run_tests.py

There is an extensive test suite that includes tests involving optional dependencies. To perform it, ./run_tests.py full. It is important to note that some tests may fail because an optional dependency is missing, not because the TuLiP installation itself is flawed. Use the flag “-h” to get a description of driver script options. More details about testing TuLiP oriented for developers are provided in the Developer’s Guide.

2.3. New to Python?

Newcomers to scientific computing with Python should read New to Python?.

If you don’t already use Python for scientific computing, consider using Enthought Python Distribution (EPD) or Enthought Canopy. This may make the installation process easier. The EPD Free and Canopy Express distributions come with Python and includes NumPy, SciPy, matplotlib. EPD Free or Canopy Express together with networkx, cvxopt, and PLY is sufficient to run TuLiP.

Alternatives to Enthought are listed on the SciPy installation webpage. In particular, also try Anaconda.

EPD seems to work fine on most platforms but if you cannot get it to work, more alternative packages for Mac OS X and Microsoft Windows are mentioned below.

2.4. Troubleshooting

Regarding installation of numerical computing packages (NumPy, etc.), for the love of all that is good, please run tests to verify proper behavior! …unless you use a very well established install method. Nonetheless, unit testing is always good practice.

If you think the necessary packages are installed, but are unsure how to debug Python, then consider the following tips. To see the python path, execute:

$ python -c 'import sys; print("\n".join(sys.path))'

Each path searched is listed on a new line. You can augment this list by appending locations (separated by “:”) to the environment variable PYTHONPATH. To see what it’s currently set to, and add a new path to “/home/frodo/work”, use:

$ echo $PYTHONPATH
$ export PYTHONPATH=$PYTHONPATH:/home/frodo/work

You may need to tweak the export statement depending on your terminal shell. All of my examples are tested with zsh (the Z shell).

2.4.1. Mac OS X

For installing SciPy, NumPy, consider trying Scipy Superpack for Mac OSX by Chris Fonnesbeck.

When installing CVXOPT using MacPorts, there are some compatibility issues that cause CVXOPT to fail to install. The following customizations will link numpy against Apple’s implementation of LAPACK and BLAS and bypass this issue:

  • Uninstall atlas (if installed):

    $ sudo port uninstall atlas; sudo port clean atlas

  • Uninstall numpy (if installed):

    $ sudo port uninstall numpy; sudo port clean numpy

  • Install numpy without atlas:

    $ sudo port install py27-numpy -atlas

  • Install cvxopt without atlas or dsdp:

    $ sudo port install py27-cvxopt -atlas -dsdp

Note that if you have packages that rely on numpy (such as scipy), you will have to uninstall and reinstall those packages as well.

2.4.2. Microsoft Windows

For Windows users, type the above commands without “$” in the terminal. For example, check the version of your Python by typing:

python -V

To check whether the packages has been installed, open a new terminal and try:

python
import numpy
import scipy
import cvxopt

If an error message occurs, the package might not be visible on the current path or may not be installed at all. When you cannot find a suitable package of NumPy, SciPy, CVXOPT, and Matplotlib for your system, consider trying Unofficial Windows Binaries for Python Extension Packages by Christoph Gohlke.

The package of gr1c for Windows still cannot be found. But without this package, you can also run most TuLiP functions.

2.4.3. Installing other Python dependencies

The command pip install ... will usually suffice. To get PLY, try:

$ pip install ply

2.4.4. virtualenv and pydoc

If you have installed TuLiP into a virtualenv-built environment, then the documentation may not be visible through pydoc . We describe two solutions here, the first being more general.

$ alias pydoc='python -m pydoc'

If that fails, try to explicitly augment the path used by pydoc with an alias. E.g., suppose your username is “frodo”, you are running Python v2.6, and your virtual environment is called “PY_scratch” under your home directory. Then the appropriate alias is similar to:

$ alias pydoc='PYTHONPATH=$PYTHONPATH:/home/frodo/PY_scratch/lib/python2.6/site-packages/ pydoc'

To set this alias for every new terminal session, add the line to your shell startup script; e.g., ~/.bashrc for bash, or ~/.zshrc for zsh [1]. To test it, try looking at the transys subpackage by entering:

$ pydoc tulip.transys

Footnotes

2.4.5. remote server installation

Instructions for installing tulip and its dependencies from scratch on a Unix server can be found here.