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}