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__m	list of floats	Initial water depth (m) in each reservoir, listed top to bottom
snowpack__m_SWE	float	Initial snowpack depth in m snow-water equivalent (SWE)

Example:

initial_conditions:
    water_reservoir_effective_depths__m:
        - 1.5    # Top (soil) reservoir starts at 1.5 m
        - 200    # Bottom (groundwater) starts at 200 m
    snowpack__m_SWE: 0.5  # 0.5 m 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
water_year_start_month	int	Month (1–12) when water year begins (10 = October for USGS)

Example:

catchment:
    drainage_basin_area__km2: 3800
    evapotranspiration_method: datafile
    water_year_start_month: 10

The general section

Option	Type	Description
scalar_dt	bool	Required field; set to true. The model always enforces a 1-day time step regardless of this value.
spin_up_cycles	int	Number of complete passes through data before the main run. Use 0 to skip spin-up.

Example:

general:
    scalar_dt: true
    spin_up_cycles: 2  # Run through data twice to initialize

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__m	list of floats	Storage capacity (m) per reservoir; use .inf for unlimited

Example:

reservoirs:
    e_folding_residence_times__days:
        - 16      # Soil: drains in ~16 days
        - 2000    # Groundwater: drains in ~2000 days
    exfiltration_fractions:
        - 0.8     # 80% to river, 20% to next layer
        - 1.0     # 100% to river (should be 1.0; warning issued if not)
    maximum_effective_depths__m:
        - .inf
        - .inf

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)

Example:

snowmelt:
    PDD_melt_factor: 1.0  # 1 mm SWE melts per °C per day

Complete Example

timeseries:
    datafile: data/input.csv

initial_conditions:
    water_reservoir_effective_depths__m: [2, 400]
    snowpack__m_SWE: 0

catchment:
    drainage_basin_area__km2: 3800
    evapotranspiration_method: ThorntwaiteChang2019  # requires T_monthly_normals in Python
    water_year_start_month: 10

general:
    scalar_dt: true
    spin_up_cycles: 1

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

snowmelt:
    PDD_melt_factor: 1.0

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