Every method in the rest of this deck starts from the repository root. Clone once, cd into it, and keep that as your working directory for every command that follows.

# Clone the FLUXOS source
git clone https://github.com/ue-hydro/FLUXOS_cpp.git

# Enter the repo — all container recipes, Python scripts and sample
# inputs are referenced relative to this directory.
cd FLUXOS_cpp

Two steps on the host: install Docker, then build the container image. The image ships every FLUXOS build-time dependency and the source tree. It does not compile FLUXOS yet — that's step 4, on the next slide.

1 · Activate Docker (host)

# macOS / Windows:  install & launch Docker Desktop  (https://www.docker.com/products/docker-desktop)
# Linux:            install Docker Engine              (https://docs.docker.com/engine/install/)
# Sanity check (bash / zsh — macOS & Linux):
docker --version && docker compose version

# Sanity check (Windows PowerShell — `&&` is unsupported in PowerShell 5.1):
#   docker --version ; docker compose version

2 · Create the container image (installs build deps)

# From the repo root. Installs CMake, GCC, Armadillo, HDF5, nlohmann/json, OpenMP.
docker compose -f containers/docker-compose.yml build

# Add MPI support (optional) — brings OpenMPI into the image.
# bash / zsh (macOS & Linux):
USE_MPI=ON docker compose -f containers/docker-compose.yml build

# Windows PowerShell equivalent (set the env var first, then build):
#   $env:USE_MPI="ON"; docker compose -f containers/docker-compose.yml build

# Windows cmd.exe equivalent:
#   set USE_MPI=ON&& docker compose -f containers/docker-compose.yml build

With the container image ready, open a shell and compile FLUXOS. The whole repo is bind-mounted at /work, so every file the build writes lands on the host automatically.

3 · Open a shell inside the container

# Drops you at a bash prompt inside the container. The host repo is
# bind-mounted at /work, so sources, bin/, and any Results*/ folders
# are the same files on the host and in the container.
docker compose -f containers/docker-compose.yml run --rm fluxos

4 · Compile FLUXOS (inside the shell)

# You are now inside the container (default shell is bash). /work is
# the bind-mounted repo root. Each command is on its own line so the
# snippet survives multi-line paste in any host terminal — including
# Windows PowerShell, which can mangle && chains.
cd /work
mkdir -p build
cd build

# -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/work/bin drops the binary onto the host's ./bin/
cmake -DMODE_release=ON \
      -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/work/bin /work
make -j$(nproc)

# Run from /work so the relative paths inside the modset resolve against
# Example for the bind-mounted inputs at /work/Working_example/ . Simulation outputs
# land at whichever folder the modset's OUTPUT_FOLDER names.
cd /work
./bin/fluxos Working_example/modset_river_30h.json

Apptainer (formerly Singularity) runs rootless on HPC clusters and mounts user home directories transparently. Two recipes are provided: fluxos_apptainer.def (CPU + OpenMP + MPI) and fluxos_apptainer_cuda.def (CUDA + MPI). Neither compiles FLUXOS during image build — that's step 4, next slide.

1 · Activate Apptainer (login node)

# Most HPC systems provide Apptainer as a module (or: module load singularity)
module load apptainer
# Sanity check
apptainer --version
# Local install (workstation): https://apptainer.org/docs/admin/main/installation.html

2 · Create the .sif image (installs build deps)

# CPU + OpenMP + MPI — run from the repo root
apptainer build --fakeroot fluxos_cpu.sif \
    containers/fluxos_apptainer.def

# CUDA + MPI (GPU nodes) — the resulting run must use --nv to expose host GPUs
apptainer build --fakeroot fluxos_cuda.sif \
    containers/fluxos_apptainer_cuda.def

Apptainer .sif images are read-only, so compile into a bind-mounted host directory. The container's source tree lives at /opt/fluxos; point CMake at it and build into the writable mount.

3 · Open a shell inside the container

# CPU shell with the current dir bind-mounted at /src (writable)
apptainer shell --bind $PWD:/src fluxos_cpu.sif

# CUDA shell — --nv exposes host GPUs + drivers
apptainer shell --nv --bind $PWD:/src fluxos_cuda.sif

4 · Compile FLUXOS (inside the shell, binary lands in host's ./bin)

# You are now inside the container. Source tree is at /opt/fluxos (read-only).
cd /src
mkdir -p build
cd build

# -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/src/bin → binary appears on the host at ./bin/
cmake -DMODE_release=ON -DUSE_MPI=ON \
      -DCMAKE_RUNTIME_OUTPUT_DIRECTORY=/src/bin /opt/fluxos
make -j$(nproc)

# Run from /src so the modset's relative paths resolve against Working_example/
cd /src
./bin/fluxos_mpi Working_example/modset_river_30h.json

# Multi-process MPI: launch from the login node using `apptainer exec`
# (exit the shell first)
mpirun -n 16 apptainer exec --bind $PWD:/src fluxos_cpu.sif \
    /src/bin/fluxos_mpi /src/Working_example/modset.json

You should already be in the repo root from slide 4 (git clone & cd FLUXOS_cpp). Install the toolchain and libraries FLUXOS links against. All commands below target Debian / Ubuntu; adjust for your package manager.

# 1. Compiler + build tools (GCC 7+ or Clang 5+ for C++17)
sudo apt install build-essential cmake git ca-certificates

# 2. Required libraries — always needed
sudo apt install libarmadillo-dev nlohmann-json3-dev libhdf5-dev libomp-dev

# 3. Optional: MPI (for multi-node / multi-process runs)
sudo apt install libopenmpi-dev openmpi-bin

# 4. Optional: CUDA Toolkit ≥ 11.0 for GPU builds
#    Follow NVIDIA's instructions at https://developer.nvidia.com/cuda-downloads
# Verify the driver is installed
nvidia-smi

All variants share the same CMake pattern — only the feature flags differ.

# Generic pattern (run from the repo root). Linux / macOS / WSL bash:
mkdir build
cd build
cmake -DMODE_release=ON  <flags>  ..
make -j$(nproc)

Build variants — pick the CMake flags you need

The modset JSON is the single argument. Paths inside the modset are resolved relative to the working directory from which you launch the binary.

# Coming from slide 12 you ended in build/; step back to the repo root
# so the relative paths inside the modset resolve against the right place.
cd ..

# Basic / trimesh run (OpenMP threads auto-detected)
./build/bin/fluxos Working_example/modset.json

# Control OpenMP threads explicitly
OMP_NUM_THREADS=8 ./build/bin/fluxos Working_example/modset_trimesh.json

# MPI: distributed across N processes
mpirun -np 16 ./build/bin/fluxos_mpi Working_example/modset.json

# Hybrid MPI + OpenMP (4 MPI procs × 4 threads each)
export OMP_NUM_THREADS=4
mpirun -np 4 ./build/bin/fluxos_mpi Working_example/modset.json

# GPU run
./build/bin/fluxos_cuda Working_example/modset_trimesh.json