The main testing platform for PyOP2 is Ubuntu 14.04 64-bit with Python 2.7. Other UNIX-like systems may or may not work. Mac OS X 10.7-10.12 are also known to work.

PyOP2 requires a number of tools and libraries to be available:

• A C compiler (for example gcc or clang), make
• A Fortran compiler (for PETSc)
• MPI
• Blas and Lapack
• Git, Mercurial
• Python version 2.7
• pip and the Python headers

The following dependencies are part of the Python subsystem:

• Cython >= 0.22
• decorator
• numpy >= 1.9.1
• mpi4py >= 1.3.1

PETSc. We require very recent versions of PETSc so you will need to follow the specific instructions given below to install the right version.

• PETSc
• PETSc4py

COFFEE. We require the current master version of COFFEE for which you will need to follow the instructions given below.

Testing dependencies (optional, required to run the tests):

• pytest >= 2.3
• flake8 >= 2.1.0
• gmsh
• triangle

With the exception of the PETSc dependencies, these can be installed using the package management system of your OS, or via pip.

To install dependencies system-wide use sudo pip install ..., to install to a user site use pip install --user .... If you don't want PyOP2 or its dependencies interfering with your existing Python environment, consider creating a virtualenv.

On a Debian-based system (Ubuntu, Mint, etc.) install core packages:

sudo apt-get install -y build-essential python-dev git-core \
  mercurial python-pip libopenmpi-dev openmpi-bin libblas-dev \
  liblapack-dev gfortran

Install dependencies via pip:

sudo pip install "Cython>=0.22" decorator "numpy>=1.6" "mpi4py>=1.3.1"

We recommend using Homebrew as a package manager for the required packages on Mac OS systems. Obtaining a build environment for PyOP2 consists of the following:

1. Install Xcode. For OS X 10.9 (Mavericks) and later this is possible through the App Store. For earlier versions, try https://developer.apple.com/downloads (note that on OS X 10.7 (Lion) you will need to obtain Xcode 4.6 rather than Xcode 5)
2. If you did not install Xcode 5, you will need to additionally install the Xcode command line tools through the downloads section of Xcode's preferences
3. Install homebrew, following the instructions at http://brew.sh

4. Install an MPI library (PyOP2 is tested with openmpi):

   brew install openmpi

5. Install an up-to-date Python via homebrew:

   brew install python

   Note

   Do not follow the instructions to update pip, since they currently result in a broken pip installation (see Homebrew/legacy-homebrew#26900)

6. Install numpy via homebrew:

   brew tap homebrew/python
   brew install numpy

7. Install python dependencies via pip:

   pip install decorator
   pip install cython
   pip install mpi4py
   pip install pytest
   pip install flake8

PyOP2 uses petsc4py, the Python bindings for the PETSc linear algebra library and requires:

• an MPI implementation built with shared libraries
• A suitable very recent PETSc master branch built with shared libraries

The version of PETSc you install must be configured with HDF5 support. This either requires appropriate operating system packages, or else asking PETSc to download and build a compatible HDF5 (instructions below).

If you have a suitable PETSc installed on your system, PETSC_DIR and PETSC_ARCH need to be set for the petsc4py installer to find it.

Then install PETSc via pip :

sudo PETSC_CONFIGURE_OPTIONS="--download-ctetgen --download-triangle --download-chaco --download-hdf5" \
  pip install https://bitbucket.org/mapdes/petsc/get/firedrake.tar.bz2
unset PETSC_DIR
unset PETSC_ARCH

If you built PETSc using pip, PETSC_DIR and PETSC_ARCH should be left unset when building petsc4py.

Install petsc4py via pip:

sudo pip install git+https://bitbucket.org/mapdes/petsc4py.git@firedrake#egg=petsc4py

If you have previously installed and older version of PETSc or petsc4py, pip might tell you that the requirements are already satisfied when running above commands. In that case, use pip install -U --no-deps to upgrade (--no-deps prevents also recursively upgrading any dependencies).

If you do not intend to develop COFFEE, you can simply install it using pip:

sudo pip install git+https://github.com/coneoproject/COFFEE.git

If you do intend to contribute to COFFEE, then clone the repository:

git clone git@github.com:coneoproject/COFFEE.git

COFFEE can be installed from the repository via:

sudo python setup.py install

PyOP2 allows initializing data structures using data stored in HDF5 files. To use this feature you need the optional dependency h5py. This installation should be linked against the same version of the HDF5 library used to build PETSc.

Clone the PyOP2 repository:

git clone git://github.com/OP2/PyOP2.git

PyOP2 uses Cython extension modules, which need to be built in-place when using PyOP2 from the source tree:

python setup.py build_ext --inplace

When running PyOP2 from the source tree, make sure it is on your $PYTHONPATH:

export PYTHONPATH=/path/to/PyOP2:$PYTHONPATH

When installing PyOP2 via python setup.py install the extension modules will be built automatically and amending $PYTHONPATH is not necessary.

To make sure PyOP2 finds all its dependencies, create a file .env e.g. in your PyOP2 root directory and source it via . .env when using PyOP2. Use the template below, adjusting paths and removing definitions as necessary:

#PETSc installation, not necessary when PETSc was installed via pip
export PETSC_DIR=/path/to/petsc 
export PETSC_ARCH=linux-gnu-c-opt

#Add PyOP2 to PYTHONPATH
export PYTHONPATH=/path/to/PyOP2:$PYTHONPATH

Alternatively, package the configuration in an environment module.

PyOP2 unit tests use pytest >= 2.3. Install via package manager:

sudo apt-get install python-pytest

or pip:

sudo pip install "pytest>=2.3"

The code linting test uses flake8. Install via pip:

sudo pip install "flake8>=2.1.0"

If you install pytest and flake8 using pip --user, you should include the binary folder of your local site in your path by adding the following to ~/.bashrc or .env:

# Add pytest binaries to the path
export PATH=${PATH}:${HOME}/.local/bin

If all tests in our test suite pass, you should be good to go:

make test

This will run code linting and unit tests, attempting to run for all backends and skipping those for not available backends.

Start by verifying that PyOP2 picks up the "correct" dependencies, in particular if you have several versions of a Python package installed in different places on the system.

Run pydoc <module> to find out where a module/package is loaded from. To print the module search path, run:

python -c 'from pprint import pprint; import sys; pprint(sys.path)'

Run the tests as follows, to abort after the first failed test:

Start with the unit tests with the sequential backend :

py.test test/unit -vsx --tb=short --backend=sequential