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}