Repository Structure

This page describes the organization of the OpenWQ GitHub repository to help you navigate the codebase.

openwq/
├── containers/              # Container definitions for Docker and Apptainer
│   ├── Dockerfile           # Docker image build instructions
│   ├── docker-compose.yml   # Docker Compose configuration
│   └── openwq_apptainer.def # Apptainer/Singularity definition file
│
├── src/                     # C++ source code
│   ├── compute/             # Core computational routines
│   ├── extwatflux_ss/       # External water flux and source/sink handling
│   ├── models_CH/           # Chemistry/BGC module implementations
│   ├── models_LE/           # Lateral exchange module
│   ├── models_SI/           # Sorption isotherm module
│   ├── models_TD/           # Transport dissolved module
│   ├── models_TS/           # Transport sediment module
│   └── output/              # Output handling routines
│
├── supporting_scripts/      # Python tools for configuration and analysis
│   ├── Model_Config/        # Configuration file generators
│   │   ├── model_config_template.py    # Main configuration template
│   │   └── config_support_lib/         # Generator libraries
│   ├── Read_Outputs/        # Post-processing and visualization
│   │   ├── reading_plotting_results_template.py
│   │   └── hdf5_support_lib/           # HDF5 reader, plotter, mapper
│   └── Calibration/         # Calibration and sensitivity analysis
│       ├── calibration_config_template.py  # Calibration configuration template
│       └── calibration_lib/            # Optimization algorithms and drivers
│
├── openwq_in_a_nutshell/    # Interactive HTML presentations
│   ├── 1_OpenWQ_Overview.html
│   ├── 2_Biogeochemistry_Engines.html
│   ├── 3_Sources_Sinks_Loads.html
│   ├── 4_Model_Setup_Guide.html
│   ├── 5_Calibration_Guide.html
│   └── 6_Supporting_Scripts.html
│
├── json_files_repos/        # Example JSON configuration files
│
├── testing/                 # Test cases and validation
│
├── utils/                   # Utility scripts (compilation helpers)
│
├── wikipage/                # Documentation source (Sphinx/RST)
│   └── source/              # RST files for ReadTheDocs
│
├── CMakeLists.txt           # Main CMake build configuration
├── main.cpp                 # Entry point (standalone mode)
├── README.md                # Quick start guide
└── LICENSE                  # GNU GPL v3 license

Folder Descriptions

containers/

Contains all containerization files for running OpenWQ in isolated environments:

  • Dockerfile: Builds a Docker image with Ubuntu 24.04, all dependencies pre-installed (PHREEQC-RM, SUNDIALS, Armadillo, ParallelIO)

  • docker-compose.yml: Simplifies container management with volume mounts

  • openwq_apptainer.def: Definition file for Apptainer/Singularity (used on HPC clusters)

To build with Docker:

cd containers
docker-compose build
docker-compose up -d

To build with Apptainer:

cd containers
apptainer build openwq.sif openwq_apptainer.def

src/

The C++ source code organized by module:

  • compute/: Core solver routines, time stepping, parallel execution

  • extwatflux_ss/: Parsing and application of external water fluxes and source/sink terms

  • models_CH/: Biogeochemistry implementations (NATIVE_BGC_FLEX, PHREEQC)

  • models_LE/: Lateral exchange between compartments

  • models_SI/: Sorption isotherm calculations (Freundlich, Langmuir)

  • models_TD/: Dissolved transport (advection, dispersion)

  • models_TS/: Sediment transport (HYPE-based erosion models)

  • output/: HDF5/CSV output generation

supporting_scripts/

Python tools organized into three main categories. All scripts require Python 3.8+ with dependencies.

Environment Setup:

cd supporting_scripts
./setup_venv.sh           # Create virtual environment
source .venv/bin/activate # Activate environment

Or with conda:

conda create -n openwq python=3.10
conda activate openwq
pip install -r requirements.txt

Available Tools:

  1. Model_Config/: Generate all JSON configuration files from a single Python template

    • model_config_template.py: Edit this file to configure your model

    • Run it to auto-generate all required JSON files

  2. Read_Outputs/: Post-processing and visualization

    • Read_h5_driver.py: Load HDF5 output files into Python

    • Plot_h5_driver.py: Create time series plots

    • Map_h5_driver.py: Generate spatial maps and animated GIFs

  3. Calibration/: Parameter optimization and sensitivity analysis

    • Morris screening for parameter importance

    • Sobol variance-based sensitivity analysis

    • DDS (Dynamically Dimensioned Search) optimization

    • HPC templates for SLURM/PBS clusters

openwq_in_a_nutshell/

Interactive HTML presentations that can be viewed in any web browser. Use arrow keys to navigate. Topics include:

  1. Overview of OpenWQ architecture

  2. Biogeochemistry engines (NATIVE_BGC_FLEX, PHREEQC)

  3. Source/sink and load configuration options

  4. Model setup step-by-step guide

  5. Calibration and sensitivity analysis guide

  6. Supporting scripts usage guide

wikipage/

Documentation source files in reStructuredText (RST) format. These are built by Sphinx and hosted on ReadTheDocs. To build locally:

cd wikipage
pip install -r requirements.txt
make html

Key Files

  • CMakeLists.txt: CMake build configuration. Set COMPILE_TARGET and SOLVER_TYPE here.

  • main.cpp: Standalone entry point (used when OpenWQ runs independently, not coupled to a host model)

  • README.md: Quick start guide with compilation and Docker instructions

  • .readthedocs.yaml: Configuration for automatic documentation builds