Installation

The simplest way to install the most recent release of SPORCO from PyPI is

pip install sporco

SPORCO can also be installed from source, either from the development version from GitHub, or from a release source package downloaded from PyPI.

To install the development version from GitHub, either do

pip install git+https://github.com/bwohlberg/sporco

or

git clone https://github.com/bwohlberg/sporco.git

followed by

cd sporco
python setup.py build
python setup.py test
python setup.py install

Please report any test failures. The install command will usually have to be performed with root permissions, e.g. on Ubuntu Linux

sudo -H pip install sporco

or

sudo python setup.py install

The procedure for installing from a source package downloaded from PyPI is similar.

SPORCO can also be installed as a conda package from the conda-forge channel

conda install -c conda-forge sporco

A summary of the most significant changes between SPORCO releases can be found in the CHANGES.rst file. It is strongly recommended to consult this summary when updating from a previous version.

Requirements

The primary requirements are Python itself, and modules future, numpy, scipy, imageio, pyfftw, and matplotlib. Installation of these requirements is system dependent:

Under Ubuntu Linux 18.04, the following commands should be sufficient for Python 2

sudo apt-get -y install python-numpy python-scipy python-numexpr python-matplotlib \
                        python-imageio python-pip python-future libfftw3-dev python-pytest
sudo -H pip install pyfftw pytest-runner

or Python 3

sudo apt-get -y install python3-numpy python3-scipy python3-numexpr python3-matplotlib \
                        python3-imageio python3-pip python3-future libfftw3-dev python3-pytest
sudo -H pip3 install pyfftw pytest-runner

Some additional dependencies are required for building the documentation from the package source, for which Python 3.3 or later is required. For example, under Ubuntu Linux 18.04, the following commands should be sufficient

sudo apt-get -y install python3-sphinx python3-numpydoc python3-pygraphviz pandoc
sudo -H pip3 install sphinxcontrib-bibtex sphinx_tabs sphinx_fontawesome jonga \
                     jupyter git+https://github.com/leonardt/py2nb#egg=py2nb

The first step is to install Python 2.7

brew install python

or the current version of Python 3.x

brew install python3

The FFTW library is also required

brew install fftw

The Python modules required by SPORCO can be installed using pip

pip install numpy scipy imageio matplotlib pyfftw
pip install six future python-dateutil pyparsing cycler
pip install pytz pytest pytest-runner

(For Python 3, replace pip above with pip3.)

Some additional dependencies are required for building the documentation from the package source, for which Python 3 is required

brew install graphviz
pip3 install sphinx numpydoc sphinxcontrib-bibtex sphinx_tabs
pip3 install sphinx_fontawesome jonga

A version of Python that includes NumPy and SciPy is required. The instructions given here are for installing a reference version from python.org, but a potentially simpler alternative would be to install one of the Windows versions of Python distributed with the SciPy stack that are listed at scipy.org.

The first step is to install Python itself, e.g. for version 3.6.2, download python-3.6.2-amd64.exe and run the graphical installer. The easiest way of installing the main required packages is to download the binaries from the list of Unofficial Windows Binaries for Python Extension Packages. At the time of writing this documentation, the current versions of these binaries for each main package are

After downloading and saving each of these binaries, open a Command Prompt, change directory to the folder in which the binaries were saved, and enter

pip install numpy-1.13.1+mkl-cp36-cp36m-win_amd64.whl
pip install scipy-0.19.1-cp36-cp36m-win_amd64.whl
pip install matplotlib-2.0.2-cp36-cp36m-win_amd64.whl
pip install pyFFTW-0.10.4-cp36-cp36m-win_amd64.whl
pip install future imageio

Some additional dependencies are required for building the documentation from the package source

pip install sphinx numpydoc sphinxcontrib-bibtex sphinx_tabs
pip install sphinx_fontawesome

It is also necessary to download and install Graphviz and then set the Windows PATH environment variable to include the dot command, e.g. to do this on the command line, for the current version of Graphviz

set PATH=%PATH%;"C:\Program Files (x86)\Graphviz2.38\bin"

In addition to the required packages, a number of optional packages enable additional features when installed:

Optional Package Features Supported
numexpr Acceleration of some functions in sporco.linalg
mpldatacursor Data cursor enabled for plot.plot, plot.contour, and plot.imview
cupy GPU acceleration of modules in sporco.cupy
wurlitzer Utility that supports capture of sporco.cuda function output within Jupyter notebooks
GPUtil Additional utility functions in sporco.cupy
mpi4py Parallel computation of the grid search in sporco.mpiutil