API Reference
Buckets
The primary class for running a watershed simulation.
- class hydroravens.Buckets(T_monthly_normals=None)[source]
Bases:
objectIncorporates a list of reservoirs into a linear hierarchy that sends water either downwards or out to the surface. Reservoirs are ordered from top (nearest Earth’s surface) to bottom (deepest groundwater); this order controls the direction of infiltration between layers.
- __init__(T_monthly_normals=None)[source]
Initialize the watershed model.
If using the ThorntwaiteChang2019 ET method, pass T_monthly_normals here so that the thermal index I and exponent a are computed once from climatological normals and remain fixed throughout the simulation.
- Parameters:
T_monthly_normals (array-like of length 12, optional) – Long-term mean monthly temperatures (°C) used to compute the Thornthwaite thermal index I and exponent a per Chang et al. (2019), https://doi.org/10.1002/ird.2309. Required when evapotranspiration_method is ‘ThorntwaiteChang2019’.
- export_Hlist()[source]
Return the current water depths in all subsurface reservoirs.
Useful for checkpointing reservoir state between a spin-up run and the main simulation, or for restarting a paused run.
- initialize(config_file=None)[source]
Set up the model from a YAML configuration file.
Reads the configuration file, loads the input time series, builds the reservoir stack, instantiates snowpack if temperature data are present, computes the water-year ET multiplier, and runs any requested spin-up cycles. Part of the CSDMS Basic Model Interface.
- Parameters:
config_file (str, optional) – Path to the YAML configuration file. If None, all required values must be set on the object directly before calling update().
- compute_water_year()[source]
Assign a water-year label to each row in self.hydrodata.
Adds a ‘Water Year’ column. A water year begins on water_year_start_month and is labelled by the calendar year in which it ends. For example, with a start month of October (USGS convention), 1 Oct 2020 – 30 Sep 2021 is water year 2021.
- compute_ET_multiplier()[source]
Compute per-water-year ET scaling factors to enforce water balance.
For each water year, computes the ratio of required ET (P - Q) to measured or computed ET, and stores this as ‘ET multiplier’ in self.hydrodata_WY_means. This multiplier is later applied in compute_ET() to scale ET so that P - Q - ET ≈ 0 over each water year.
- compute_ET()[source]
Build the water-balance-adjusted ET time series used in the model.
Assembles ET in two steps:
Obtain raw daily ET from the input data file or the Thornthwaite–Chang 2019 equation (see evapotranspiration_Chang2019()).
Scale raw ET by the per-water-year multiplier from compute_ET_multiplier() so that P - Q - ET ≈ 0 in each water year.
The result is stored as ‘ET for model [mm/day]’ in self.hydrodata.
- update(time_step=None)[source]
Advance the model by one time step.
Routes precipitation minus ET through the snowpack (if present) and then through each subsurface reservoir in order from shallowest to deepest. Stores modeled specific discharge, snowpack SWE, and total subsurface storage in self.hydrodata for the current time step. Part of the CSDMS Basic Model Interface.
NOTE FALLACY: recharging before discharging, even though during the same time step. Consider changing to use half-recharge from each time step.
FOR LATER: , dt_at_timestep=self.dt FOR SOONER: WATER-YEAR BALANCE
- Parameters:
time_step (int, optional) – Index into self.hydrodata for the time step to update. If None, uses and then increments the internal counter self._timestep_i.
- evapotranspiration_Chang2019(Tmax=None, Tmin=None, photoperiod=None, k=0.69)[source]
Modified daily Thornthwaite ET₀ equation.
Chang et al. (2019), Eq. 1–4. https://doi.org/10.1002/ird.2309
- Parameters:
Tmax (array-like) – Daily maximum temperature (°C).
Tmin (array-like) – Daily minimum temperature (°C).
photoperiod (array-like) – Photoperiod N (hours), computed from latitude and Julian day per Allen et al. (1998), Eqs. 2–4 of Chang et al. (2019).
k (float) – Calibration coefficient in the T_ef formula. Default 0.69, recommended by Pereira & Pruitt (2004) for daily ET₀ (https://doi.org/10.1016/j.agrformet.2004.01.005). Use 0.72 for monthly ET₀ per Camargo et al. (1999).
- Returns:
ET0 – Daily reference evapotranspiration (mm day⁻¹).
- Return type:
array-like
- run()[source]
Advance the model through all time steps in self.hydrodata.
Resets the internal time counter to the first row before iterating, so run() is safe to call more than once (e.g. spin-up then main run). Captures storage at the start of the run for check_mass_balance(). Part of the CSDMS Basic Model Interface.
- finalize()[source]
Report model skill and display output plots.
Calls compute_NSE(verbose=True) to print the Nash–Sutcliffe Efficiency to stdout, then calls plot() to display a time-series comparison of observed and modeled specific discharge. Part of the CSDMS Basic Model Interface.
- plot()[source]
Display a time-series comparison of precipitation and specific discharge.
Produces a dual-axis figure: precipitation as a bar chart on the left axis and both observed and modeled specific discharge as line plots on the right axis.
- check_mass_balance(time_step=None)[source]
Compute the mass-balance discrepancy at a given time step.
Compares cumulative inputs (P - ET) from the start of the record through time_step with cumulative outputs (discharge) plus current storage (snowpack + subsurface reservoirs) and any carried-over deficit. Returns the excess mass still in the model; a value near zero indicates good mass conservation.
- compute_NSE(return_nse=True, verbose=False)[source]
Compute the Nash–Sutcliffe Efficiency of the discharge simulation.
Compares modeled and observed specific discharge for all time steps where both values are non-missing. Stores the result as self.NSE.
- Parameters:
- Returns:
NSE – Nash–Sutcliffe Efficiency coefficient. Returns None if return_nse is False. A value of 1 indicates perfect agreement; values below 0 indicate the model performs worse than the observed-mean predictor.
- Return type:
float or None
Reservoir
A single linear reservoir.
- class hydroravens.Reservoir(t_efold, f_to_discharge=1.0, Hmax=inf, H0=0.0)[source]
Bases:
objectGeneric reservoir. Accepts new water (recharge), and sends it to other reservoirs and/or out of the system (discharge) at a rate that is proportional to the amount of water held in the reservoir.
- __init__(t_efold, f_to_discharge=1.0, Hmax=inf, H0=0.0)[source]
Initialize a linear reservoir.
- Parameters:
t_efold (float) – E-folding residence time for reservoir depletion (days, or whatever time unit matches the model time steps).
f_to_discharge (float, optional) – Fraction of water lost each time step that exits as river discharge. The remainder (1 - f_to_discharge) infiltrates to the next-deeper reservoir. Default 1.0 (all to discharge).
Hmax (float, optional) – Maximum water depth the reservoir can hold. Default np.inf.
H0 (float, optional) – Initial water depth at the start of the simulation. Default 0.
- Raises:
ValueError – If t_efold <= 0, f_to_discharge < 0 or > 1, or Hmax < 0.
- recharge(H)[source]
Add or remove water from the reservoir.
Recharge H can be positive (net water input, e.g. P > ET) or negative (net deficit, e.g. ET > P). Sets H_excess if the reservoir overflows Hmax, or H_deficit if more water is removed than the reservoir holds.
- Parameters:
H (float) – Depth of water added (positive) or removed (negative).
- Raises:
ValueError – If Hwater is already negative before recharge is applied.
- discharge(dt)[source]
Discharge water from the reservoir over one time step.
Computes water lost by exponential decay, partitions it between river discharge (H_exfiltrated) and infiltration to the next-deeper reservoir (H_infiltrated), and adds overflow from recharge() (H_excess) to H_discharge.
- Parameters:
dt (float) – Time step duration (same units as t_efold; typically days).
Snowpack
Snowpack accumulation and positive-degree-day melt.
- class hydroravens.Snowpack(melt_factor=None)[source]
Bases:
objectSnowpack reservoir driven by temperature.
Accumulates precipitation as snow when mean temperature is at or below 0 °C. Melts at a positive-degree-day rate when temperature is above 0 °C. All melt is routed to the top subsurface reservoir as infiltration; direct discharge to the river is not modeled.
Should precede the subsurface reservoir list in a watershed model. The melt factor is a positive-degree-day factor [mm/°C/day].
- __init__(melt_factor=None)[source]
Initialize an empty snowpack.
- Parameters:
melt_factor (float, optional) – Positive-degree-day melt factor (mm SWE °C⁻¹ day⁻¹). Can be set or updated later via set_melt_factor().
- set_melt_factor(melt_factor)[source]
Set or update the positive-degree-day melt factor.
- Parameters:
melt_factor (float) – Melt rate per positive degree-day (mm SWE °C⁻¹ day⁻¹).
- set_temperature(T)[source]
Set the mean air temperature for the current time step.
- Parameters:
T (float) – Mean air temperature (°C).
- recharge(H)[source]
Apply net water input or deficit to the snowpack.
If T <= 0, positive H accumulates as snow (SWE). If T > 0, positive H bypasses the snowpack and is passed directly to the top subsurface reservoir via H_infiltrated. Negative H (ET > P) is removed from the snowpack as sublimation; any remainder that exceeds available SWE becomes H_deficit.
- Parameters:
H (float) – Net water depth for this time step (mm). Positive = input (P - ET > 0); negative = deficit (ET - P > 0).
- melt(dt, P=0.0)[source]
Compute positive-degree-day and rain-on-snow melt; update state.
Both terms are routed to H_infiltrated (→ top soil reservoir). If total available energy exceeds the SWE present, the leftover is returned as equivalent degree-days so the caller can credit it toward frozen-soil thawing (FGI reduction) rather than losing it.
Rain-on-snow sensible heat: water arriving at T_mean > 0 °C carries (c_p / L_f) · T · P mm SWE of latent-heat capacity. Spring snowpacks are near-isothermal at 0 °C, so cold-content corrections are negligible and the latent-heat term dominates.
References
McCabe et al. (2007) doi:10.1175/BAMS-88-3-319 Würzer et al. (2016) doi:10.1175/JHM-D-15-0181.1
- Parameters:
- Returns:
excess_dd – Leftover melt energy after the snowpack is exhausted, expressed as degree-day equivalent [°C·day] = leftover mm SWE / melt_factor. Zero when SWE is not fully depleted.
- Return type: