OpenWQ

Open-Source Water Quality Modeling Framework

A flexible, modular platform for simulating biogeochemical processes
coupled with any hydrological model

Diogo Costa

University of Évora, Portugal

What is OpenWQ?

OpenWQ is an open-source water quality modeling framework designed to simulate the transport and transformation of chemical species in aquatic environments.

                            Key Innovation:

                            Biogeochemistry is defined in JSON configuration files, not hardcoded. Users can modify reactions without recompiling!

Modular — Couples with any hydrological model
Flexible — User-defined reaction networks
Scalable — From hillslope to continental
Open — Community-driven development

┌─────────────────────────────────┐
│        HOST MODEL               │
│  (SUMMA, mizuRoute, CRHM, ...)  │
│                                 │
│   Provides:                     │
│   • Water fluxes                │
│   • Storage volumes             │
│   • Temperature                 │
└───────────────┬─────────────────┘
                │
                ▼
┌─────────────────────────────────┐
│          OpenWQ                 │
│                                 │
│   Computes:                     │
│   • Chemical transport          │
│   • Biogeochemical reactions    │
│   • Source/sink dynamics        │
│   • Concentrations & loads      │
└─────────────────────────────────┘

Core Capabilities

🧪

Bio/Geochemistry

Two engines: NATIVE_BGC_FLEX for user-defined kinetic reactions (JSON-based) and PHREEQC for thermodynamic equilibrium geochemistry.

📊

Sources & Sinks

Flexible loading from CSV, JSON, HDF5, land-use coefficients, or ML predictions.

🔧

Calibration

DDS optimizer with Morris screening and Sobol sensitivity analysis.

Available Modules

Transport	Advection & dispersion
Lateral Exchange	Inter-compartment fluxes
Isotherms	Freundlich, Langmuir sorption
Erosion	Sediment-bound transport
Consumptive Use	Irrigation, withdrawals
External Fluxes	Precipitation, inflows

Available Modules

OpenWQ provides a comprehensive set of modules for water quality modeling:

🧪 Biogeochemistry

NATIVE_BGC_FLEX	User-defined kinetics
BGC_FLEX_THERMO	With F_T factor
PHREEQC	Equilibrium geochemistry

🌊 Transport & Exchange

ADVDISP	Advection + Dispersion
ADV	Advection only
BOUNDMIX	Lateral exchange

📎 Sorption & Sediment

LANGMUIR	Sorption isotherm
FREUNDLICH	Sorption isotherm
HYPE_HBVSED	Sediment transport
HYPE_MMF	Sediment transport

                    All modules configured via JSON — swap modules by changing configuration, not code!

                    See "Other Modules" presentation for detailed theory and configuration.

Coupled Host Models

OpenWQ integrates with established hydrological models via C++/Fortran wrappers:

Model	Domain	Description
SUMMA	Land Surface	Structure for Unifying Multiple Modeling Alternatives — multi-physics land model
mizuRoute	River Routing	Continental-scale river routing with lakes and reservoirs
mizuRoute-CSLM	River + Lakes	mizuRoute with Community Surface and Lake Model integration
FLUXOS	Overland Flow	2D overland flow and sediment transport model
CRHM	Cold Regions	Cold Regions Hydrological Model — snow, frozen soils, prairie hydrology
Custom	Any	Straightforward API for coupling with any model

                    Coupling Approach: OpenWQ receives water fluxes and volumes from the host model, then computes solute mass balance and returns updated concentrations.
                

01

Theoretical Framework

Governing Equation: Mass Balance

Mass Conservation for Species i in Compartment j

dM_ij/dt = Σ(Q_in·C_in) - Σ(Q_out·C_ij) + S_ij + R_ij

Term	Description
M_ij	Mass of species i in compartment j [g]
Q_in, Q_out	Water fluxes from host model [L/s]
C_in, C_ij	Concentrations [mg/L]
S_ij	External sources/sinks [g/s]
R_ij	Biogeochemical reactions [g/s]

Key Processes

Advection — Transport with water flow
Dispersion — Spreading due to velocity gradients
Reactions — Chemical transformations
Exchange — Lateral mixing between compartments

Compartment Structure

OpenWQ organizes the domain into compartments — hydrological units that store and transport water.

Example Compartments

SOIL (multiple layers)
RUNOFF (surface flow)
GROUNDWATER (aquifers)
RIVER_REACHES
LAKES / RESERVOIRS

                            Each compartment has its own cycling framework — the set of biogeochemical reactions active within it.
                        

     PRECIPITATION
          ↓ (External Flux)
    ┌─────────────┐
    │   CANOPY    │
    └──────┬──────┘
           ↓
    ┌─────────────┐
    │   RUNOFF    │────→ RIVER
    └──────┬──────┘        ↓
           ↓            LAKE
    ┌─────────────┐
    │  SOIL_L1    │
    └──────┬──────┘
           ↓ (Exchange)
    ┌─────────────┐
    │  SOIL_L2    │
    └──────┬──────┘
           ↓
    ┌─────────────┐
    │ GROUNDWATER │
    └─────────────┘

Module Architecture

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                    OpenWQ MODULES                                       │
├────────────────────────────────────────────────────────────────────────────────────────┤
│                                                                                         │
│   ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐        │
│   │   BIOGEOCHEMISTRY   │    │      TRANSPORT      │    │   SOURCES/SINKS     │        │
│   │                     │    │                     │    │                     │        │
│   │ • NATIVE_BGC_FLEX   │    │ • Advection         │    │ • JSON/CSV/HDF5     │        │
│   │   (user kinetics)   │    │ • Dispersion        │    │ • Land-use based    │        │
│   │                     │    │ • Lateral exchange  │    │ • ML predictions    │        │
│   │ • PHREEQC           │    │                     │    │                     │        │
│   │   (equilibrium)     │    │                     │    │                     │        │
│   └─────────────────────┘    └─────────────────────┘    └─────────────────────┘        │
│                                                                                         │
│   ┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐        │
│   │     SORPTION        │    │  SEDIMENT TRANSPORT │    │      OUTPUT         │        │
│   │                     │    │                     │    │                     │        │
│   │ • Freundlich        │    │ • HYPE_HBVSED       │    │ • HDF5              │        │
│   │ • Langmuir          │    │ • HYPE_MMF          │    │ • CSV               │        │
│   │                     │    │                     │    │                     │        │
│   └─────────────────────┘    └─────────────────────┘    └─────────────────────┘        │
│                                                                                         │
└────────────────────────────────────────────────────────────────────────────────────────┘

                    All modules are configured via JSON files — swap modules by changing configuration, not code!
                

02

Supported Processes

Biogeochemical Processes

🌿

Nitrogen Cycle

Nitrification, denitrification, mineralization, immobilization, volatilization

🧫

Phosphorus Cycle

Sorption, desorption, mineralization, sediment binding

🍂

Carbon Cycle

DOC production, BOD decay, organic matter decomposition

💨

Dissolved Oxygen

Reaeration, respiration, photosynthesis, SOD

🔩

Heavy Metals

Sorption isotherms, complexation, precipitation

🦠

Pathogens

Die-off, settling, resuspension, UV inactivation

🧴

Pesticides

Degradation, volatilization, sorption, hydrolysis

⚗️

Geochemistry

pH, speciation, mineral equilibria (PHREEQC)

                    All processes use the same framework — define consumed/produced species + kinetic expression
                

Pre-Built Model Templates

Popular Model Frameworks

SWAT	N & P cycling with erosion
QUAL2E/QUAL2K	Stream water quality
HYPE	Large-scale nutrient modeling
WASP8	Lakes and estuaries
INCA	Integrated catchment N & C
SPARROW	Regional nutrient export

NATIVE_BGC_FLEX Templates (.json)

Inorganic nitrogen (NO₃, NH₄)
Phosphorus (PO₄, sediment-P)
Carbon (DOC, POC) & Dissolved oxygen
Heavy metals, Pathogens, Tracers

PHREEQC Templates (.pqi)

Major ions equilibrium
Mineral saturation indices
Kinetic processes (DO, algae)

03

Applications

Application Areas

🌾 Agricultural Watersheds

Nutrient export from croplands
Fertilizer management
Best management practices
Tile drainage impacts

🏔️ Cold Regions

Snowmelt-driven transport
Freeze-thaw effects
Permafrost dynamics
Spring freshet loading

🏙️ Urban Systems

Stormwater quality
Point source impacts
Green infrastructure
Combined sewer overflows

🌊 Lakes & Reservoirs

Eutrophication
Algal blooms
Stratification effects
Reservoir operations

⛏️ Mining Impacts

Acid mine drainage
Metal contamination
Tailings pond seepage
Remediation modeling

🌍 Large-Scale Studies

Continental nutrient budgets
Climate change impacts
Land-use scenarios
Policy evaluation

Technical Stack

Languages & Libraries

C++	Core simulation engine
Fortran	Host model coupling (SUMMA, mizuRoute)
Python	Configuration, calibration, post-processing
Armadillo	Linear algebra
exprtk	Mathematical expression parsing
PhreeqcRM	Geochemical reactions

I/O & Deployment

NetCDF/HDF5	Input/output data
JSON	Configuration files
CMake	Build system
Docker	Container deployment
Apptainer	HPC deployment

OpenMP parallelization for multi-core performance

AI-Powered Assistance

OpenWQ includes built-in support for AI-powered assistance using Claude and other LLMs.

🖥️ Claude Code CLI (Users & Developers)

# macOS/Linux: Install + add to PATH
curl -fsSL https://claude.ai/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Windows: Install using winget, then restart terminal
winget install Anthropic.ClaudeCode

# Navigate to OpenWQ & start Claude
cd /path/to/openwq/ && claude

# CLAUDE.md auto-loaded - ask anything:
> How do I set up nitrification?

Can read, write & edit files directly

🌐 Web/API Users (Everyone)

Copy prompt from docs/OPENWQ_ASSISTANT_PROMPT.md

Paste into claude.ai or any AI assistant

What AI Can Help With

BGC reaction configuration
Calibration framework setup
Troubleshooting errors
Understanding source code
Writing JSON configurations

                            Pro Tip: Create a Claude Project with uploaded docs for persistent context across conversations
                        

Summary

🔧 Flexible

User-defined reactions without recompiling. JSON-based configuration.

🔗 Coupled

Works with SUMMA, mizuRoute, CRHM, and custom hydrological models.

🌐 Open

Open-source, community-driven, actively developed.

                            OpenWQ bridges the gap between hydrological modeling and water quality science

                            — bringing flexible biogeochemistry to any water model

Thank You

Questions & Resources

GitHub: github.com/ue-hydro/openwq

Documentation: openwq.readthedocs.io

Contact: diogo.costa@uevora.pt

OpenWQ

Contents

What is OpenWQ?

Core Capabilities

Bio/Geochemistry

Sources & Sinks

Calibration

Available Modules

Available Modules

🧪 Biogeochemistry

🌊 Transport & Exchange

📎 Sorption & Sediment

Coupled Host Models

Theoretical Framework

Governing Equation: Mass Balance

Key Processes

Compartment Structure

Example Compartments

Module Architecture

Supported Processes

Biogeochemical Processes

Nitrogen Cycle

Phosphorus Cycle

Carbon Cycle

Dissolved Oxygen

Heavy Metals

Pathogens

Pesticides

Geochemistry

Pre-Built Model Templates

Popular Model Frameworks

NATIVE_BGC_FLEX Templates (.json)

PHREEQC Templates (.pqi)

Applications

Application Areas

🌾 Agricultural Watersheds

🏔️ Cold Regions

🏙️ Urban Systems

🌊 Lakes & Reservoirs

⛏️ Mining Impacts

🌍 Large-Scale Studies

Technical Stack

Languages & Libraries

I/O & Deployment

AI-Powered Assistance

🖥️ Claude Code CLI (Users & Developers)

🌐 Web/API Users (Everyone)

What AI Can Help With

Summary

🔧 Flexible

🔗 Coupled

🌐 Open

Thank You