Installation

Attention

The installation of PySAP has been extensively tested on Ubuntu and macOS, however we cannot guarantee it will work on every operating system. A Docker image is available (see below) for those unable to install PySAP directly.

If you encounter any installation issues be sure to go through the following steps before opening a new issue:

1. Check that that all the dependencies have been correctly installed.

2. Read through all of the documentation provided, including the troubleshooting suggestions.

3. Check if your problem has already been addressed in a previous issue.

Basic installation

You can install the latest release of PySAP from PyPI as follows.

Tip

Depending on your Python setup you may need to provide the --user option.

pip install --user python-pysap

pip install python-pysap

Developers

Developers are recommend to clone the repository and build the package locally. To build PySAP locally run the following.

pip install .

Alternatively, you can also run the following.

python setup.py install

Custom installation

Caution

These options can also be invoked when installing with pip using the --install-option="<OPTION>" option. For example,

pip install . --install-option="--noplugins"

However, this will disable the use of wheels and may take significantly longer to build all of the dependencies. Therefore, when installing PySAP this way, it is recommended to pre-install all the required dependencies or use the Conda environment provided.

The following options can be passed when running python setup.py install:

• --noplugins : Install PySAP without any plug-ins

• --only=<PLUG-IN NAME> : Install PySAP with only the specified plug-in name(s) (comma separated)

• --nosparse2d : Install PySAP without building Sparse2D

Example

To install PySAP with only the ETomo plug-in and without Sparse2D you would run the following.

python setup.py install --nosparse2d --only=pysap-etomo

Conda environment

A a Conda environment.yml file is provided to facilitate the installation of the required PySAP dependencies along with some optional dependencies that provide additional features. To build the environment run the following.

conda env create -f environment.yml

Then to activate the environment run the following.

conda activate pysap

Finally, install PySAP following the instructions above.

Docker image

A PySAP Docker image is available via Docker Hub that includes the latest stable version of PySAP pre-installed. To install the image run the following.

docker pull ceacosmic/pysap

A Jupyter notebook can be launched using the Docker image as a backend and with access to the user’s current working directory as follows.

docker run -p 8888:8888 -v ${PWD}:/home ceacosmic/pysap

Troubleshooting

If you encounter any difficulties installing PySAP we recommend that you open a new issue and we will do our best to help you.

Linux

PySAP is actively supported and developed using the latest versions of Ubuntu and CentOS. We are confident that you will be able to install PySAP on these distributions if all the required dependencies have been installed.

macOS

PySAP is actively supported and developed using the latest versions of macOS. We are confident that you will be able to install PySAP on most versions of this operating system if all the required dependencies have been installed.

Important

macOS developer tools must be installed beforehand.

xcode-select --install

The easiest way to install CMake and add OpenMP support for Clang on macOS is to install the following packages using Homebrew.

brew install cmake libomp

Further help with macOS can be found here.

Windows

Tip

Windows users are encouraged to use the PySAP Docker image to avoid installation issues.

PySAP is not actively supported or developed on Windows, however some tips are provided in this Gist.