OpenWQ

How to Compile
Step-by-step instructions for compiling OpenWQ
β€” Docker, Apptainer (HPC), and native Linux builds

Contents

β€’ Compilation Methods Overview

β€’ Dependencies

β€’ Clone Repositories

β€’ Repository Structure

Section 01: Docker Build

β€’ Docker: Build Container & Enter It

β€’ Docker: Create Makefile via CMake & Compile

Section 02: Apptainer / Singularity (HPC)

β€’ Apptainer/Singularity: Build Container & Enter It

β€’ Apptainer/Singularity: Create Makefile via CMake & Compile

Section 03: Native Linux

β€’ Native Linux: Manual Setup

β€’ Key Files & Locations

β€’ Troubleshooting

Compilation Methods Overview

Choose the method that matches your environment:

🐳 Docker

Local development & testing

  • All dependencies pre-installed
  • Works on macOS, Linux, Windows
  • Easy volume mounting
  • VSCode integration

Recommended for beginners

πŸ“¦ Apptainer

HPC clusters & production

  • No root required to run
  • HPC-optimized
  • Portable .sif image
  • SLURM/PBS compatible

Recommended for HPC

🐧 Native Linux

Full control & customization

  • Direct hardware access
  • Maximum performance
  • Custom dependencies
  • Requires manual setup

Advanced users only

Note: Native compilation on macOS and Windows is not supported β€” use Docker or Apptainer instead

Dependencies

Required Libraries

ArmadilloLinear algebra (C++)
HDF5Output file format
NetCDFHost model I/O
OpenBLAS/LAPACKMatrix operations
CMake β‰₯ 3.10Build system
g++ / gfortranCompilers

Optional Libraries

PHREEQC-RMGeochemistry engine
SUNDIALSODE solver
ParallelIOMizuRoute-CSLM support
Container builds include everything!
Docker and Apptainer containers come with all dependencies pre-installed β€” no manual setup required.
Recommendation: Use container builds (Docker/Apptainer) for reproducibility. Native builds require careful version matching.

Clone Repositories

Step 1: Clone Host Model

Choose one host model repository:

# SUMMA (land surface hydrology)
git clone -b develop https://github.com/ue-hydro/summa_ashleymedin.git

# mizuRoute (river routing)
git clone https://github.com/ue-hydro/mizuRoute_ESCOMP_withOpenWQlink.git

# mizuRoute-CSLM (with lakes)
git clone https://github.com/ue-hydro/mizuroute_cslm_openwq.git

# FLUXOS (overland flow)
git clone https://github.com/ue-hydro/FLUXOS_cpp.git
                            

Step 2: Clone OpenWQ

Navigate to host model's OpenWQ directory, where the hydrolink file is located (.../openwq/OpenWQ_hydrolink.cpp), then clone:

# Go to the "openwq" directory inside the hostmodel
# Example for Mizuroute:
cd .../route/build/openwq

# Clone OpenWQ (use develop branch)
git clone -b develop https://github.com/ue-hydro/openwq.git
                            
Note: The exact path to the OpenWQ directory varies by host model. However, it is always located inside a folder named "openwq" inside or close to where the hostmodel code is located.

OpenWQ Repository Structure

Navigate inside the cloned OpenWQ repository: From the host model's openwq directory (.../openwq), enter the cloned repo: cd openwq
You should now be at .../openwq/openwq
πŸ“ openwq/ # Root of cloned repo
β”œβ”€β”€ CMakeLists.txt # Build configuration
β”œβ”€β”€ main.cpp # Mock entry point (for testing only)
β”œβ”€β”€ πŸ“ src/ # C++ source code
β”‚   β”œβ”€β”€ couplercalls/ # Host model coupling
β”‚   β”œβ”€β”€ compute/ # Core computations
β”‚   β”œβ”€β”€ models_CH/ # BGC engines (PHREEQC, bgc_flex)
β”‚   β”œβ”€β”€ models_LE/ # Load/export models
β”‚   β”œβ”€β”€ models_SI/ # Sorption/isotherms
β”‚   β”œβ”€β”€ models_TD/ # Transport/dispersion
β”‚   β”œβ”€β”€ models_TS/ # Sediment transport
β”‚   β”œβ”€β”€ readjson/ # JSON config readers
β”‚   β”œβ”€β”€ output/ # HDF5 output writers
β”‚   β”œβ”€β”€ initiate/ # Initialization routines
β”‚   β”œβ”€β”€ units/ # Unit conversions
β”‚   β”œβ”€β”€ extwatflux_ss/ # External water/sources
β”‚   β”œβ”€β”€ global/ # Global variables
β”‚   β””── utils/ # Utility functions
β”œβ”€β”€ πŸ“ supporting_scripts/ # Python tools
β”‚   β”œβ”€β”€ Model_Config/ # Config generators
β”‚   β”œβ”€β”€ Calibration/ # Calibration framework
β”‚   β””── Read_Outputs/ # HDF5 output readers
β”œβ”€β”€ πŸ“ containers/ # Docker & Apptainer
β”‚   β”œβ”€β”€ Dockerfile
β”‚   β”œβ”€β”€ docker-compose.yml
β”‚   β””── openwq_apptainer.def
β”œβ”€β”€ πŸ“ utils/ # Build helper scripts
β”œβ”€β”€ πŸ“ in_a_nutshell/ # HTML presentations
β”œβ”€β”€ πŸ“ wikipage/ # ReadTheDocs source
β”œβ”€β”€ πŸ“ testing/ # Test cases
└── README.md
Key directories:
src/ β€” C++ source code (compiled)
supporting_scripts/ β€” Python tools (config, calibration, output reading)
containers/ β€” Docker & Apptainer definitions

Container Files Organization

OpenWQ provides containerized build support via Docker (for local machines with root access) and Apptainer/Singularity (for HPC environments). Native compilation is possible but is system-dependent and must be configured by the user. Some guidance is provided on page 15, however adjustments will always be needed depending on your system.

πŸ“ containers/
β”œβ”€β”€ Dockerfile # Docker image definition
β”œβ”€β”€ docker-compose.yml # Docker config
β”œβ”€β”€ openwq_apptainer.def # Apptainer definition
└── πŸ“ hpc_templates/ # Job scripts
    β”œβ”€β”€ slurm_job.sh
    β””── pbs_job.sh

πŸ“ utils/
β”œβ”€β”€ install_armadillo.sh # Armadillo installer
β”œβ”€β”€ compile_summa_apptainer.sh
β”œβ”€β”€ run_summa_apptainer.sh
└── compile_mizuroute_apptainer.sh

🐳 Docker Files

Complete dev environment with all dependencies pre-installed

πŸ“¦ Apptainer Files

HPC-ready container definition + job templates for SLURM/PBS

πŸ”§ Utils Scripts

Helper scripts for building and running with containers

Executables: openwq/build/ or host_model/bin/
01

Docker (Local Machines)

Docker: Build Container & Enter It

Assuming the host model and OpenWQ have already been cloned (see Clone Repositories), and that you are now inside the cloned OpenWQ repository (.../openwq/openwq), follow the steps below to build the Docker container and run a shell inside it.

1

Start Docker

Make sure Docker Desktop is running

2

Navigate to containers

cd containers

3

Create the container

docker compose up -d

4

Run a shell inside the container

docker exec -it docker_openwq /bin/bash

# 1. Start Docker
# macOS:
open -a Docker
# Linux:
sudo systemctl start docker
# Windows (PowerShell):
Start-Service Docker

# 2. Navigate to the containers/ folder
cd containers

# (optional) Clear all docker images and containers
docker system prune -a

# 3. Create the "docker_openwq" container
docker compose up -d

# (optional) Stop the container
docker compose down
# (optional) See the containers running
docker ps

# 4. Run a shell inside the container
docker exec -it docker_openwq /bin/bash
                        

Docker: Create Makefile via CMake and Compile the Coupled Hostmodel-OpenWQ

Inside the container (via shell, step 4 of previous page), navigate to the cloned OpenWQ repository (.../openwq/openwq), where the CMakeLists.txt file is located.

Run CMake to generate the Makefile used to compile OpenWQ (see code snippets below).

Important note: OpenWQ requires two CMake arguments: -DHOST_MODEL_TARGET and -DCMAKE_BUILD_TYPE.

# (Optional but recommended) Clean previous CMake
# cache to avoid stale configuration issues
rm -f CMakeCache.txt
rm -rf CMakeFiles

# CMake command syntax:
cmake -DHOST_MODEL_TARGET=<target> \
      -DCMAKE_BUILD_TYPE=<type> .

# Examples:
cmake -DHOST_MODEL_TARGET=summa_openwq \
      -DCMAKE_BUILD_TYPE=Release .

cmake -DHOST_MODEL_TARGET=mizuroute_openwq \
      -DCMAKE_BUILD_TYPE=Debug .

cmake -DHOST_MODEL_TARGET=mizuroute_lakes_cslm_openwq \
      -DCMAKE_BUILD_TYPE=Release .

# Then compile:
# With 8 GB container RAM: use make -j1 (sequential, slower but safe)
# With 16 GB container RAM: use make -j2 (parallel, faster)
make -j1
# Note: if you increased container RAM for compilation, consider
# reducing it afterwards to avoid competing with the host machine.
# Executable created in .../openwq/openwq/bin/
                        

HOST_MODEL_TARGET Options

summa_openwqSUMMA land model
mizuroute_openwqMizuRoute routing
mizuroute_lakes_openwqWith lake module
mizuroute_lakes_cslm_openwqCSLM lakes

CMAKE_BUILD_TYPE Options

ReleaseOptimized (production)
DebugWith debug symbols
02

Apptainer / Singularity (HPC)

Apptainer is the current name of the project (since 2021). Some HPC systems may still use the older name Singularity. The commands are interchangeable.

Apptainer/Singularity: Build Container & Enter It

Assuming the host model and OpenWQ have already been cloned (see Clone Repositories), and that you are now inside the cloned OpenWQ repository (.../openwq/openwq), follow the steps below to build the Apptainer SIF image and enter it.

# 1. Navigate to the containers/ folder
cd containers

# 2. Build Apptainer/Singularity image
apptainer build openwq.sif openwq_apptainer.def
# or
singularity build openwq.sif openwq_apptainer.def
# Or with --fakeroot (if required by your system):
apptainer build --fakeroot openwq.sif openwq_apptainer.def
# or
singularity build --fakeroot openwq.sif openwq_apptainer.def

# IMPORTANT: Build on same architecture as target HPC
# (x86_64 vs ARM). Contact HPC team for site policies.

# 3. Transfer SIF to HPC (if built locally)
scp openwq.sif user@hpc:/path/to/containers/

# 4. Enter the container (run a shell)
apptainer shell --bind $(pwd):/code openwq.sif
# or
singularity shell --bind $(pwd):/code openwq.sif
                        

What's Included in SIF

  • Ubuntu 24.04 base
  • Armadillo 10.6.0
  • SUNDIALS 7.1.1
  • PHREEQC-RM
  • ParallelIO (MizuRoute-CSLM)
  • NetCDF, HDF5, OpenBLAS
Note: Building SIF requires sudo, but running does not β€” perfect for HPC
Image: ~2-3 GB | Build: 15-30 min

Apptainer/Singularity: Create Makefile via CMake and Compile the Coupled Hostmodel-OpenWQ

Inside the container (via shell, step 4 of previous page), navigate to the cloned OpenWQ repository (.../openwq/openwq), where the CMakeLists.txt file is located.

Run CMake to generate the Makefile used to compile OpenWQ (see code snippets below).

Important note 1: OpenWQ requires three CMake arguments: -DHOST_MODEL_TARGET, -DCMAKE_BUILD_TYPE, and -DCMAKE_PREFIX_PATH.

Important note 2: OpenWQ must be compiled on the same machine (and architecture) that was used to build the Apptainer/Singularity SIF image.

# (Optional but recommended) Clean previous CMake
# cache to avoid stale configuration issues
rm -f CMakeCache.txt
rm -rf CMakeFiles

# CMake command syntax:
cmake -DHOST_MODEL_TARGET=<target> \
      -DCMAKE_BUILD_TYPE=<type> \
      -DCMAKE_PREFIX_PATH="<paths>" .

# Examples:
cmake -DHOST_MODEL_TARGET=summa_openwq \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_PREFIX_PATH="/usr/local/phreeqcrm;/usr/local/sundials" .

cmake -DHOST_MODEL_TARGET=mizuroute_openwq \
      -DCMAKE_BUILD_TYPE=Release \
      -DCMAKE_PREFIX_PATH="/usr/local/phreeqcrm;/usr/local/sundials" .

# Then compile:
# With 8 GB container RAM: use make -j1 (sequential, slower but safe)
# With 16 GB container RAM: use make -j2 (parallel, faster)
make -j1
# Note: if you increased container RAM for compilation, consider
# reducing it afterwards to avoid competing with the host machine.
# Executable created in .../openwq/openwq/bin/
                        
HPC Tip: Use job scripts in hpc_templates/ for SLURM/PBS submission

HOST_MODEL_TARGET Options

summa_openwqSUMMA land model
mizuroute_openwqMizuRoute routing
mizuroute_lakes_openwqWith lake module
mizuroute_lakes_cslm_openwqCSLM lakes

CMAKE_BUILD_TYPE Options

ReleaseOptimized (recommended for HPC)
DebugWith debug symbols
Note: CMAKE_PREFIX_PATH is needed so CMake can find PhreeqcRM and SUNDIALS installed inside the container.
03

Native Linux Build

Native Linux: Manual Setup

# 1. Install system dependencies (Ubuntu/Debian)
sudo apt-get install g++ gfortran cmake \
  libnetcdf-dev libnetcdff-dev \
  libhdf5-dev libopenblas-dev liblapack-dev

# 2. Install Armadillo
cd openwq/utils
./install_armadillo.sh
# Installs to openwq/utils/armadillo-VERSION

# 3. (Optional) Install SUNDIALS for ODE solver
wget https://github.com/LLNL/sundials/archive/v7.1.1.tar.gz
tar -xzf v7.1.1.tar.gz && cd sundials-7.1.1
mkdir build && cd build
cmake .. -DBUILD_FORTRAN_MODULE_INTERFACE=ON \
         -DCMAKE_INSTALL_PREFIX=/usr/local/sundials
make -j4 && sudo make install

# 4. Compile OpenWQ
cd openwq
cmake -DHOST_MODEL_TARGET=summa_openwq \
      -DCMAKE_BUILD_TYPE=Release .
# With 8 GB container RAM: use make -j1 (sequential, slower but safe)
# With 16 GB container RAM: use make -j2 (parallel, faster)
make -j1
# Note: if you increased container RAM for compilation, consider
# reducing it afterwards to avoid competing with the host machine.
# Executable in bin/ folder
                        

HPC Cluster Setup

Use module system instead of apt:

module load gcc/11.2.0
module load netcdf/4.8.1
module load hdf5/1.12.1
module load openblas/0.3.18
module load cmake/3.22.1
                            
Caution: Native builds require matching library versions. Container builds are more reproducible.

Key Build Files

Build Configuration

CMakeLists.txtMain build config
cmake/CMake modules
src/OpenWQ source code

Output Executables

summa_openwqSUMMA + OpenWQ
mizuroute_openwqmizuRoute + OpenWQ
mizuroute_lakes_cslm_openwqFull lakes model

Configuration Files

openwq_master.jsonMain config file
openwq_config.jsonRuntime settings
openwq_bgc_*.jsonBGC framework
Executables location:
openwq/build/ or
host_model/bin/

Troubleshooting

CMake Errors

Armadillo not found Set -DARMADILLO_ROOT=/path
HDF5 not found module load hdf5 or install
NetCDF version mismatch Ensure Fortran bindings installed

Runtime Errors

Library not found Set LD_LIBRARY_PATH
HDF5 version error Compile with same HDF5 version

Docker Issues

Permission denied Add user to docker group
Volume mount fails Check path in docker-compose.yml
Get help:
β€’ Documentation: openwq.readthedocs.io
β€’ GitHub Issues: github.com/ue-hydro/openwq

Summary

🐳 Docker

Best for local development
docker-compose build

πŸ“¦ Apptainer

Best for HPC clusters
apptainer build openwq.sif

🐧 Native

For advanced users
cmake .. && make

Quick Start Recommendation:
Use Docker for development β†’ Build Apptainer image for production HPC runs

Thank You

Questions?

Container files: containers/

Docker | Apptainer | Native Linux