Skip to main content

hydro_core/
forcing.rs

1//! Forcing data types shared across all hydrology models.
2//!
3//! Defines the per-timestep meteorological forcing ([`Forcing`]), static basin
4//! metadata ([`BasinInfo`]), and outlet hydraulics ([`Outlet`]) used by every
5//! model in the suite. All types are serializable so that scenarios can be
6//! persisted as JSON.
7
8use serde::{Serialize, Deserialize};
9
10/// Per-timestep meteorological forcing for a sub-basin or grid cell.
11///
12/// All models in the suite consume the same forcing tuple — precipitation,
13/// potential evapotranspiration, and air temperature — so a single
14/// forcing series can be replayed across every model for comparison.
15#[derive(Clone, Debug, Serialize, Deserialize, Default)]
16pub struct Forcing {
17    /// Precipitation depth for this time-step, in millimetres (mm).
18    pub p_mm: f64,
19    /// Potential evapotranspiration (PET) for this time-step, in millimetres (mm).
20    pub pet_mm: f64,
21    /// Air temperature for this time-step, in degrees Celsius (°C).
22    pub t_c: f64,
23}
24
25/// Static basin / sub-basin metadata shared across all models.
26///
27/// Carries the immutable descriptors (area, outlet location, identifiers)
28/// that a model needs to convert specific discharge to volumetric discharge
29/// and to georeference outputs.
30#[derive(Clone, Debug, Serialize, Deserialize)]
31pub struct BasinInfo {
32    /// Stable identifier used as a key in configs and platform output tables.
33    pub id: String,
34    /// Human-readable basin name (e.g. `"Huagrahuma"`, `"Ames_sub1"`).
35    pub name: String,
36    /// Basin drainage area in square kilometres (km²).
37    ///
38    /// Used to convert between volumetric discharge (m³/s) and runoff depth
39    /// (mm) via `D_mm = ΣQ · dt_h · 3.6 / area_km2`.
40    pub area_km2: f64,
41    /// Outlet latitude in decimal degrees (WGS84 / CGCS2000 ≈ WGS84).
42    pub outlet_lat: f64,
43    /// Outlet longitude in decimal degrees (WGS84 / CGCS2000 ≈ WGS84).
44    pub outlet_lon: f64,
45}
46
47/// Outlet section descriptor.
48///
49/// Each [`BasinInfo`] has at least one outlet; this struct attaches the
50/// outlet's hydraulic relationship (rating curve) so stage outputs can be
51/// converted to discharge and vice versa.
52#[derive(Clone, Debug, Serialize, Deserialize)]
53pub struct Outlet {
54    /// Identifier of the basin this outlet drains.
55    pub basin_id: String,
56    /// Human-readable outlet name (e.g. `"Main gauge"`).
57    pub name: String,
58    /// Optional stage–discharge relationship as a list of `(stage_m, discharge_m3s)`
59    /// control points, monotone increasing in stage. Linear interpolation is
60    /// used between points. `None` if the model writes discharge directly.
61    pub rating_curve: Option<Vec<(f64, f64)>>, // (stage_m, discharge_m3s)
62}