Skip to content

Installation Instructions for SERVAL

Requirements

SERVAL requires a recent C++ compiler that supports OpenMP and C++20 (eg. GCC>=8). In addition the current version of SERVAL requires MPI for some features. All other dependencies will be installed through pip.

For MacOS

SERVAL cannot be compiled with the clang compiler that is the default for MacOS because it does not support OpenMP. We recommend installing GCC. If you are using Homebrew to install the latest version of GCC:

brew install gcc

You'll then need to set the CC and CXX environment variables to point to the equivalent binaries. For example if you installed gcc-15 then export the following variables before installing SERVAL:

export CC=/opt/homebrew/bin/gcc-15
export CXX=/opt/homebrew/bin/g++-15

The current version of SERVAL requires open-mpi to be installed. This can also be done through Homebrew:

brew install open-mpi

It is better to install open-mpi after GCC, so that it is linked against the correct compiler, and before compiling SERVAL.

Local installation

For the installation we recommend using a virtual environment. You can create one with:

python3 -m venv myenv
source myenv/bin/activate

Then upgrade pip:

pip install --upgrade pip

Source Distribution

SERVAL has a C++ backend and must be compiled on installation. This is done using the scikit-build-core toolchain and should work on most platforms with a suitable C++ compiler.

To install, clone the repo into the local directory and then install with:

pip install .

For development it is recommended to do:

pip install -e '.[all]'

Wheel Distribution

The same dependencies as above apply. To install from a wheel, download the appropriate wheel file from the releases page and then install with:

pip install serval-<version>-<python-version>-<platform>.whl

Testing

If serval is installed directly from source, then the testing dependencies testing and examples or all must be installed as well. If serval is installed from a wheel then the testing dependencies must be installed separately with:

pip install 'serval[testing]'
pip install 'serval[examples]'

Running the Test Suite

All tests can be run with:

pytest .

We recommend not running the slow tests by default. To avoid the slow tests, use:

pytest -m "not slow" .

Installation on HPC systems

Currently the only HPC system where SERVAL has been tested is the ETHZ Euler cluster. Below are instructions for installing and running SERVAL on Euler. They should be adaptable to other HPCs with similar module systems.

Euler

Release (Python 3.11.6)

Load the following modules: 

module load stack/2024-0o6 gcc/12.2.0 python/3.11.6 openmpi/4.1.6

Clone the repo into the local directory and then create a virtual environment: 

python -m venv --system-site-packages myenv
source myenv/bin/activate

Install SERVAL (including the optional dependencies): 

pip3 install -e '.[all]'

Release (Python 3.12.8 - preferred)

Load the following modules: 

module load stack/2024-0o6 gcc/12.2.0 python/3.12.8 openmpi/4.1.6

Clone the repo into the local directory and then create a virtual environment: 

python -m venv --system-site-packages myenv
source myenv/bin/activate

Install SERVAL (including the optional dependencies): 

pip3 install -e '.[all]'

Release (Python 3.13.0)

Load the following modules: 

module load stack/2025-0o6 gcc/12.2.0 openblas/0.3.28 python/3.13.0 openmpi/4.1.7

Clone the repo into the local directory and then create a virtual environment: 

python -m venv --system-site-packages myenv
source myenv/bin/activate

Install locally fftw3: 

wget http://www.fftw.org/fftw-3.3.10.tar.gz
tar xf fftw-3.3.10.tar.gz
cd fftw-3.3.10
./configure --prefix="$VIRTUAL_ENV" --enable-shared --enable-openmp --disable-mpi CC=gcc
make -j 
make install

Add the local fftw3 installation to the environment variables: 

export PKG_CONFIG_PATH="$VIRTUAL_ENV/lib/pkgconfig:$PKG_CONFIG_PATH"

Install SERVAL (including the optional dependencies): 

cd ..
pip3 install -e '.[all]'

Testing

Open a terminal in a computing node in Euler: 

srun --cpus-per-task=6 --pty bash

After loading the modules and activating the virtual environment, the tests can be run. We recommend not running the slow tests by default. To avoid the slow tests, use:

python -m pytest -m "not slow" .

Note that this requires installation with testing and examples or all dependency tag.

Running examples

Open a terminal in a computing node in Euler: 

srun --cpus-per-task=6 --pty bash

After loading the modules and activating the virtual environment, create a jupyter kernel for your local environment: 

python -m ipykernel install --user --name myenv --display-name "Python (wheel)"
You only need to do this once for every new environment.

Then you can execute the examples in the examples/ folder, selecting the kernel you just created: 

python -m jupyter nbconvert --to notebook --execute ./examples/Projector\ Usage.ipynb --inplace --ExecutePreprocessor.kernel_name=myenv
Note that this requires installation with dev and examples or all dependency tag.

If you would like to delete the kernel later, you can do so from inside your environment with: 

jupyter kernelspec remove myenv

Useful Guides

This section contains useful guides for installing dependencies on different platforms.

MacOS Homebrew Installation

To install Homebrew on MacOS: 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Add Homebrew to your shell. If you use zsh (default on macOS): 
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

If you use bash: 

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.bash_profile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify the installation: 

which brew

You should see: 

/opt/homebrew/bin/brew

For Developers

Building wheels

Linux

Start by installing the build dependencies (if not already installed): 

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build

Then create a virtual environment and install the build tools: 

python3 -m venv buildenv
source buildenv/bin/activate
pip install --upgrade pip
pip install build

Finally build the wheel: 

python -m build --wheel

This will create the wheel file in the dist/ folder.

MacOS

For MacOS we recommend using homebrew and uv. Start by installing homebrew if not already installed (see above). Then install the c++ toolchain and buiild tools if not already installed: 

brew install gcc cmake ninja

Then install uv if not already installed: 

brew install uv

Then build the wheel with uv: 

uv build --wheel

This will create the wheel file in the dist/ folder.