Installation

The requirements for pypfilt are:

These packages and pypfilt can all be installed using pip:

# Install pypfilt without plotting support.
pip install pypfilt
# Install pypfilt with plotting support.
pip install pypfilt[plot]

Note

The above instructions should be sufficient for almost all situations, in which case there is no need to read the rest of this page.

Installing required packages

Binary installation on Linux and OS X

On Linux and OS X, you should be able to install binary versions of the required packages (“wheels”) and avoid lengthy compilation times:

pip install --only-binary :all: 'numpy>=1.8' 'scipy>=0.11' 'h5py>=2.2'
# Optional: install matplotlib to use the pypfilt.plot module.
pip install --only-binary :all: 'matplotlib>=1.5'

This is best done within a virtual environment (see the source installation instructions, below).

Source installation on Linux and OS X

Warning

Installing from source on Windows is effectively impossible, due to the dependencies of h5py.

Note

If you are using Python 3, you will most likely need to substitute “python3” for “python” in all of the package names listed here.

Alternatively, these packages can be manually installed in a Virtual Environment, by using virtualenv. This requires the following development tools:

  • C and Fortran compilers (typically gcc and gfortran).
    • Debian: sudo apt-get install gcc fortran.
    • Red Hat Enterprise Linux and CentOS: sudo yum install gcc gcc-gfortran.
    • Fedora: sudo dnf install gcc gcc-gfortran.
    • OS X: Install Command Line Tools for Xcode (instructions).
  • Python header files.
    • Debian: sudo apt-get install python-dev.
    • Red Hat Enterprise Linux and CentOS: sudo yum install python-devel.
    • Fedora: sudo dnf install python-devel.
    • OS X: brew install python (see why installing a separate version of Python is a good idea).
  • Linear algebra libraries (typically ATLAS and LAPACK, or MKL, or ACML).

Then install virtualenv and the libhdf5 development files:

# For Debian and Debian-based distributions such as Ubuntu.
sudo apt-get install virtualenv libhdf5-dev

# For Red Hat Enterprise Linux and CentOS.
sudo yum install python-virtualenv hdf5-devel

# For Fedora.
sudo dnf install python-virtualenv hdf5-devel

# For OS X.
brew install python homebrew/science/hdf5
pip install virtualenv

Then create a virtual environment (called venv-pypfilt in the following example):

# Create and activate the virtual environment.
virtualenv venv-pypfilt
source venv-pypfilt/bin/activate

# Upgrade pip, setuptools and wheel to the latest versions.
pip install --upgrade pip
pip install --upgrade setuptools wheel

# Install NumPy before SciPy, and Cython before h5py.
pip install 'numpy>=1.8' 'Cython >=0.17'
pip install 'scipy>=0.11'

# Note: may need to identify the directory that contains `include/hdf5.h`.
# For example, for 64-bit Debian and Debian-based distributions:
# export HDF5_DIR=/usr/lib/x86_64-linux-gnu/hdf5/serial
pip install 'h5py>=2.2'

# Optional: install matplotlib to use the pypfilt.plot module.
pip install 'matplotlib>=1.5'

Note

In order to install h5py, you may need to identify the directory that contains include/hdf5.h by defining the HDF5_DIR environment variable (see the comments in the code block above).

You can search for include/hdf5.h by running find -L /usr -name hdf5.h. On Red Hat Enterprise Linux, CentOS, and Fedora, this file is located at /usr/include/hdf5.h and there is no need to define HDF5_DIR. On OS X, this file is located at /usr/local/include/hdf5.h when using Homebrew, and there should be no need to define HDF5_DIR.

Installing pypfilt

Once the required packages have been installed (see instructions, above), you can clone the pypfilt repository and install it in the venv-pypfilt virtual environment:

# Activate the virtual environment.
source venv-pypfilt/bin/activate
# Clone the pypfilt repository.
git clone https://bitbucket.org/robmoss/particle-filter-for-python.git
# Install pypfilt in the virtual environment.
cd particle-filter-for-python
python setup.py install

If you are not using a virtual environment, and you don’t have permission to install pypfilt system-wide, you can install the package locally:

# Clone the pypfilt repository.
git clone https://bitbucket.org/robmoss/particle-filter-for-python.git
# Install pypfilt in the user's "site-packages" directory.
cd particle-filter-for-python
python setup.py install --user

Building the documentation

If you want to build the documentation locally, you will need to install Sphinx 1.3 or newer, and the Read the Docs Sphinx Theme.

These can be installed through a package manager:

# For Debian and Debian-based distributions such as Ubuntu.
sudo apt-get install python-sphinx python-sphinx-rtd-theme

# For Red Hat Enterprise Linux and CentOS.
sudo yum install python-sphinx python-sphinx_rtd_theme

# For Fedora.
sudo dnf install python-sphinx python-sphinx_rtd_theme

# For OS X.
brew install sphinx
pip install sphinx_rtd_theme

Alternatively, they can be installed in the venv-pypfilt virtual environment:

# Activate the virtual environment.
source venv-pypfilt/bin/activate
pip install 'Sphinx>=1.3' sphinx_rtd_theme

You can then build the documentation from the pypfilt repository, which will be written to the doc/build/html directory:

python setup.py build_sphinx