OpenWQ

Model Setup Guide

Step-by-step instructions for setting up an OpenWQ water quality model
from scratch — configuration files, directory structure, and execution

Setup Overview

OpenWQ uses JSON configuration files organized in a hierarchical structure:

          ┌──────────────────────┐
          │    Master JSON       │ ← Entry point
          │  (project settings)  │
          └──────────┬───────────┘
                     │
       ┌─────────────┼─────────────┐
       ▼             ▼             ▼
┌────────────┐ ┌────────────┐ ┌────────────┐
│  Config    │ │  Modules   │ │  External  │
│ (IC, comp) │ │ (BGC, etc) │ │  Sources   │
└────────────┘ └────────────┘ └────────────┘

Required Files

Master JSON (entry point)
Configuration file (compartments)
Module configs (see slide 4)
External sources (SS, EWF)

                            💡 Easier Option: Use the Python template!

                            python model_config_template.py

                            Auto-generates all JSON files from one Python script

Available Modules

🧪 Biogeochemistry

NATIVE_BGC_FLEX	User kinetics
BGC_FLEX_THERMO	With F_T factor
PHREEQC	Equilibrium

Config: .json or .pqi + .dat

🌊 Transport

ADVDISP	Advection + Dispersion
ADV	Advection only
NONE	No transport

↔️ Lateral Exchange

BOUNDMIX

Between compartments

Set K_VAL mixing rates [1/s]

📎 Sorption Isotherms

LANGMUIR	qmax, KL, Kadsdes
FREUNDLICH	KF, n, Kadsdes

🏔️ Sediment Transport

HYPE_HBVSED	HBV-sed approach
HYPE_MMF	Modified MMF

Particulate-bound transport

All modules configured in: openWQ_master.json → "MODULES" section

Recommended Directory Structure

📁 my_openwq_project/
├── openWQ_master.json # Entry point
│
├── 📁 openwq_in/ # OpenWQ inputs
│   ├── openWQ_config.json # Compartments & IC
│   ├── openWQ_MODULE_*.json # Biogeochemistry
│   ├── openWQ_MODULE_*.json # Transport, LE, etc.
│   ├── openWQ_SS_*.json # Sources/Sinks
│   └── openWQ_EWF_*.json # External fluxes
│
├── 📁 openwq_out/ # Output folder
│   └── (generated HDF5/CSV files)
│
└── 📁 hostmodel_files/ # Host model inputs

                            💡 Auto-Generated by Scripts!

                            The supporting scripts automatically generate all these files. No need to create them by hand!

                            python model_config_template.py

Generated File Names

openWQ_master.json
openWQ_config.json
openWQ_MODULE_*.json
openWQ_SS_*.json
openWQ_EWF_*.json

01

Master JSON Configuration

Step 1: Create Master JSON

{
    // Project metadata
    "PROJECT_NAME": "My_Watershed_WQ",
    "GEOGRAPHICAL_LOCATION": "Saskatchewan, Canada",
    "AUTHORS": "Your Name",
    "DATE": "Feb_2026",

    // Computational settings
    "COMPUTATIONAL_SETTINGS": {
        "RUN_MODE_DEBUG": false,
        "USE_NUM_THREADS": "all"     // or integer (e.g., 8)
    },

    // Input file references
    "OPENWQ_INPUT": {
        "CONFIG_FILEPATH": "openwq_config.json",
        "SINK_SOURCE": {
            "1": { "LABEL": "Fertilizer", "FILEPATH": "sources_fertilizer.json" }
        },
        "EXTERNAL_WATER_FLUXES": {
            "1": { "LABEL": "Precipitation", "FILEPATH": "precip_chemistry.json" }
        }
    },

    // Module selection
    "MODULES": {
        "BIOGEOCHEMISTRY": { "MODULE_NAME": "NATIVE_BGC_FLEX", "MODULE_CONFIG_FILEPATH": "bgc_cycling.json" },
        "TRANSPORT_EROSION": { "MODULE_NAME": "OPENWQ_NATIVE_TRANSP_DISS_ADVDISP", "MODULE_CONFIG_FILEPATH": "transport.json" }
    },

    // Output configuration
    "OPENWQ_OUTPUT": {
        "RESULTS_FOLDERPATH": "../openwq_out",
        "FORMAT": "HDF5",
        "CHEMICAL_SPECIES": ["NO3_N", "NH4_N"],
        "UNITS": "mg/L",
        "TIMESTEP": [1, "day"]
    }
}

02

Configuration File

Step 2: Define Compartments & Initial Conditions

{
  "BIOGEOCHEMISTRY_CONFIGURATION": {

    // River compartment
    "RIVER_NETWORK_REACHES": {
      "CYCLING_FRAMEWORK": ["N_CYCLE"],
      "INITIAL_CONDITIONS": {
        "DATA_FORMAT": "JSON",
        "NO3_N": {
          "1": ["all", "all", "all", 2.0, "mg/L"]
        },
        "NH4_N": {
          "1": ["all", "all", "all", 0.1, "mg/L"]
        }
      }
    },

    // Soil compartment (from HDF5)
    "SOIL": {
      "CYCLING_FRAMEWORK": ["N_CYCLE", "P_CYCLE"],
      "INITIAL_CONDITIONS": {
        "DATA_FORMAT": "HDF5",
        "FOLDERPATH": "ic_hdf5/",
        "UNITS": "mg"
      }
    }
  }
}

Compartment Names

Must match host model compartments:

RIVER_NETWORK_REACHES
SCALARAQUIFER
SOIL (layer 1, 2, ...)
LAKE

Initial Conditions

Two formats supported:

JSON — [ix, iy, iz, value, units]
HDF5 — from previous run or external

Tip: Use "all" for uniform IC across entire compartment

03

BGC Module Configuration

Step 3: Configure Biogeochemistry

Three biogeochemistry engines available:

NATIVE_BGC_FLEX

User-defined kinetic reactions

"MODULE_NAME": "NATIVE_BGC_FLEX"
// Define species & reactions
"kinetics": ["k * A * B"]
"parameter_values": {...}

📄 Config: .json files

NATIVE_BGC_FLEX_THERMODYNAMIC

Kinetics + equilibrium constraints

"MODULE_NAME":
  "NATIVE_BGC_FLEX_THERMODYNAMIC"
// Kinetics + equilibrium
"equilibrium_species": [...]

📄 Config: .json files

PHREEQC

Full geochemical modeling

"MODULE_NAME": "PHREEQC"
// Uses PHREEQC input files
"FILEPATH": "*.pqi"
"DATABASE": "*.dat"

📄 Config: .pqi + .dat files

                    Choose based on complexity: NATIVE_BGC_FLEX for simple kinetics → THERMODYNAMIC for equilibrium constraints → PHREEQC for full geochemistry
                

Use Pre-Built Templates

Start from existing templates instead of writing from scratch:

NATIVE_BGC_FLEX (.json)

Individual Chemicals

nitrogen_simple/full.json
phosphorus_simple/full.json
dissolved_oxygen.json
carbon_organic.json
heavy_metals.json
pathogens.json, pesticides.json
silica.json, iron_manganese.json
phytoplankton_algae.json

Mimicking Popular Models

SWAT_full_nutrients.json
QUAL2E_stream.json
HYPE_nutrients.json
WASP8_eutrophication.json

BGC_FLEX_THERMO (.json)

Thermodynamic Templates

aerobic_respiration.json
denitrification_thermo.json
nitrification.json
anammox.json
sulfate_reduction.json
iron_reduction.json
manganese_reduction.json
methanogenesis.json
redox_cascade_thermo.json
full_sediment_diagenesis.json

PHREEQC (.pqi + .dat)

Full Geochemistry

major_ions_equilibrium.pqi
nitrogen_speciation.pqi
phosphorus_minerals.pqi
trace_metals.pqi
dissolved_oxygen_kinetics.pqi
pH_alkalinity_kinetics.pqi
phytoplankton_kinetics.pqi
sediment_diagenesis_kinetics.pqi
wetland_processing_kinetics.pqi
emerging_contaminants.pqi

+ phreeqc.dat database

Location: supporting_scripts/Model_Config/config_support_lib/BGC_templates/

04

Transport Configuration

Step 4: Configure Transport

{
  "MODULE_NAME": "OPENWQ_NATIVE_TRANSP_DISS_ADVDISP",

  // Dispersion coefficients
  "ADVDISP_CONFIGURATION": {
    "dispersion_x": 10.0,  // m²/s
    "dispersion_y": 1.0,
    "dispersion_z": 0.1,
    "characteristic_length_m": 100.0
  },

  // Lateral exchange between compartments
  "BOUNDMIX_CONFIGURATION": {
    "1": {
      "DIRECTION": "z",
      "UPPER_COMPARTMENT": "RUNOFF",
      "LOWER_COMPARTMENT": "SOIL",
      "K_VAL": 0.001
    },
    "2": {
      "DIRECTION": "z",
      "UPPER_COMPARTMENT": "SOIL",
      "LOWER_COMPARTMENT": "GROUNDWATER",
      "K_VAL": 0.0001
    }
  }
}

Transport Module Options

ADVDISP	Advection + Dispersion
ADV	Advection only
NONE	No transport

Lateral Exchange

K_VAL controls mixing rate between adjacent compartments (1/s)

Higher K → faster exchange
Direction: x, y, or z

05

Run the Model

Step 5: Run the Model

                            HTML Report: The model_config_template.py generates an interactive HTML report with ready-to-copy Docker commands — paths are auto-filled from your template configuration.
                        

Running with Docker (via mpirun)

# General pattern (auto-filled in the HTML report)
docker exec docker_openwq /bin/bash -c \
  "cd <output_dir> && \
   mpirun --allow-run-as-root -np 2 \
   <executable> <control_file>"

# Example with actual paths
docker exec docker_openwq /bin/bash -c \
  "cd /code/my_project && \
   mpirun --allow-run-as-root -np 2 \
   /code/bin/mizuroute_openwq_Release \
   /code/my_project/mizuroute.control"

                            Important: mizuRoute requires mpirun -np 2 (minimum 2 MPI processes) for domain decomposition. Do not use -g 1 1 -m flags.
                        

What the HTML Report Provides

Configuration summary (modules, species, solver)
Interactive basin map with GRQA stations
Source/sink setup details
Ready-to-copy Docker commands
Python snippets to read & visualize results

Expected Output

In openwq_out/ folder:

RIVER@NO3_N#mg_L.h5
RIVER@NH4_N#mg_L.h5
Log_OpenWQ.txt

HDF5 naming: {COMPARTMENT}@{SPECIES}#{UNITS}.h5

Setup Checklist

Configuration Files

Create master JSON with project metadata
Configure computational settings (threads)
Define compartments and cycling frameworks
Set initial conditions (JSON or HDF5)
Configure BGC module with species and reactions
Set up transport parameters
Configure output settings (format, species, timestep)

Optional Components

Add source/sink loading files
Configure external water flux chemistry
Set up PHREEQC if using geochemistry
Configure sediment transport module
Add sorption isotherms

Execution

Start Docker container
Review the HTML report for configuration summary
Copy Docker run command from report and execute
Use Python snippets from report to visualize results

Common Issues & Solutions

Issue	Solution
File not found errors	Check paths are relative to master JSON location
Unknown compartment name	Ensure compartment names match host model exactly
Species not defined	Add species to CHEMICAL_SPECIES list before referencing
Kinetics expression error	Check exprtk syntax — use ^ for power, not **
Negative concentrations	Reduce timestep or check reaction rates
No output produced	Check OPENWQ_OUTPUT species list matches defined species

Debugging Tip: Set "RUN_MODE_DEBUG": true for verbose logging

Summary

📁 Organize

Create directory structure with openwq_in/ and openwq_out/ folders

📝 Configure

Edit model_config_template.py — generates JSON configs + interactive HTML report

🚀 Execute

Copy Docker commands from report, run model, use Python snippets to visualize

                    The HTML report is your central hub — review configuration, run the model, and visualize results from copy-paste code.
                

Thank You

Questions?

Documentation: openwq.readthedocs.io