Installation

Sassena can be used on Linux and in Docker containers. There are several ways how Sassena can be compiled / installed, which are listed in the following. An AppImage is provided that can be run without the need for compilation or installation. If the AppImage does not work, Sassena has to be compiled. As this process can be a bit lengthy, this page provides several ways to ease the process.

AppImage

An AppImage is provided that can run on Linux (x64, without CUDA support) out of the box when executed (no compilation or installation needed). To use it, download the latest AppImage from the releases page, mark it as an executable and run it from the command-line:

# download the code that comes with an example trajectory so you can run the example
git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
cd sassena

# get some prerequesites that the AppImage needs to run
sudo apt-get install -y openmpi-bin openmpi-common libopenmpi-dev libfuse2 file

# Download Sassena.AppImage from the releases page to this directory (see link above)

# mark as executable
chmod +x Sassena.AppImage

# and run Sassena on the provided example, either on one core
./Sassena.AppImage --config tests/waterdyn4/scatter.xml

# or use MPI on e.g. 4 cores:
mpiexec -np 4 ./Sassena.AppImage --config tests/waterdyn4/scatter.xml

Creating a Docker image

Sassena provides a convenient runner.sh script in the root directory that handles building (and running) Sassena inside a Docker container. Given that you have docker installed on your machine, this approach ensures you have all the correct dependencies without modifying your local system.

This variant describes the Docker Build, a self-contained “image”: a snapshot of a Linux operating system with Sassena and all its complex dependencies (HDF5, Boost, MPI) pre-installed.

First you have to make sure that Docker is installed on your system. On the example of Ubuntu 24.04, one would run

sudo apt update
sudo apt install docker.io
sudo usermod -aG docker $USER
newgrp docker # to activate docker, or you can just close and reopen the terminal

Once Docker is installed, the compilation of Sassena can be done with

# get the source code
git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
cd sassena

# Build for CPU (default)
./runner.sh build --cpu

# Build with NVIDIA GPU support
./runner.sh build --cuda

Docker Installation

For a hassle-free installation, we recommend using the Docker workflow. Please refer to the Using Sassena with Docker for detailed instructions.

Docker Installation

For a hassle-free installation, we recommend using the Docker workflow. Please refer to the Using Sassena with Docker for detailed instructions.

Compiling from Source

VSCode

The easiest way to compile Sassena is by using VSCode’s Dev Containers. This will automatically create a Docker container, install dependencies, configure the build and compile Sassena inside that container. Sassena must then be run form inside this container. This means that no additional dependencies (e.g. Boost) need to be installed on the system as they are all encapsulated inside the container.

To use VSCode’s Dev Containers, you need to have Docker installed. For Linux, this means Docker Engine and Docker Compose. Please follow the installation guide for Docker here and note that you must add your user to the docker group so that VSCode can create and run containers without sudo.

If you want to also build with CUDA support, you must first make sure that your system has the NVIDIA drivers installed. Additionally, running CUDA applications inside of a Dev Container requires the installation of the NVIDIA Container Toolkit. Docker must be configured to use the NVIDIA Container toolkit, so make sure to follow the configuration guide as well.

You can then clone the project. Make sure to update the submodules as Sassena relies upon the header-only library taskflow, which is distributed as a submodule in the repo.

git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
cd sassena
git submodule update --init --recursive

Once you have the required dependencies, you can open the folder in VSCode and the editor will then ask whether you want to open the project in a container. You can select either the CPU or the CPU+CUDA container depending on your needs. If you don’t get any prompt, you can follow the additional instructions in the Dev Container Documentation.

Once VSCode has built the container, it should ask you to configure the project, which corresponds to the CMake configure step. If you only intend to run Sassena and not develop further, pick either “Release (CPU)” or “Release (CPU+CUDA)”. You can then build the project using build button as normal or F7. Once it has been built, you can open a terminal in VSCode (Terminal > New Terminal) and a shell will appear pointing to the current build directory, where the sassena binaries should be visible.

Using the runner.sh script

The runner.sh script provides the possibility to compile the code directly on your computer’s operating system (without Docker). The script will attempt to install all development libraries for you. This is primarily useful for developers modifying the C++ source code who want faster incremental compilation, but it is harder to set up.

# Build for CPU (default)
./runner.sh build-local --cpu

# Build with NVIDIA GPU support
./runner.sh build-local --cuda

Other Editors

For optimal performance (e.g. using target-specific registers, CUDA), Sassena can be compiled on the target machine, e.g. on Ubuntu 24.04 without using any containers.

Note

If you want to use the CUDA backend, you will need the NVIDIA drivers (not the open-source nouveau) as well as the CUDA Toolkit as it contains not only the runtime libraries, but also libraries such as cuFFT, which the Sassena CUDA backend relies upon.

The process is in essence the same as building with VSCode, though it requires manually configuring with CMake and compiling:

sudo apt install build-essential cmake ninja-build git\
 openmpi-bin libblas-dev liblapack-dev \
 libxml2-dev libhdf5-dev zlib1g-dev libfftw3-dev\
 libboost-regex-dev libboost-mpi-dev\
 libboost-thread-dev libboost-serialization-dev\
 libboost-filesystem-dev libboost-program-options-dev
git clone https://codebase.helmholtz.cloud/DAPHNE4NFDI/sassena.git
cd sassena
git submodule update --init --recursive
cmake --preset=rel-cpu --build # or rel-cuda if you want to build with CUDA

Clusters

If you are compiling Sassena on a cluster and are not able to install packages such as Boost, you can still compile them locally and include them in the Sassena build.

During the CMake configuration process, Sassena will look for the following libraries:

  • LibXml2

  • ZLIB

  • HDF5

  • LAPACK

  • spdlog

  • FFTW3

  • CudaToolkit (if using CUDA)

  • Boost

  • MPI

You can compile these separately and pass their locations to CMake. For example, for Boost, this means setting the BOOST_ROOT location:

cmake --preset=dev -DBOOST_ROOT=/opt/boost .

Please note that there is no standardised naming convention for these CMake options. For each library, you must consult the relevant FindX page in the CMake documentation, where X is the name of the library. For example, for HDF5, the relevant CMake module is called FindHDF5.

CMake Presets

Sassena defines several CMake presets which saves time over configuring the CMake build manually as it sets default values for the most common options. All of these values can be viewed or changed in CMakePresets.json, though you can still override them using the command-line as usual:

cmake --preset=rel-cpu -DSASS_BUILD_DOCS=ON .

This would use the Release (CPU) preset but also build documentation, which is usually disabled for a release build.

Depending on your use-case, you may wish to use a different preset, but we recommend you stick with Release (CPU) for most cases:

Sassena’s CMake Presets

Preset Display Name

Preset CMake Parameter

Explanation

Dev (CPU)

--preset=dev

This is the debug build for Sassena with CPU support only. It will have signficantly worse runtime performance than a release build but will allow you to debug the program with a debugger like gdb. It also enables the developer mode, so tests will be built.

Dev (CUDA)

--preset=dev-cuda

This is also a debug build for Sassena except it also builds the project with CUDA support. This means you must have a CUDA-compatible GPU, the NVIDIA Drivers and the CUDA Toolkit installed.

Release (CPU)

--preset=rel-cpu

This is a release build of Sassena (i.e. optimisations are enabled) and supports CPU only.

Release (CUDA)

--preset=rel-cuda

This is a release build of Sassena (i.e. optimisations are enabled) and supports CUDA, so the same precautions must be taken as with dev-cuda.

Building Unit Tests

Sassena defines a CMake option USE_DEVELOPER_MODE, which is automatically enabled if you use either of the dev presets. If this option is enabled, then unit tests are built.

The unit tests are run as a testing step on the CI but if you wish to run them locally, they appear as a target in CMake. Therefore, depending on the generator (e.g. Ninja, Make), you can execute

ninja test

to run the tests. If you are using a release build and still want to run the tests, you can pass the option -DUSE_DEVELOPER_MODE=ON to CMake in the command-line as described in the CMake Presets section.

Building Documentation

If you want to build the documentation locally, then you must have Sphinx and Doxygen installed, as well as doxysphinx and sphinx_rtd_theme (both of which are written in Python and are available on pip). All of these dependencies are already included in the VSCode Dev Container.

You must then enable the SASS_BUILD_DOCS option in CMake. This can be done by passing -DSASS_BUILD_DOCS=ON to CMake when configuring the project, for example. If this succeeded, then the docs-sass target will be added to the build, which can be built by running

ninja docs-sass

if you are using the Ninja build generator (which is the default).

The .html files will be built in the docs/sphinx directory inside the build folder.

Other Build Generators

CMake does not actually build the project itself but instead generates a build script for a build system, e.g. Make, Visual Studio or XCode. Sassena uses Ninja by default as it is simple and performant. However, if you don’t want to use Ninja you can override the default option, e.g.

cmake --preset=rel-cpu -G "Unix Makefiles" .

will tell CMake to output Makefiles instead. You can then run make in the build directory as usual.