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.

For Windows

The most suitable compiler is MSVC. Specifically we suggest the user installs the compiler through Visual Studio to ensure all libraries are included:

A) Visual Studio 2022 Community

https://visualstudio.microsoft.com/vs/community/

B) Build Tools for Visual Studio 2022

https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022

In both cases during installation select "Desktop development with C++" and enable also the installation of cmake.

Healpy

Currently serval requires the healpy package if one is perforimng the full installation (for development). This package is not available for Windows. This means that the available examples written with Jupyter notebook cannot be executed in Windows. This depencency will be removed soon.

Local installation

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

python3 -m venv myenv
source myenv/bin/activate

or for Windows with:

python -m venv myenv
myenv\Scripts\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]'

Except for Windows (see Requirements).

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