index.rst

User Guide

This page is designed to serve as a quick guide for users (who aren't developers) to compile and run Sassena.

Installation

AppImage

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

chmod +x Sassena.AppImage
./Sassena.AppImage # --config scatter.xml etc.
# or to use mpi:
mpirun -n 16 ./Sassena.AppImage --config scatter.xml

Compiling from Source

If you want to target a specific instruction set (e.g. ARM) or want to use the CUDA implementation, compiling from source is needed.

VSCode

The easiest way to compile Sassena is by using VSCode's Dev Containers. This will automatically create a Docker container, configure the build and compile Sassena inside that container. This means that no additional dependencies (e.g. Boost) need to be installed on the system.

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.

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.

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\
 openmpi-bin libblas-dev liblapack-dev gfortran\
 libxml2-dev libhdf5-dev zlib1g-dev libfftw3-dev\
 libboost-all-dev libboost-regex-dev libboost-mpi-dev\
 libboost-thread-dev libboost-serialization-dev libboost-system-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

Running

Waterdyn4 Test Project

Once you have built Sassena, you may wish to try it on a sample project:

cd tests/waterdyn4
../../build-rel-cpu/bin/sassena --config scatter.xml

The command-line output should look terminate with something like:

[11:38:49 Rank 0] [info] Total runtime (s): 77.552289999999999
[11:38:49 Rank 0] [info] Successfully finished... Have a nice day!

and will output to signal.h5 by default.

Running with CUDA

Sassena has a new CUDA backend for self scattering, though it is only possible to use it if you have built the project from source and used the "Release (CPU+CUDA)" or "Dev (CPU+CUDA)" CMake preset. To try it, you can direct Sassena to use it in the scatter.xml file by adding the following lines inside the <scattering> tag:

<device>
    <type>cuda</type>
    <atoms>100</atoms>
</device>

The value in the <type> tag can be either cpu or cuda depending on the desired backend. If using CUDA, you can dictate how many atoms to calculate in parallel using the <atoms> tag. Note that this is subject to memory capacity on the GPU and will fail if the value is too high.

Sassena can still be run with mpirun in the usual way when using the CUDA backend as only one process will claim the GPU.