Configuration Reference

HydroRaVENS is configured entirely through a YAML file. This page documents all available options.

Configuration File Structure

timeseries:
    # Data input section

initial_conditions:
    # Starting state of reservoirs and snowpack

catchment:
    # Basin properties

general:
    # Simulation settings

reservoirs:
    # Reservoir cascade configuration

snowmelt:
    # Required section; snowpack processes are only active if
    # Mean Temperature [C] is present in the input CSV

The `timeseries` section

Option	Type	Description
`datafile`	string	Path to CSV input file with daily time series

Example:

timeseries:
    datafile: data/streamflow_2010_2020.csv

The `initial_conditions` section

Option	Type	Description
`water_reservoir_effective_depths__mm`	list of floats	Initial water depth (mm) in each reservoir, listed top to bottom
`snowpack__mm_SWE`	float	Initial snowpack depth in mm snow-water equivalent (SWE)

Example:

initial_conditions:
    water_reservoir_effective_depths__mm:
        - 150    # Top (soil) reservoir starts at 150 mm
        - 400    # Bottom (groundwater) starts at 400 mm
    snowpack__mm_SWE: 50  # 50 mm SWE initially

The `catchment` section

Option	Type	Description
`drainage_basin_area__km2`	float	Basin area (km²); used for discharge-to-depth conversion
`evapotranspiration_method`	string	`datafile` or `ThorntwaiteChang2019`. See note below.
`water_year_start_month`	int	Month (1–12) when water year begins (10 = October for USGS)
`baseflow_Q`	float	Constant regional groundwater import (mm/day). Added to modeled discharge after routing; not mass-balanced against P or ET. Default `0.0` (disabled). Use only when independent hydrogeological evidence supports an external groundwater source.

Note

ThorntwaiteChang2019 requires long-term monthly temperature normals to compute the Thornthwaite heat index \(I\) and exponent \(a\). If normals are not supplied via T_monthly_normals in the Buckets constructor, they are computed automatically from the mean monthly temperatures in the input record. A UserWarning is raised when the record is shorter than 20 years, as a short period may not represent long-term climatology. For best results, supply normals from a 30-year reference period (e.g. WMO 1991–2020 normals).

Water years with no discharge observations receive an ET multiplier of 1.0 (raw ET, no water-balance correction) with a UserWarning naming the affected years.

Example:

catchment:
    drainage_basin_area__km2: 3800
    evapotranspiration_method: datafile
    water_year_start_month: 10
    baseflow_Q: 0.0   # disabled; set > 0 for regional groundwater import

The `general` section

Option	Type	Description
`spin_up_cycles`	int or `null`	Number of complete passes through data before the main run. Use 0 to skip spin-up (e.g. when supplying `initial_states` for chained decade runs). `null` (or omitting the key when calling `run_and_score()`) triggers automatic calculation: `ceil(τ_max / record_length)`, where `τ_max` is the longest reservoir e-folding time. Because initial conditions are set to analytical steady-state depths, one e-folding time is sufficient to resolve seasonal and inter-annual climate memory.
`et_alpha`	float	Fraction (0–1) of potential ET drawn from the top (soil) reservoir when `et_reservoir_draw: true`. The remainder `1 − et_alpha` is drawn from the second reservoir. Default `1.0` (all ET from top reservoir). Has no effect when `et_reservoir_draw: false`. See ET Module Parameters.
`direct_runoff_fraction`	float	Fast-bypass fraction (0–1) of positive daily recharge that exits directly as runoff, bypassing the reservoir cascade. Active only when `direct_runoff: true` in the `modules` block. Default `0.0` (disabled). Also settable as a calibration parameter via `run_and_score()`.
`enforce_water_balance`	string	Controls how ET is scaled to close the water balance. Default `'water-year'` if the key is absent. Accepted values: `'water-year'` — scale ET by a per-water-year multiplier so that P − Q − ET = 0 over each water year. `'global'` — scale ET by a single multiplier computed from the full record (sum(P − Q) / sum(ET_raw)). No per-year overfitting; does not add hidden degrees of freedom to AIC comparisons. Recommended when calibrating with a long record and comparing models by AIC. `'none'` — use raw ET without any correction. Appropriate only when supplying trusted measured ET (e.g. eddy covariance). Using `'none'` with `ThorntwaiteChang2019` raises a warning because Thornthwaite ET carries large systematic biases. Also appropriate when `et_scale` is a free calibration parameter (see ET Module Parameters). Legacy boolean values are accepted: `true` maps to `'water-year'` and `false` maps to `'none'`.

Example:

general:
    spin_up_cycles: 2                  # Run through data twice to initialize
    enforce_water_balance: water-year  # default; omit to accept the default
    et_alpha: 1.0                      # fraction of ET from top reservoir (et_reservoir_draw only)
    direct_runoff_fraction: 0.0        # fast-bypass fraction (direct_runoff module only)

The `reservoirs` section

This section defines the cascade of linear reservoirs (1 or more). All lists must have the same length.

Option	Type	Description
`e_folding_residence_times__days`	list of floats	Drainage time constant (days) for each reservoir
`exfiltration_fractions`	list of floats	Fraction (0–1) of drainage exiting as discharge
`maximum_effective_depths__mm`	list of floats	Storage capacity (mm) per reservoir; use `.inf` for unlimited
`pdm_H0__mm`	list of floats or `null`	PDM characteristic depth (mm) per reservoir. When set for a reservoir, a fraction \(f_\text{sat} = 1 - e^{-H / H_0}\) of incoming recharge becomes saturation-excess runoff. `null` (or omitting the entry) disables PDM for that reservoir. Default: all `null` (PDM off). Mutually exclusive with a finite `maximum_effective_depths__mm` entry for the same reservoir.
`tile_fractions`	list of floats	Fraction (0–1) of infiltrating water diverted to a fast tile-drain sub-reservoir, per main reservoir. Default: all `0.0` (no tile drainage). When non-zero, the corresponding `tile_residence_times__days` entry must also be set.
`tile_residence_times__days`	list of floats or `null`	E-folding residence time (days) of the tile-drain sub-reservoir per main reservoir. Required when the corresponding `tile_fractions` entry is greater than zero; ignored otherwise. Default: all `null`.
`recession_exponents`	list of floats	Power-law recession exponent \(b\) per reservoir. \(b = 1\) recovers the standard linear reservoir; \(b > 1\) produces concave recession limbs consistent with subsurface flow theory (Brutsaert & Nieber 1977; Kirchner 2009). The theoretical value for catchment-integrated baseflow recession is \(b \approx 2.2\) (Brutsaert & Nieber 1977); calibrated soil-zone values are typically larger (\(b \approx 3\)–5). Default: all `1.0` (linear). Also overridable per calibration run via `run_and_score()`. See Model Description for theory and Recession Analysis for estimating b from observed streamflow.

Example:

reservoirs:
    e_folding_residence_times__days:
        - 16      # Interflow: fast lateral drainage, days to weeks
        - 200     # Soil zone: seasonal storage, months
        - 3650    # Groundwater: multi-year storage
    exfiltration_fractions:
        - 0.8     # 80% to stream, 20% percolates to soil zone
        - 0.1     # 10% to stream, 90% recharges groundwater
        - 1.0     # All exits as baseflow
    maximum_effective_depths__mm:
        - .inf
        - .inf
        - .inf

No reservoir is fixed to a particular process; physical meaning is set by the parameters. Successive reservoirs naturally span progressively longer storage timescales — from interflow (days) to soil moisture (months) to groundwater (years) — but that mapping is the user’s choice.

The `snowmelt` section

This section is always required in the configuration file. Snowpack processes are only activated when Mean Temperature [C] is present in the input CSV, but the PDD_melt_factor key must be present regardless.

Option	Type	Description
`PDD_melt_factor`	float	Melt rate (mm SWE per °C per day)
`fgi_decay_coeff`	float	Maximum daily FGI decay rate \(A_0\) (default `0.97`, Molnau & Bissell 1983). When `Minimum Temperature [C]` and `Maximum Temperature [C]` are present in the input CSV, the effective per-day coefficient \(A_t\) is computed from the diurnal temperature range: \(A_t = 1 - (1-A_0)\,f_{\text{above}}\), where \(f_{\text{above}}\) is the fraction of the day above 0°C (linear diurnal cycle). On all-below-zero days \(A_t = 1\) (no decay); on days that straddle 0°C, \(A_t\) decreases toward \(A_0\). This makes FGI accumulation persistent in continental climates and decay-bounded in maritime ones. Without T_min/T_max, falls back to constant \(A_0\) (original M&B behaviour).
`fdd_threshold`	float	Frozen ground index (FGI) threshold (°C·day) above which the top reservoir’s lateral drainage is blocked and all water exits as direct runoff (Molnau & Bissell 1983). The FGI accumulates freezing degree-days and decays during thaw; when it exceeds this threshold the soil is considered frozen. Default `inf` (frozen ground never triggers). Requires `frozen_ground: true` in the `modules` block and temperature data. Typically calibrated; literature values for agricultural soils range from ~50–200 °C·day. Also overridable via `run_and_score()`. Do not calibrate simultaneously with `snow_insulation_k` — see Model Description.
`snow_insulation_k`	float	Snow insulation decay constant (mm⁻¹ SWE). Scales effective air temperature reaching the soil as \(T_\text{eff} = T \cdot e^{-k \cdot \text{SWE}}\), reducing FGI accumulation under deep snowpack. Default `0.0` (no insulation). The exponential form originates in Molnau & Bissell (1983); LISFLOOD uses ~0.057 mm⁻¹ (van der Knijff et al. 2010) as a literature starting point. Do not calibrate simultaneously with `fdd_threshold` — the two parameters are correlated and will produce equifinal solutions. Fix one from independent data before calibrating the other; see Model Description.

Example:

snowmelt:
    PDD_melt_factor: 1.0     # 1 mm SWE melts per °C per day
    fdd_threshold: 83.0      # °C·day; calibrate or fix from soil data
    snow_insulation_k: 0.057 # LISFLOOD default; set 0.0 to disable

The `modules` section

Optional process modules can be enabled or disabled through the modules block. All keys default to the values shown below if the block is absent.

Key	Type	Default	Description
`snowpack`	bool	`true`	Accumulation, melt (PDD), and rain-on-snow. Requires `Mean Temperature [C]` in the input CSV; silently inactive if the column is absent regardless of this flag.
`frozen_ground`	bool	`true`	Frozen ground index (FGI; Molnau & Bissell 1983). Accumulates freezing degree-days; blocks shallow-to-soil infiltration when the index exceeds `fdd_threshold`. Requires `snowpack: true` and temperature data.
`rain_on_snow`	bool	`true`	Sensible-heat contribution of warm rain falling on snowpack. Only active when `snowpack: true`.
`direct_runoff`	bool	`false`	Hortonian-inspired fast-bypass fraction. A fixed fraction (`f_direct_runoff`) of positive daily recharge bypasses the reservoir cascade entirely. Conceptually motivated by infiltration-excess overland flow, but not a rigorous physical representation at the daily timestep.
`dtr_fgi_decay`	bool	`true`	DTR-based FGI decay coefficient. When enabled and `Minimum Temperature [C]` / `Maximum Temperature [C]` columns are present, the per-day FGI decay coefficient \(A_t\) varies with the diurnal temperature range rather than being held constant at `fgi_decay_coeff`. Disable to revert to constant \(A_0\) (original Molnau & Bissell 1983 behaviour). Has no effect when T_min/T_max columns are absent or when `frozen_ground: false`.
`et_water_stress`	bool	`false`	Soil-moisture-dependent ET. Actual ET is multiplied by \(1 - e^{-H_0 / H_{\text{pdm}}}\), where \(H_0\) is the current storage in the top reservoir and \(H_{\text{pdm}}\) is its PDM characteristic depth (`pdm_H0__mm`). ET approaches potential ET as the reservoir fills and drops to zero as it empties. Mutually exclusive with `et_reservoir_draw`; if both are set, `et_reservoir_draw` takes precedence.
`et_reservoir_draw`	bool	`false`	Post-cascade reservoir ET extraction. Instead of subtracting ET from precipitation before it enters the reservoir cascade, ET is drawn directly from reservoir storage after drainage. Partitioned between the top two reservoirs by `et_alpha` (see ET Module Parameters). Supports a wilting-point threshold (`wp_soil`, `wp_soil_sigma`) below which soil-reservoir ET extraction is reduced or blocked. Mutually exclusive with `et_water_stress`.

Example:

modules:
    snowpack:          true
    frozen_ground:     true
    rain_on_snow:      true
    direct_runoff:     false   # off by default
    dtr_fgi_decay:     true    # on by default; disable for continental climates with A=1
    et_water_stress:   false   # off by default; enable for soil-moisture-limited ET
    et_reservoir_draw: false   # off by default; enable for post-cascade reservoir ET

When a module is disabled, its associated parameter (e.g. PDD_melt_factor when snowpack: false) has no effect and need not be calibrated.

ET Module Parameters

The parameters below are calibration parameters associated with the ET modules. They are passed to run_and_score() rather than read directly from the YAML file (except et_alpha, which may also be set in the general block).

Parameter	Type	Description
`et_scale`	float	Global ET multiplier. Scales potential ET up or down uniformly across the entire record. Active (calibrated) only when `et_water_stress: true` or `et_reservoir_draw: true` and `enforce_water_balance: 'none'` in the driver. Incompatible with `'water-year'` or `'global'` water-balance enforcement (those modes compute their own multiplier). Default `1.0`.
`et_alpha`	float	Fraction (0–1) of potential ET extracted from the top (soil) reservoir; `1 − et_alpha` is extracted from the second reservoir. Active only when `et_reservoir_draw: true`. Default `1.0`. May also be set as `et_alpha` in the `general` YAML block.
`wp_soil`	float	Wilting-point threshold (mm water depth) for the soil reservoir when `et_reservoir_draw: true`. ET extraction from the soil reservoir is reduced or blocked when storage falls below this value. Default `0.0` (no wilting point). When `wp_soil_sigma` is also set, a smooth Gaussian-CDF transition replaces the hard threshold.
`wp_soil_sigma`	float	Standard deviation (mm) of the spatially distributed wilting-point threshold. When `> 0`, the fraction of the catchment below wilting point is modeled as a Gaussian CDF centered on `wp_soil` with standard deviation `wp_soil_sigma`, and ET extraction is reduced proportionally. Default `0.0` (hard threshold). Requires `wp_soil > 0`.

Complete Example

timeseries:
    datafile: data/input.csv

initial_conditions:
    water_reservoir_effective_depths__mm: [2, 400]
    snowpack__mm_SWE: 0

catchment:
    drainage_basin_area__km2: 3800
    evapotranspiration_method: ThorntwaiteChang2019  # normals auto-computed if not supplied
    water_year_start_month: 10
    baseflow_Q: 0.0   # mm/day regional groundwater import; 0 = disabled

general:
    spin_up_cycles: null  # auto: ceil(tau_max / record_length)

reservoirs:
    e_folding_residence_times__days: [16, 2000]
    exfiltration_fractions: [0.8, 1.0]
    maximum_effective_depths__mm: [.inf, .inf]

snowmelt:
    PDD_melt_factor: 1.0
    fgi_decay_coeff: 0.97       # default; Molnau & Bissell (1983)
    fdd_threshold: .inf         # °C·day; .inf = frozen ground never triggers
    snow_insulation_k: 0.0      # mm⁻¹ SWE; 0 = disabled

modules:
    snowpack:          true
    frozen_ground:     true
    rain_on_snow:      true
    direct_runoff:     false
    dtr_fgi_decay:     true
    et_water_stress:   false   # soil-moisture-dependent ET
    et_reservoir_draw: false   # post-cascade reservoir ET extraction

Illustrative Starting Points

These are rough starting points only, not calibrated or validated parameter sets. Actual values depend strongly on the specific catchment.

Alpine watershed with snowpack:

reservoirs:
    e_folding_residence_times__days: [8, 1500]
    exfiltration_fractions: [0.7, 1.0]

snowmelt:
    PDD_melt_factor: 1.5

catchment:
    evapotranspiration_method: ThorntwaiteChang2019

Humid lowland catchment:

reservoirs:
    e_folding_residence_times__days: [25, 3000]
    exfiltration_fractions: [0.9, 1.0]

catchment:
    evapotranspiration_method: datafile

Arid/semi-arid watershed:

reservoirs:
    e_folding_residence_times__days: [3, 500]
    exfiltration_fractions: [0.5, 1.0]

snowmelt:
    PDD_melt_factor: 0.5

Configuration Reference

Configuration File Structure

The timeseries section

The initial_conditions section

The catchment section

The general section

The reservoirs section

The snowmelt section

The modules section

ET Module Parameters

Complete Example

Illustrative Starting Points

The `timeseries` section

The `initial_conditions` section

The `catchment` section

The `general` section

The `reservoirs` section

The `snowmelt` section

The `modules` section