A flexible biogeochemical modeling framework for water quality simulations
OpenWQ couples with existing hydrological and hydrodynamic models to enable multi-scale, multi-chemistry simulations. It supports both kinetic reaction networks (via the native BGC-Flex engine) and equilibrium geochemistry (via PHREEQC integration).
- Soure code for the multi-chemistry, multi-scale OpenWQ modelling framework.
- Reading material:
- Documentation
- Articles: Coming soon!
- main: primary branch with latest verified updates to the working code
- development: used to verify updates from feature branches before merging with main
- supporting_scripts: feature branch for development of supporting Python and MATLAB scripts
- wrapper_interfaces: feature branch for development of wrapper interfaces between SUMMA and OpenWQ, and MESH and OpenWQ
- expression_evaluation_optimization: feature branch for optimizing string parsing and the computation of mathematical expressions
- optimization_sink_source: feature branch
- Note that the primary branch (formerly known as "master") was renamed as "main"
- If using a local clone with the previous naming scheme, the clone may be updated using the following Git commands:
$ git branch -m master main
$ git fetch -p origin
$ git branch -u origin/main main
- CMake: CMakeLists.txt is provided
- Library dependencies: Armadillo, VTK, OpenMP
- CMake minimum version: 3.10
Below are the steps to compile SUMMA with OpenWQ integration.
- Clone SUMMA:
git clone -b develop https://github.com/ashleymedin/summa.git cd summa/build/source/openwq- Clone OpenWQ:
git clone -b develop git@github.com:ue-hydro/openwq.git
Native macOS compilation is currently not supported. Please use Docker.
Note: Compilation requires at least 16 GB of RAM due to heavy C++ template instantiation. Use
make -j 2(not-j 4) to avoid out-of-memory crashes. On HPC clusters, request at least--mem=16Gin your job submission.
- Install or Load (Cluster) Dependencies
- NetCDF
- HDF5
- OpenBLAS or LAPACK
- Armadillo
- Included install script in
summa/build/source/openwq/openwq/utils/install_armadillo.sh - Running the script will install Armadillo in the
summa/build/source/openwq/openwq/utils/armadillo-VERSIONdirectory - C++ Compiler (e.g., g++) - Fortran Compiler (e.g., gfortran) - CMake
- Included install script in
- Method 1:
cd summa/build/source/openwq/openwq/build/ cmake ..make -j 2- Method 2:
cd summa/build/cmake/ - Edit the
build.pc.cmakefile to include the OpenWQ library with-DUSE_OPENWQ=ON ./build.pc.cmake
Container files (Dockerfile, docker-compose.yml) are located in the containers/ folder.
- cd into the OpenWQ repository (if following the common steps, this would be
summa/build/source/openwq/openwq) - cd into containers:
cd containers - Build using docker-compose:
docker-compose build - Start the container:
docker-compose up -d - Connect to the container with
docker attach docker_openwqor VSCode's Remote-Containers extension - cd into
/code/build/cmakeand adjust thebuild.pc.cmakefile to include the OpenWQ library with-DUSE_OPENWQ=ON - run
./build.pc.cmaketo compile SUMMA with OpenWQ - Alternatively, you can
cd /code/build/source/openwq/openwq - Edit the
CMakeLists.txt:- Ensure that
COMPILE_TARGETis set tosumma_openwq - To use sundials ensure
SOLVER_TYPEis set tosundials, otherwise useNone
- Ensure that
- mkdir build && cd build
- cmake ..
- make -j 2
Alternative (without docker-compose):
cd containersdocker build -t openwq .- cd back up to the parent directory (e.g., summa)
docker run -itd -v $(pwd):/code openwq- Connect to the container with
docker attach <container_id>
The Apptainer definition file openwq_apptainer.def is located in the containers/ folder. This file can be used to build an Apptainer (Singularity) container. NOTE: You will need sudo access to build the container. Once the container is built you can transfer the container to a system with Apptainer to run the container. Running the container does not require sudo access.
TO BUILD THE CONTAINER:
- Follow the common steps above to obtain the source code
cd summa/build/source/openwq/openwq/containerssudo apptainer build openwq.sif openwq_apptainer.def
COMPILE SUMMA-OPENWQ WITH THE CONTAINER:
- There is a script in
utils/calledcompile_summa_apptainer.shthat will compile SUMMA-OpenWQ using the container. cd utils./compile_summa_apptainer.sh- This script will launch the container and compile SUMMA-OpenWQ - This will create a summa-openwq that can then be run within the container.
RUNNING SUMMA-OPENWQ WITH THE CONTAINER:
- There is an example script in
utils/calledrun_summa_apptainer.shthat will run SUMMA-OpenWQ using the container. cd utils./run_summa_apptainer.sh- This script will launch the container and run the summa-openwq executable
- This will run the summa-openwq executable within the container.
- This script depends on the synthetic_tests: https://github.com/KyleKlenk/synthetic_tests, which will need to be cloned into
summa
- Coming soon!
- Coming soon!
- Used for model configuration, execution, reporting, calibration, and post-processing
- See supporting_scripts folder
The model_config_template.py provides a single-file workflow that can:
- Generate all OpenWQ JSON configuration files (Sections 1-7)
- Run the model inside Docker or Apptainer containers (Section 8)
- Generate an interactive HTML report with maps, charts, and statistics (Section 9)
cd supporting_scripts/Model_Config/
cp model_config_template.py my_project.py
# Edit my_project.py — set run_model = True, generate_report = True
python my_project.py # generates configs → runs model → produces reportThe report (openwq_config_report.html) is a self-contained HTML file featuring:
- Project information header (name, authors, host model, description)
- Module parameter details with collapsible sections for each active module (BGC species/frameworks, transport dispersion, lateral exchange, sediment parameters, sorption isotherms)
- Source/sink setup summary with per-species statistics (cells, time period, total load)
- Interactive Plotly.js time series, Leaflet.js basin maps, spatial statistics, and run metadata
- Config-only mode: set
run_model = Falseto generate a configuration-review report without executing the model
The supporting scripts require Python 3.8+ with several dependencies. A virtual environment setup is provided:
cd supporting_scripts
# Automated setup (recommended)
./setup_venv.sh
# Activate
source .venv/bin/activate
# Or use conda
conda create -n openwq python=3.10
conda activate openwq
pip install -r requirements.txtOpenWQ includes a comprehensive calibration framework with:
- 106+ Calibratable Parameters across all modules (BGC, sorption, sediment, transport, etc.)
- Sensitivity Analysis: Morris screening and Sobol variance-based methods
- DDS Optimization: Efficient parameter calibration for expensive models
- HPC Support: SLURM/PBS templates for high-performance computing
- Interactive HTML Reports: Auto-generated per-variant reports with Plotly.js charts (convergence, time series, scatter, residuals), parameter tables with bounds and position bars, and dark/light theme toggle
- Interactive Basin Maps: Leaflet.js maps with HRU polygons, river network (styled by Strahler order), and observation station markers — embedded directly in reports
- Per-Basin Multi-Variant Reports: Consolidated reports comparing all calibration variants (A/B/C/D) for each basin, with side-by-side KGE metrics and parameter comparisons
Key documentation:
- Calibration Usage Guide - Step-by-step calibration guide
- Sensitivity Analysis Guide - Complete parameter sensitivity reference
- Parameter Defaults - Scientifically-grounded parameter ranges
OpenWQ supports the PHREEQC geochemical engine for advanced water quality simulations including:
- Aqueous speciation and saturation indices
- Equilibrium with mineral phases and gases
- Ion exchange and surface complexation
- Kinetic reactions (dissolution, precipitation, redox)
For setup instructions, see the Documentation.
- Coming soon!