Skip to main content

hydro_xinanjiang/
lib.rs

1//! 新安江模型(三层蒸发 + 蓄满产流 + 三水源 + 单位线汇流 + 线性水库退水)。
2//!
3//! 算法对齐赵人俊《水文预报》标准 + 开源参考 OuyangWenyu/hydromodel xaj.py。
4//! 实现 `hydro_core::HydroModel` trait,可被 hydro-platform 统一编排。
5//!
6//! - **产流** `run_xinanjiang_step`(三层 ET + 蓄满产流 + 张力水更新 + 三水源)逐行对齐
7//!   xaj.py;**交叉验证在 `tests/xaj_crosscheck.rs`**(9 变量 ×3 场景 NSE>0.999 + relBias<0.1%,
8//!   数据 `tests/xaj_data/*`,由 `validation/xaj/gen_reference.py` 生成)。
9//! - **汇流** 地表 `rs` 经**单位线 UH 卷积**(`convolve_uh`)+ 壤中流/地下水 `ci/cg` 线性水库
10//!   + `cs` 河网平滑。单位线提供地表延迟(此前为"直接入流")。
11//!
12//! 说明:平台(H8)只供面平均 forcing,故本 trait 在**单出口**约束下提供单位线汇流;
13//! 完整分布式多子流域 + 马斯京根河道拓扑演算需逐子流域 forcing + 河网拓扑,留作后续。
14//!
15//! # English summary
16//!
17//! Distributed Xinanjiang rainfall–runoff model (Zhao Renjun, *Hydrological
18//! Forecasting*) for basins where saturation-excess runoff dominates. Each
19//! step runs three-layer evapotranspiration, saturation-excess production
20//! over a variable-capacity curve, three-source separation (surface /
21//! interflow / groundwater) on a free-water store, and linear-reservoir
22//! routing with a unit-hydrograph lag on surface runoff.
23//!
24//! - **Production** [`run_xinanjiang_step`] follows the reference
25//!   `OuyangWenyu/hydromodel xaj.py` line by line; cross-verified in
26//!   `tests/xaj_crosscheck.rs` (9 variables × 3 scenarios, NSE > 0.999 and
27//!   relative bias < 0.1 %; data under `tests/xaj_data/*`, generated by
28//!   `validation/xaj/gen_reference.py`).
29//! - **Routing** routes surface source `rs` through a unit hydrograph
30//!   ([`convolve_uh`]); interflow and groundwater pass through `ci` / `cg`
31//!   linear reservoirs and the total is smoothed by the `cs` network store.
32//!
33//! Implements [`hydro_core::HydroModel`] so the model can be orchestrated by
34//! `hydro-platform`. The platform supplies spatially averaged forcing, so the
35//! trait exposes single-outlet unit-hydrograph routing; a fully distributed
36//! multi-subbasin build with Muskingham channel topology is left for later.
37
38use hydro_core::{Forcing, HydroModel};
39use serde::{Deserialize, Serialize};
40
41// ---------------------------------------------------------------------------
42// Parameters
43// ---------------------------------------------------------------------------
44
45/// 单位线默认值(无延迟:uh=[1.0] → RS 当步直达,等价于原"直接入流"行为)。
46fn default_uh() -> Vec<f64> {
47    vec![1.0]
48}
49
50/// Xinanjiang model parameters (16 params + unit hydrograph + basin area).
51///
52/// Tension-water capacity `WM = um + lm + dm`. The basin `area_km2` is used
53/// to convert runoff depth (mm/Δt) to discharge (m³/s) inside routing.
54/// Defaults follow Zhao Renjun, *Hydrological Forecasting* (赵人俊《水文预报》),
55/// also matching the reference `OuyangWenyu/hydromodel xaj.py`.
56#[derive(Clone, Debug, Serialize, Deserialize)]
57pub struct XinanjiangParams {
58    /// Evaporation reduction coefficient (PET → EM = kc · PET). Typical 0.7–1.05. Dimensionless.
59    pub kc: f64,
60    /// Upper-layer tension-water capacity (mm). Typical ≈ 20.
61    pub um: f64,
62    /// Lower-layer tension-water capacity (mm). Typical ≈ 60.
63    pub lm: f64,
64    /// Deep-layer tension-water capacity (mm); `WM = um + lm + dm`. Typical ≈ 40.
65    pub dm: f64,
66    /// Deep-layer evaporation coefficient. Typical 0.1–0.2. Dimensionless.
67    pub c: f64,
68    /// Tension-water capacity curve exponent b (saturation-excess runoff distribution). Typical 0.1–0.4. Dimensionless.
69    pub b: f64,
70    /// Impervious-area fraction (rain on `im` becomes direct surface runoff). Typical 0–0.05. Dimensionless.
71    pub im: f64,
72    /// Free-water capacity (mm) over the producing area FR. Typical 10–50.
73    pub sm: f64,
74    /// Free-water distribution-curve exponent (three-source separation). Typical 1–3. Dimensionless.
75    pub ex: f64,
76    /// Groundwater outflow coefficient (kg · S → RG). Dimensionless per step.
77    pub kg: f64,
78    /// Interflow outflow coefficient (ki · S → RI). Dimensionless per step.
79    pub ki: f64,
80    /// Groundwater recession coefficient (linear-reservoir `Qg ← cg·Qg + (1−cg)·inflow`). Dimensionless.
81    pub cg: f64,
82    /// Interflow recession coefficient (linear-reservoir `Qi ← ci·Qi + (1−ci)·inflow`). Dimensionless.
83    pub ci: f64,
84    /// Channel-network storage smoothing coefficient (`Q ← cs·Q + (1−cs)·raw`). Dimensionless.
85    pub cs: f64,
86    /// Surface-runoff unit hydrograph (normalised convolution kernel; default `[1.0]` = no lag).
87    /// Supplied externally; not part of scalar calibration.
88    #[serde(default = "default_uh")]
89    pub uh: Vec<f64>,
90    /// Basin area (km²); used for mm/Δt → m³/s conversion in routing.
91    pub area_km2: f64,
92}
93
94impl Default for XinanjiangParams {
95    fn default() -> Self {
96        Self {
97            kc: 0.9, um: 20.0, lm: 60.0, dm: 40.0, c: 0.14, b: 0.4, im: 0.02,
98            sm: 20.0, ex: 1.5, kg: 0.42, ki: 0.28, cg: 0.98, ci: 0.80, cs: 0.20,
99            uh: default_uh(),
100            area_km2: 1000.0,
101        }
102    }
103}
104
105// ---------------------------------------------------------------------------
106// Production: state + single-step function (供 oracle 交叉验证直接调用)
107// ---------------------------------------------------------------------------
108
109const PRECISION: f64 = 1e-5;
110const DEFAULT_FR: f64 = 0.1;
111
112/// Continuous hydrological state carried across time steps. All fields are
113/// basin-wide averages.
114///
115/// - `wu` / `wl` / `wd`: upper / lower / deep tension-water storage (mm).
116/// - `s`: free-water depth (mm), defined over the producing area `fr`.
117/// - `fr`: producing-area fraction (0–1).
118#[derive(Debug, Clone, Serialize, Deserialize)]
119pub struct BasinState {
120    /// Upper-layer tension-water storage (mm), `∈ [0, um]`.
121    pub wu: f64,
122    /// Lower-layer tension-water storage (mm), `∈ [0, lm]`.
123    pub wl: f64,
124    /// Deep-layer tension-water storage (mm), `∈ [0, dm]`.
125    pub wd: f64,
126    /// Free-water storage (mm) over the producing area `fr`, `∈ [0, sm]`.
127    pub s: f64,
128    /// Producing-area fraction (dimensionless, `∈ [0, 1]`).
129    #[serde(default = "default_fr")]
130    pub fr: f64,
131}
132
133fn default_fr() -> f64 {
134    DEFAULT_FR
135}
136
137impl Default for BasinState {
138    fn default() -> Self {
139        Self { wu: 0.0, wl: 0.0, wd: 0.0, s: 0.0, fr: DEFAULT_FR }
140    }
141}
142
143/// One-step runoff output, expressed as basin-average depth (mm/Δt) at the
144/// channel inlet.
145///
146/// `rs` already includes direct discharge over the impervious fraction
147/// (`pe · im`); `rri` and `rg` have been scaled by `(1 − im)`.
148#[derive(Debug, Clone, Default)]
149pub struct RunoffSource {
150    /// Actual evapotranspiration (mm/Δt), sum of the three layers.
151    pub e: f64,
152    /// Surface runoff (mm/Δt), including impervious-area direct discharge.
153    pub rs: f64,
154    /// Interflow (mm/Δt), scaled by `(1 − im)`.
155    pub rri: f64,
156    /// Groundwater runoff (mm/Δt), scaled by `(1 − im)`.
157    pub rg: f64,
158}
159
160/// One-step Xinanjiang production: three-layer ET + saturation-excess runoff
161/// + tension-water update + three-source separation.
162///
163/// Inputs are basin-average rainfall `p_mm` (mm/Δt) and potential
164/// evapotranspiration capacity `em_mm` (mm/Δt). `em_mm` is multiplied by
165/// `kc` internally (i.e. `pet = em_mm · kc`, matching `pet = p_and_e[:,1]*k`
166/// in xaj.py). The `state` is updated in place; the returned [`RunoffSource`]
167/// gives the channel-inlet sources in mm/Δt.
168///
169/// The algorithm follows `OuyangWenyu/hydromodel xaj.py` line by line. When
170/// `im = 0` the step reduces to the standard pervious Xinanjiang formulation.
171///
172/// Cross-verified against the Python oracle in `tests/xaj_crosscheck.rs`
173/// (9 variables × 3 scenarios, NSE > 0.999, relative bias < 0.1 %).
174pub fn run_xinanjiang_step(
175    state: &mut BasinState,
176    p_mm: f64,
177    em_mm: f64,
178    params: &XinanjiangParams,
179) -> RunoffSource {
180    let um = params.um.max(0.0);
181    let lm = params.lm.max(0.0);
182    let dm = params.dm.max(0.0);
183    let wm = um + lm + dm;
184    let b = params.b;
185    let c = params.c;
186    let im = params.im.clamp(0.0, 1.0);
187    let pet = (em_mm * params.kc).max(0.0); // pet = EM·kc(对齐 xaj.py)
188    let prcp = p_mm.max(0.0);
189
190    let (wu0, wl0, wd0) = (state.wu, state.wl, state.wd);
191
192    // ---- 1) 三层蒸散发 ----
193    let eu = if wu0 + prcp >= pet { pet } else { wu0 + prcp };
194    let rem_pet = (pet - eu).max(0.0);
195    let ed = if lm > 0.0 && wl0 < c * lm && wl0 < c * rem_pet {
196        (c * rem_pet - wl0).max(0.0)
197    } else { 0.0 };
198    let el = if wu0 + prcp >= pet || lm <= 0.0 { 0.0 }
199        else if wl0 >= c * lm { rem_pet * wl0 / lm }
200        else if wl0 >= c * rem_pet { c * rem_pet }
201        else { wl0 };
202    let e = eu + el + ed;
203
204    // ---- 2) 蓄满产流 ----
205    let pe_raw = prcp - e;
206    let pe = pe_raw.max(0.0);
207    let w0 = (wu0 + wl0 + wd0).min(wm - PRECISION).max(0.0);
208    let wmm = wm * (1.0 + b);
209    let r = if wm > 0.0 && pe > 0.0 {
210        let a = wmm * (1.0 - (1.0 - w0 / wm).max(0.0).powf(1.0 / (1.0 + b)));
211        if pe + a < wmm {
212            pe - (wm - w0) + wm * (1.0 - ((a + pe) / wmm).min(1.0)).powf(1.0 + b)
213        } else {
214            pe - (wm - w0)
215        }.max(0.0)
216    } else { 0.0 };
217    let r_im = (pe * im).max(0.0);
218
219    // ---- 3) 张力水更新 ----
220    let (wu_new, wl_new, wd_new) = if pe_raw > 0.0 {
221        let wu_c = if wu0 + pe_raw - r < um { wu0 + pe_raw - r } else { um };
222        let wd_c = if wu0 + wl0 + pe_raw - r > um + lm {
223            wu0 + wl0 + wd0 + pe_raw - r - um - lm
224        } else { wd0 };
225        let wl_c = wu0 + wl0 + wd0 + pe_raw - r - wu_c - wd_c;
226        (wu_c.clamp(0.0, um), wl_c.clamp(0.0, lm), wd_c.clamp(0.0, dm))
227    } else {
228        let wu_c = if wu0 + pe_raw > 0.0 { wu0 + pe_raw } else { 0.0 };
229        (wu_c.clamp(0.0, um), (wl0 - el).clamp(0.0, lm), (wd0 - ed).clamp(0.0, dm))
230    };
231
232    // ---- 4) 三水源分离 ----
233    let sm = params.sm.max(0.0);
234    let ex = params.ex;
235    let ki = params.ki;
236    let kg = params.kg;
237    let fr0 = state.fr;
238    let s0 = state.s;
239
240    let (rs_src, ri_src, rg_src, s1, fr_new) = if sm > 0.0 {
241        let ms = sm * (1.0 + ex);
242        let fr = if r > 0.0 && pe > 0.0 { (r / pe).clamp(0.0, 1.0) } else { fr0 };
243        let ss = if r > 0.0 && fr > 0.0 { (fr0 * s0 / fr).min(sm) } else { s0 };
244        let rs_src = if r > 0.0 {
245            let au = ms * (1.0 - (1.0 - ss / sm).max(0.0).powf(1.0 / (1.0 + ex)));
246            let v = if pe + au < ms {
247                fr * (pe - sm + ss + sm * (1.0 - ((pe + au) / ms).min(1.0)).powf(1.0 + ex))
248            } else { fr * (pe + ss - sm) };
249            v.min(r).max(0.0)
250        } else { 0.0 };
251        let s_pre = if r > 0.0 && fr > 0.0 { (ss + (r - rs_src) / fr).min(sm) } else { s0 };
252        let ri_src = ki * s_pre * fr;
253        let rg_src = kg * s_pre * fr;
254        let s1 = (s_pre * (1.0 - ki - kg)).max(0.0);
255        (rs_src, ri_src, rg_src, s1, fr)
256    } else {
257        let rs_src = if r > 0.0 { r } else { 0.0 };
258        (rs_src, 0.0, 0.0, 0.0, fr0)
259    };
260
261    // ---- 提交状态 ----
262    state.wu = wu_new; state.wl = wl_new; state.wd = wd_new; state.s = s1; state.fr = fr_new;
263
264    // ---- 河道入口水源(rs 含 im 直排;rri/rg 已乘 1−im)----
265    let rs = rs_src * (1.0 - im) + r_im;
266    let rri = ri_src * (1.0 - im);
267    let rg = rg_src * (1.0 - im);
268    RunoffSource { e, rs, rri, rg }
269}
270
271// ---------------------------------------------------------------------------
272// Routing: unit hydrograph convolution
273// ---------------------------------------------------------------------------
274
275/// Unit-hydrograph convolution at the latest step.
276///
277/// For the most recent time index `t = rs_hist.len() − 1`, computes
278/// `qs = Σ_k uh[k] · rs_hist[t − k]`. With `uh = [1.0]`, `qs = rs_hist[t]`
279/// (no lag, equivalent to direct inflow). Returns 0 for empty inputs.
280pub fn convolve_uh(rs_hist: &[f64], uh: &[f64]) -> f64 {
281    if rs_hist.is_empty() || uh.is_empty() {
282        return 0.0;
283    }
284    let t = rs_hist.len() - 1;
285    let kmax = uh.len().min(t + 1);
286    let mut qs = 0.0;
287    for k in 0..kmax {
288        qs += uh[k] * rs_hist[t - k];
289    }
290    qs
291}
292
293// ---------------------------------------------------------------------------
294// Model state + HydroModel impl
295// ---------------------------------------------------------------------------
296
297/// Xinanjiang model instance: parameters + production state + routing
298/// reservoirs + surface-runoff (`rs`) history for unit-hydrograph convolution.
299///
300/// Implements [`hydro_core::HydroModel`]. Use [`XinanjiangModel::new`] to
301/// construct, then call `step(&forcing, dt_h)` each time step and read
302/// [`XinanjiangModel::discharge`] (m³/s).
303pub struct XinanjiangModel {
304    params: XinanjiangParams,
305    basin: BasinState,
306    // Routing reservoirs (m³/s)
307    qi: f64, qg: f64, // interflow / groundwater
308    rs_hist: Vec<f64>, // 地表水源历史(mm/Δt),供单位线卷积
309    discharge: f64,   // current total discharge (m³/s)
310}
311
312impl XinanjiangModel {
313    /// mm → m³/s conversion for the basin area.
314    fn mm_to_m3s(&self, mm: f64, dt_h: f64) -> f64 {
315        mm * self.params.area_km2 * 1000.0 / (dt_h * 3600.0)
316    }
317}
318
319impl HydroModel for XinanjiangModel {
320    type Params = XinanjiangParams;
321
322    fn new(params: Self::Params) -> Self {
323        Self {
324            params,
325            basin: BasinState::default(),
326            qi: 0.0, qg: 0.0, rs_hist: Vec::new(), discharge: 0.0,
327        }
328    }
329
330    fn step(&mut self, f: &Forcing, dt_h: f64) {
331        let p = &self.params;
332        // 产流 → 河道入口水源(mm)
333        let src = run_xinanjiang_step(&mut self.basin, f.p_mm, f.pet_mm, p);
334
335        // 地表 RS → 单位线卷积(此前为"直接入流")
336        self.rs_hist.push(src.rs);
337        let qs = convolve_uh(&self.rs_hist, &p.uh);
338        let q_rs = self.mm_to_m3s(qs, dt_h);
339
340        // 壤中流 RRI → 线性水库(ci 退水)
341        let rri_m3s = self.mm_to_m3s(src.rri, dt_h);
342        self.qi = self.qi * p.ci + rri_m3s * (1.0 - p.ci);
343        // 地下水 RG → 线性水库(cg 退水)
344        let rg_m3s = self.mm_to_m3s(src.rg, dt_h);
345        self.qg = self.qg * p.cg + rg_m3s * (1.0 - p.cg);
346
347        // 总流量 = RS + QI + QG(经 CS 河网平滑)
348        let q_raw = q_rs + self.qi + self.qg;
349        self.discharge = self.discharge * p.cs + q_raw * (1.0 - p.cs);
350    }
351
352    fn discharge(&self) -> f64 { self.discharge }
353    fn state(&self) -> serde_json::Value {
354        serde_json::json!({
355            "wu": self.basin.wu, "wl": self.basin.wl, "wd": self.basin.wd,
356            "s": self.basin.s, "fr": self.basin.fr, "qi": self.qi, "qg": self.qg
357        })
358    }
359    fn reset(&mut self) {
360        self.basin = BasinState::default();
361        self.qi = 0.0; self.qg = 0.0; self.rs_hist.clear(); self.discharge = 0.0;
362    }
363    fn name(&self) -> &'static str { "新安江" }
364    fn params(&self) -> &Self::Params { &self.params }
365    fn params_mut(&mut self) -> &mut Self::Params { &mut self.params }
366}
367
368// ---------------------------------------------------------------------------
369// Tests
370// ---------------------------------------------------------------------------
371
372#[cfg(test)]
373mod tests {
374    use super::*;
375    use hydro_core::HydroModel;
376
377    #[test]
378    fn test_state_bounds() {
379        let mut m = XinanjiangModel::new(XinanjiangParams::default());
380        for (p, e) in [(50.0, 0.0), (0.0, 5.0), (30.0, 2.0), (0.0, 8.0), (100.0, 0.0)] {
381            m.step(&Forcing { p_mm: p, pet_mm: e, t_c: 20.0 }, 1.0);
382            assert!(m.basin.wu >= -1e-6 && m.basin.wu <= m.params.um + 1e-4);
383            assert!(m.basin.wl >= -1e-6 && m.basin.wl <= m.params.lm + 1e-4);
384            assert!(m.basin.s >= -1e-6 && m.basin.s <= m.params.sm + 1e-3);
385            assert!(m.discharge >= 0.0);
386        }
387    }
388
389    #[test]
390    fn test_drought_recedes() {
391        let mut m = XinanjiangModel::new(XinanjiangParams::default());
392        for _ in 0..5 { m.step(&Forcing { p_mm: 50.0, pet_mm: 0.0, t_c: 20.0 }, 1.0); }
393        let q_peak = m.discharge;
394        for _ in 0..200 { m.step(&Forcing { p_mm: 0.0, pet_mm: 5.0, t_c: 25.0 }, 1.0); }
395        assert!(m.discharge < q_peak, "discharge should recede");
396        assert!(m.discharge < 10.0, "should recede to low baseflow after long drought: {}", m.discharge);
397    }
398
399    #[test]
400    fn test_rain_produces_flow() {
401        let mut m = XinanjiangModel::new(XinanjiangParams::default());
402        for _ in 0..10 { m.step(&Forcing { p_mm: 30.0, pet_mm: 0.0, t_c: 20.0 }, 1.0); }
403        assert!(m.discharge > 0.0, "rain should produce discharge");
404    }
405
406    #[test]
407    fn test_dyn_dispatch() {
408        let mut m: Box<dyn hydro_core::DynHydroModel> = Box::new(
409            XinanjiangModel::new(XinanjiangParams::default())
410        );
411        m.step(&Forcing { p_mm: 50.0, pet_mm: 1.0, t_c: 20.0 }, 1.0);
412        assert!(m.discharge() >= 0.0);
413        assert_eq!(m.name(), "新安江");
414    }
415
416    /// UH=[1.0]:恒定 RS → 卷积=RS 本身(无延迟,等价原"直接入流")。
417    #[test]
418    fn convolve_uh_no_lag() {
419        let rs = vec![10.0; 5];
420        assert!((convolve_uh(&rs, &[1.0]) - 10.0).abs() < 1e-9);
421    }
422
423    /// UH=[0.5,0.5]:最新 RS 与上一步各取半 → 体现延迟。
424    #[test]
425    fn convolve_uh_distributes_lag() {
426        // t=0: rs=[10], qs = 0.5·10 = 5
427        assert!((convolve_uh(&[10.0], &[0.5, 0.5]) - 5.0).abs() < 1e-9);
428        // t=1: rs=[10,0], qs = 0.5·rs[1] + 0.5·rs[0] = 0 + 5 = 5
429        assert!((convolve_uh(&[10.0, 0.0], &[0.5, 0.5]) - 5.0).abs() < 1e-9);
430        // t=1 恒定: rs=[10,10], qs = 0.5·10 + 0.5·10 = 10
431        assert!((convolve_uh(&[10.0, 10.0], &[0.5, 0.5]) - 10.0).abs() < 1e-9);
432    }
433
434    /// 单位线卷积守恒:Σ uh = 1 时,恒定 RS 的稳态 qs = RS。
435    #[test]
436    fn convolve_uh_steady_state_unit_area() {
437        let rs = vec![7.0; 8];
438        let uh = vec![0.25, 0.5, 0.25]; // Σ=1
439        assert!((convolve_uh(&rs, &uh) - 7.0).abs() < 1e-9);
440    }
441}