Using Sassena with Docker

Sassena provides a convenient runner.sh script that handles building and running Sassena inside a Docker container. This approach ensures you have all the correct dependencies without modifying your local system.

Note

You must have Docker installed on your system to use these features.

If you are unfamiliar with Docker, it is a platform for developing, shipping, and running applications in isolated environments called containers. You can learn more about the fundamentals in the official Docker overview.

Key Concepts

If you are new to containerization, here is a brief explanation of the terminology used in this script:

  • Docker Build: This creates a self-contained “image”—a snapshot of a Linux operating system with Sassena and all its complex dependencies (HDF5, Boost, MPI) pre-installed. This guarantees reproducibility: if the simulation runs on your laptop, it will run exactly the same way on a cluster or a colleague’s machine.

  • Local Build: This compiles the code directly on your computer’s operating system (without Docker). This requires you to manually install all development libraries. This is primarily useful for developers modifying the C++ source code who want faster incremental compilation, but it is harder to set up.

  • Cache vs. No-Cache: Docker remembers previous build steps to save time. If you change one file, it usually only recompiles that specific part (using the cache). Using --no-cache forces Docker to ignore previous work and rebuild everything from scratch. This is useful if you suspect a build artifact is corrupted or if you want to ensure you have the absolute latest system updates.

The Runner Script

The runner.sh script is located in the root of the repository. It acts as a wrapper around Docker commands.

Basic Usage

./runner.sh [command] [options]

Available Commands

Command

Description

build

Builds the Docker image containing Sassena.

run

Runs Sassena inside the container using your local data.

test

Runs the test suite (Unit/Integration) in Docker or locally.

build-local

Compiles Sassena directly on your machine (no Docker).

help

Displays the help message with all available options.

Workflow Example

1. Build the Image

First, build the Docker image. You can choose between a CPU or CUDA (GPU) build.

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

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

2. Run Sassena

Once built, you can run Sassena. The script automatically mounts your current directory to /data inside the container.

# Simple run (implicit Sassena flags)
./runner.sh run --config scatter.xml

# Run using MPI with 4 processes (explicit separation)
./runner.sh run --mpi -np 4 --sassena --config scatter.xml

3. Run Tests

You can run the test suite to ensure everything is working correctly.

# Run unit tests in Docker (default)
./runner.sh test --unit

# Run all tests (including integration)
./runner.sh test --all

# Run tests locally (requires build-local with tests enabled first)
./runner.sh build-local --cpu --tests
./runner.sh test --local --unit

Command Reference

Build Options

  • --cpu: Build the standard CPU version (default).

  • --cuda: Build the version with CUDA support.

  • --no-cache: Force a complete rebuild of the Docker image.

Build-Local Options

When building locally without Docker:

  • --cpu: Build for CPU (default).

  • --cuda: Build for CUDA/GPU.

  • --clean: Delete the build directory before building (useful if fixing generator errors).

  • --install-deps: Attempt to install system dependencies (requires sudo).

  • --tests: Enable building the test suite (required for ./runner.sh test --local).

Run Options

The run command uses a flexible argument parser. You can switch between passing flags to the runner script, the MPI launcher, or the Sassena application using delimiters.

Syntax:

./runner.sh run [runner_flags] [--mpi <mpi_flags>] [--sassena <sassena_flags>]

Runner Flags:

  • --use-cuda: Use the CUDA-enabled Docker image.

  • --data-dir DIR: Local directory to mount (default: current directory).

Delimiters:

  • --mpi: All subsequent flags are passed to mpiexec (e.g., -np 4, --allow-run-as-root).

  • --sassena: All subsequent flags are passed to the sassena application (e.g., --config).

Note: If no delimiters are used, the script defaults to “runner mode”. Any flag not recognized as a runner flag (like --use-cuda) is automatically treated as a Sassena flag.

Test Options

The test command allows running the test suite in a CI-like Docker environment or locally.

  • --unit: Run unit tests only (default).

  • --integration: Run integration tests only.

  • --all: Run all tests.

  • --use-cuda: Use the CUDA-enabled CI image.

  • --local: Run tests on the host machine (requires build-local).

  • --build-dir DIR: Specify a custom build directory for local tests.

Troubleshooting

Permission Issues: If you encounter permission errors with output files, ensure your user ID inside the container matches your host user. The runner script attempts to handle this automatically.

MPI Errors: If running in an environment that requires root privileges (like some CI pipelines), pass the flag within the MPI section:

./runner.sh run --mpi -np 4 --allow-run-as-root --sassena --config scatter.xml