Start Docker
Make sure Docker Desktop is running
β’ 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
Choose the method that matches your environment:
Local development & testing
Recommended for beginners
HPC clusters & production
Recommended for HPC
Full control & customization
Advanced users only
| Armadillo | Linear algebra (C++) |
| HDF5 | Output file format |
| NetCDF | Host model I/O |
| OpenBLAS/LAPACK | Matrix operations |
| CMake β₯ 3.10 | Build system |
| g++ / gfortran | Compilers |
| PHREEQC-RM | Geochemistry engine |
| SUNDIALS | ODE solver |
| ParallelIO | MizuRoute-CSLM support |
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
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
.../openwq), enter the cloned repo: cd openwq.../openwq/openwq
src/ β C++ source code (compiled)supporting_scripts/ β Python tools (config, calibration, output reading)containers/ β Docker & Apptainer definitions
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.
Complete dev environment with all dependencies pre-installed
HPC-ready container definition + job templates for SLURM/PBS
Helper scripts for building and running with containers
openwq/build/ or host_model/bin/
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.
Make sure Docker Desktop is running
cd containers
docker compose up -d
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
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/
| summa_openwq | SUMMA land model |
| mizuroute_openwq | MizuRoute routing |
| mizuroute_lakes_openwq | With lake module |
| mizuroute_lakes_cslm_openwq | CSLM lakes |
| Release | Optimized (production) |
| Debug | With debug symbols |
Apptainer is the current name of the project (since 2021). Some HPC systems may still use the older name Singularity. The commands are interchangeable.
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
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_templates/ for SLURM/PBS submission
| summa_openwq | SUMMA land model |
| mizuroute_openwq | MizuRoute routing |
| mizuroute_lakes_openwq | With lake module |
| mizuroute_lakes_cslm_openwq | CSLM lakes |
| Release | Optimized (recommended for HPC) |
| Debug | With debug symbols |
# 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
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
CMakeLists.txt | Main build config |
cmake/ | CMake modules |
src/ | OpenWQ source code |
| summa_openwq | SUMMA + OpenWQ |
| mizuroute_openwq | mizuRoute + OpenWQ |
| mizuroute_lakes_cslm_openwq | Full lakes model |
openwq_master.json | Main config file |
openwq_config.json | Runtime settings |
openwq_bgc_*.json | BGC framework |
openwq/build/ orhost_model/bin/
| Armadillo not found | Set -DARMADILLO_ROOT=/path |
| HDF5 not found | module load hdf5 or install |
| NetCDF version mismatch | Ensure Fortran bindings installed |
| Library not found | Set LD_LIBRARY_PATH |
| HDF5 version error | Compile with same HDF5 version |
| Permission denied | Add user to docker group |
| Volume mount fails | Check path in docker-compose.yml |
openwq.readthedocs.iogithub.com/ue-hydro/openwq
Best for local developmentdocker-compose build
Best for HPC clustersapptainer build openwq.sif
For advanced userscmake .. && make
Container files: containers/
Docker | Apptainer | Native Linux