Installation

Spring is provided as a python package. However, under the hood, its implementation relies on C++ and CUDA, thus requiring a compilation step. On the hardware side, a CUDA-capable GPU is required (i.e. NVidia GPU).

On the software side, the following tools are necessary to compile from source:

  • C++ compiler (compatible with the C++17 standard)

  • CUDA compiler (CUDA 11 or above)

  • cmake (3.17 or above)

At the moment, no pre-compiled packages are available, and the software has to be built from source. However, the complete installation process is based on the Python package installer PIP , which internally handles also the compilation step.

Getting the source

You can directly download the code from the source repository , or clone it on your machine with git:

$ git clone https://gitlab.ethz.ch/nux/spring.git

Installation

Warning

The compilation of source code should work also on Windows systems, but it is currently not tested.

Go with the terminal into the directory and run the pip install command as it follows:

$ python3 -m pip install .

The pip install command automatically takes care of both the compilation step (based on cmake) and the installation of the spring module in the correct python folder.

Note

The spring module makes use of the pybind11 library to make the C++/CUDA compiled code and python interact. The library is automatically downloaded into the build directory when the pip install command is called. Plase, make sure to have a working internet connection at this point.

Hint

In case of troubles with the installation process, please read the following section and/or run the pip command with the --verbose option, i.e.

python3 -m pip install . --verbose

Checking for compilation errors

If the pip install command fails at compilation step, it could be quite hard to interpret the error message. In such a case, it is convenient to manually execute the compilation step by explicitly calling the cmake command. From the root of the source tree, create a build folder and run the cmake command as following:

$ mkdir build
$ cd build
$ cmake ..

At this step, cmake will look for packages/software needed for compilation. Missing tools will be indicated.

If successful, a proper Makefile is created. The actual compilation can be done achieved with the command:

$ make

Working on specific computing clusters

Spring is currently used for analyis on experimental data acquired at FLASH, EuXFEL and SwissFEL. Here are some instructions to make it run on the computing resources provided by those research facilities.

RA cluster (PSI)

On PSI Ra cluster, first activate the desired conda environment

$ module load anaconda
$ conda activate env_name

Load the following modules with the module command:

$ module load cuda/12.1.1

Navigate to the root of the spring repository and install with the usual pip command:

$ python3 -m pip install .

Maxwell cluster (FLASH/EuXFEL)

On the Maxwell cluster, the following configurations have been tested:

$ module load maxwell
$ module load cuda/11.8

If you want to create a new environment:

$ module load conda/3.9
$ conda create env_name

Navigate to the root of the spring repository and install with the usual pip command:

$ python3 -m pip install .

Note

If you are using a new conda environment, don’t forget to add it to Jupyter, such that it is listed among the available environments. Use the following commands with the environment activated:

$ conda install -c anaconda ipykernel
$ python3 -m ipykernel install --user --name=env_name