Master Configuration

The master configuration is a JSON file that provides OpenWQ with the information and instructions to run a simulation. It references all other input files and controls which modules are enabled. The major blocks are described below.

General Project Information

Top-level keys that identify the simulation.

PROJECT_NAME	Project name string
GEOGRAPHICAL_LOCATION	Project location string
AUTHORS	Model run authors
DATE	Model run date
COMMENT	Additional documentation information

COMPUTATIONAL_SETTINGS

RUN_MODE_DEBUG	Run in debug mode with extra console output (true/false)
USE_NUM_THREADS	"all" or integer number of threads to use (e.g., 4)

SOLVER

Top-level key that selects the numerical solver.

"FORWARD_EULER" | Forward Euler explicit solver (first-order)

"SUNDIALS" | SUNDIALS CVode adaptive multi-step solver

See Numerical Solvers for details.

OPENWQ_INPUT

References the main configuration file, external water fluxes, and sink/source forcing files.

CONFIG_FILEPATH

CONFIG_FILEPATH

Path to Configuration file

EXTERNAL_WATER_FLUXES

Numbered pairs of LABEL and FILEPATH for external water flux input files. Each entry references a Source/Sink & External Fluxes file. Optional.

(#) -> LABEL	Label identifying this flux entry
(#) -> FILEPATH	Path to the external water fluxes JSON file

SINK_SOURCE

Numbered pairs of LABEL and FILEPATH for chemical source/sink input files. Each entry references a Source/Sink file. Optional.

(#) -> LABEL	Label identifying this source/sink entry
(#) -> FILEPATH	Path to the source/sink JSON file

MODULES

Selects which process modules to enable and points to their configuration files. Each module sub-block contains a MODULE_NAME and a MODULE_CONFIG_FILEPATH.

BIOGEOCHEMISTRY

MODULE_NAME	NATIVE_BGC_FLEX or PHREEQC
MODULE_CONFIG_FILEPATH	Path to biogeochemistry config file

See Modules.

TRANSPORT_DISSOLVED

See Modules.

LATERAL_EXCHANGE

MODULE_NAME	NATIVE_LE_BOUNDMIX or NONE
MODULE_CONFIG_FILEPATH	Path to lateral exchange config file

See Modules.

TRANSPORT_SEDIMENTS

See Modules.

SORPTION_ISOTHERM

MODULE_NAME	FREUNDLICH, LANGMUIR, or NONE
SEDIMENT_COMPARTMENT	Compartment name for sorption processes
MODULE_CONFIG_FILEPATH	Path to sorption isotherm config file

See Modules.

OPENWQ_OUTPUT

Controls the output format, species, compartments, and temporal resolution.

COMPARTMENTS_AND_CELLS

Each compartment is a sub-key under COMPARTMENTS_AND_CELLS. Cell selection can use "all" for all cells or numbered entries with [ix, iy, iz] indices.

Example

{
    "PROJECT_NAME": "steppler_N",
    "GEOGRAPHICAL_LOCATION": "steppler",
    "AUTHORS": "Author Name",
    "DATE": "March_2024",
    "COMMENT": "Example simulation",
    "COMPUTATIONAL_SETTINGS": {
        "RUN_MODE_DEBUG": true,
        "USE_NUM_THREADS": 4
    },
    "SOLVER": "FORWARD_EULER",
    "OPENWQ_INPUT": {
        "CONFIG_FILEPATH": "openwq_in/openWQ_config.json",
        "EXTERNAL_WATER_FLUXES": {
            "1": {
                "LABEL": "SUMMA",
                "FILEPATH": "openwq_in/openwq_EWF_mizu.json"
            }
        },
        "SINK_SOURCE": {
            "1": {
                "LABEL": "fertilizer_N",
                "FILEPATH": "openwq_in/openWQ_fertilizer_N.json"
            }
        }
    },
    "MODULES": {
        "BIOGEOCHEMISTRY": {
            "MODULE_NAME": "NATIVE_BGC_FLEX",
            "MODULE_CONFIG_FILEPATH": "openwq_in/openWQ_MODULE_BGC.json"
        },
        "TRANSPORT_DISSOLVED": {
            "MODULE_NAME": "NATIVE_TD_ADV",
            "MODULE_CONFIG_FILEPATH": "openwq_in/openWQ_MODULE_TD.json"
        },
        "LATERAL_EXCHANGE": {
            "MODULE_NAME": "NATIVE_LE_BOUNDMIX",
            "MODULE_CONFIG_FILEPATH": "openwq_in/openWQ_MODULE_LE.json"
        },
        "TRANSPORT_SEDIMENTS": {
            "MODULE_NAME": "NONE",
            "SEDIMENT_COMPARTMENT": "RIVER_NETWORK_REACHES",
            "MODULE_CONFIG_FILEPATH": "openwq_in/openWQ_MODULE_TS.json"
        },
        "SORPTION_ISOTHERM": {
            "MODULE_NAME": "NONE",
            "SEDIMENT_COMPARTMENT": "SUMMA_RUNOFF",
            "MODULE_CONFIG_FILEPATH": "openwq_in/openWQ_MODULE_SI.json"
        }
    },
    "OPENWQ_OUTPUT": {
        "RESULTS_FOLDERPATH": "openwq_out",
        "FORMAT": "HDF5",
        "CHEMICAL_SPECIES": ["NO3-N", "NH4-N"],
        "UNITS": "MG/L",
        "NO_WATER_CONC_FLAG": -9999,
        "EXPORT_SEDIMENT": false,
        "COMPARTMENTS_AND_CELLS": {
            "RIVER_NETWORK_REACHES": {
                "1": ["all", "all", "all"]
            }
        },
        "TIMESTEP": [1, "hour"]
    }
}

The JSON file supports C/C++ syntax for comments: single-line comment (//) or comment blocks (/* and */).

The symbol (#) refers to an integer number sequence.