OpenWQ
Other Modules
Detailed theory and JSON configuration for transport, sorption isotherms,
lateral exchange, and sediment transport modules
lateral exchange, and sediment transport modules
Contents
β’ Module Overview
Section 01: Transport Modules
β’ ADVDISP (Advection-Dispersion)
β’ ADV (Advection Only)
β’ NONE (No Transport)
Section 02: Lateral Exchange
β’ BOUNDMIX Theory
β’ Configuration
Section 03: Sorption Isotherms
β’ Langmuir Isotherm
β’ Freundlich Isotherm
β’ Configuration
Section 04: Sediment Transport
β’ HYPE_HBVSED Model
β’ HYPE_MMF Model
β’ Configuration
OpenWQ
2
Module Overview
OpenWQ provides specialized modules for different physical and chemical processes:
Transport
Controls solute movement with water flow
| ADVDISP | Full transport |
| ADV | Advection only |
| NONE | No transport |
Lateral Exchange
Mixing between compartments
| BOUNDMIX | Boundary mixing |
Vertical & horizontal exchange
Sorption
Solid-liquid partitioning
| LANGMUIR | Monolayer |
| FREUNDLICH | Empirical |
Sediment Transport
HYPE_HBVSED: HBV-sed approach β flow-based erosion
HYPE_MMF: Modified Morgan-Morgan-Finney β rainfall/runoff erosion
OpenWQ
3
01
Transport Modules
ADVDISP: Advection-Dispersion Transport
Advection-Dispersion Equation
βC/βt = -vΒ·βC + βΒ·(DΒ·βC)
Components
| C | Concentration [mg/L] |
| v | Flow velocity [m/s] |
| D | Dispersion coefficient [mΒ²/s] |
Advection: Transport with bulk water flow
Dispersion: Spreading due to velocity variations
Dispersion: Spreading due to velocity variations
Use Cases
- River reaches with mixing
- Groundwater transport
- Lake outflow mixing
- Estuarine systems
Advection (v)
βββββββββββββββββββββββββββββββ
ββββββββββββ β ββββ ββββ ββββ
Initial pulse Dispersion spreads
concentration
OpenWQ
5
Transport Module Configuration
{
// In openWQ_master.json β MODULES
"TRANSPORT_EROSION": {
"MODULE_NAME": "OPENWQ_NATIVE_TRANSP_DISS_ADVDISP",
"MODULE_CONFIG_FILEPATH": "transport_config.json"
}
}
// transport_config.json
{
"ADVDISP_CONFIGURATION": {
"dispersion_x": 10.0, // mΒ²/s, longitudinal
"dispersion_y": 1.0, // mΒ²/s, lateral
"dispersion_z": 0.1, // mΒ²/s, vertical
"characteristic_length_m": 100.0
}
}
Module Options
| Module Name | Description |
|---|---|
ADVDISP | Advection + Dispersion |
ADV | Advection only |
NONE | No transport |
Parameters
| dispersion_x | 0.1 - 100 mΒ²/s |
| dispersion_y | 0.01 - 10 mΒ²/s |
| dispersion_z | 0.001 - 1 mΒ²/s |
| char_length | Grid scale [m] |
OpenWQ
6
02
Lateral Exchange
BOUNDMIX: Boundary Mixing
Mass Exchange Rate
F = K Β· (Cupper - Clower)
Components
| F | Mass flux [g/s] |
| K | Exchange coefficient [1/s] |
| C | Concentration [mg/L] |
K_VAL: Controls mixing rate β higher values mean faster equilibration between compartments
UPPER COMPARTMENT (e.g., Runoff)
βββββββββββββββββββββββββββββββ
β C_upper = 5.0 mg/L β
ββββββββββββββββ¬βββββββββββββββ
β
β K_VAL = 0.001 /s
β ββ Exchange
β
ββββββββββββββββ΄βββββββββββββββ
β C_lower = 2.0 mg/L β
βββββββββββββββββββββββββββββββ
LOWER COMPARTMENT (e.g., Soil)
Common Exchanges
- Runoff β Soil
- Soil β Groundwater
- River β Hyporheic zone
OpenWQ
8
BOUNDMIX Configuration
{
// In transport_config.json
"BOUNDMIX_CONFIGURATION": {
// Exchange 1: Runoff β Soil
"1": {
"DIRECTION": "z",
"UPPER_COMPARTMENT": "RUNOFF",
"LOWER_COMPARTMENT": "SOIL",
"K_VAL": 0.001 // [1/s]
},
// Exchange 2: Soil β Groundwater
"2": {
"DIRECTION": "z",
"UPPER_COMPARTMENT": "SOIL",
"LOWER_COMPARTMENT": "GROUNDWATER",
"K_VAL": 0.0001
},
// Exchange 3: River β Floodplain (lateral)
"3": {
"DIRECTION": "x",
"UPPER_COMPARTMENT": "RIVER",
"LOWER_COMPARTMENT": "FLOODPLAIN",
"K_VAL": 0.01
}
}
}
Parameters
| Parameter | Description |
|---|---|
| DIRECTION | x, y, or z axis |
| UPPER_COMPARTMENT | Source compartment |
| LOWER_COMPARTMENT | Destination compartment |
| K_VAL | Exchange rate [1/s] |
Typical K_VAL Ranges
| Fast exchange | 0.01 - 0.1 /s |
| Moderate | 0.001 - 0.01 /s |
| Slow diffusion | 0.0001 - 0.001 /s |
OpenWQ
9
03
Sorption Isotherms
Langmuir Isotherm
Langmuir Adsorption Isotherm
q = qmax Β· KL Β· C / (1 + KL Β· C)
Parameters
| q | Adsorbed concentration [mg/kg] |
| qmax | Maximum adsorption capacity [mg/kg] |
| KL | Langmuir constant [L/mg] |
| C | Equilibrium concentration [mg/L] |
Physical Basis
- Monolayer adsorption model
- Finite number of identical sites
- Saturation at high concentrations
- Best for: Phosphorus, heavy metals
q (adsorbed)
β ___________ q_max
β /
β /
β /
β /
β/__________________ C (solution)
Approaches saturation limit
OpenWQ
11
Freundlich Isotherm
Freundlich Adsorption Isotherm
q = KF Β· Cn
Parameters
| q | Adsorbed concentration [mg/kg] |
| KF | Freundlich constant [(mg/kg)/(mg/L)βΏ] |
| n | Freundlich exponent (0 < n β€ 1) |
| C | Equilibrium concentration [mg/L] |
Physical Basis
- Empirical power-law model
- Heterogeneous surfaces
- No saturation limit
- n < 1: Favorable adsorption
- Best for: Organic compounds, pesticides
Linear case (n = 1):
q = Kd Β· C (partition coefficient)
q = Kd Β· C (partition coefficient)
OpenWQ
12
Sorption Isotherm Configuration
{
// Langmuir configuration
"SORPTION_ISOTHERMS": {
"PO4": {
"ISOTHERM_TYPE": "LANGMUIR",
"COMPARTMENTS": ["SOIL", "SEDIMENT"],
"PARAMETERS": {
"qmax": 500.0, // mg/kg
"KL": 0.5, // L/mg
"Kadsdes": 0.01 // kinetic rate [1/s]
}
},
// Freundlich configuration
"PESTICIDE_A": {
"ISOTHERM_TYPE": "FREUNDLICH",
"COMPARTMENTS": ["SOIL"],
"PARAMETERS": {
"KF": 25.0, // Freundlich K
"n": 0.8, // Freundlich n
"Kadsdes": 0.001 // kinetic rate [1/s]
}
}
}
}
Langmuir Parameters
| Parameter | Typical Range |
|---|---|
| qmax | 100 - 1000 mg/kg |
| KL | 0.01 - 10 L/mg |
| Kadsdes | 0.0001 - 0.1 /s |
Freundlich Parameters
| Parameter | Typical Range |
|---|---|
| KF | 1 - 100 |
| n | 0.3 - 1.0 |
| Kadsdes | 0.0001 - 0.1 /s |
Kadsdes: Controls rate of approach to equilibrium
OpenWQ
13
04
Sediment Transport
HYPE_HBVSED: HBV-Sed Approach
Sediment Yield (HBV-sed)
SY = erosion_index Β· Qexp
Theory
Empirical relationship between streamflow and sediment transport. Based on the HBV-sed model from HYPE.
- Flow-driven erosion
- Simple parameterization
- Suitable for data-sparse regions
Parameters
| erosion_index | Erodibility factor |
| exp | Flow exponent (typically 1-2) |
| Q | Discharge [mΒ³/s] |
| SY | Sediment yield [kg/s] |
Best for:
β’ Catchment-scale modeling
β’ Limited sediment data
β’ Flow-dominated erosion systems
β’ Catchment-scale modeling
β’ Limited sediment data
β’ Flow-dominated erosion systems
OpenWQ
15
HYPE_MMF: Modified Morgan-Morgan-Finney
Detachment by Rainfall
F = K Β· R2 Β· (1 - C)
Transport Capacity
TC = c Β· QΞ· Β· SΞΆ
Key Features
- Rainfall-driven detachment
- Runoff-driven transport
- Slope factor included
- Cover factor (vegetation)
Parameters
| K | Soil erodibility |
| R | Rainfall energy |
| C | Crop/cover factor (0-1) |
| Q | Runoff volume |
| S | Slope gradient |
| Ξ·, ΞΆ | Calibration exponents |
Best for:
β’ Agricultural watersheds
β’ Rainfall-dominated erosion
β’ Land-use change scenarios
β’ Agricultural watersheds
β’ Rainfall-dominated erosion
β’ Land-use change scenarios
OpenWQ
16
Sediment Transport Configuration
{
// In openWQ_master.json β MODULES
"SEDIMENT_TRANSPORT": {
"MODULE_NAME": "HYPE_HBVSED",
"MODULE_CONFIG_FILEPATH": "sediment_config.json"
}
}
// sediment_config.json - HYPE_HBVSED
{
"HBVSED_CONFIGURATION": {
"erosion_index": 0.5,
"flow_exponent": 1.5,
"deposition_rate": 0.1
}
}
// sediment_config.json - HYPE_MMF
{
"MMF_CONFIGURATION": {
"soil_erodibility_K": 0.3,
"cover_factor_C": 0.2,
"slope_factor": 0.05,
"cohesion": 5.0
}
}
HYPE_HBVSED Parameters
| Parameter | Range |
|---|---|
| erosion_index | 0.1 - 5.0 |
| flow_exponent | 1.0 - 2.5 |
| deposition_rate | 0.01 - 0.5 |
HYPE_MMF Parameters
| Parameter | Range |
|---|---|
| soil_erodibility_K | 0.1 - 0.7 |
| cover_factor_C | 0.0 - 1.0 |
| cohesion | 1 - 20 kPa |
OpenWQ
17
Summary
Transport
ADVDISP, ADV, NONE
Controls solute movement with dispersion coefficients
Exchange
BOUNDMIX
Inter-compartment mixing via K_VAL exchange rates
Sorption
LANGMUIR, FREUNDLICH
Solid-liquid partitioning with kinetic rates
Sediment Transport
HYPE_HBVSED (flow-based) | HYPE_MMF (rainfall/runoff-based)
Particulate-bound contaminant transport
All modules configured via JSON β modify parameters without recompiling
OpenWQ
18
Thank You
Questions?
Documentation: openwq.readthedocs.io