hydro_calib/lib.rs
1//! hydro-calib: 模型无关率定器(对标 SPOTPY/OSTRICH)。
2//!
3//! 针 `hydro_core::DynHydroModel` trait(`set_params_json` + `step/discharge` 管线已就绪)。
4//! 两个原生 Rust 全局优化器:
5//! - **DDS**(Tolson & Shoemaker 2007):动态降维搜索,少评估、稳健,默认首选。
6//! - **SCE-UA**(Duan et al. 1992):洗牌复杂演化,经典、强收敛,评估多。
7//! 目标函数可插拔(NSE/KGE/logNSE/DC/NegRMSE),归一化决策变量 `[0,1]`→实际参数区间。
8//!
9//! # English
10//!
11//! `hydro-calib` is a **model-agnostic calibrator** for any type that implements
12//! [`hydro_core::DynHydroModel`]. It pairs two native-Rust global optimisers —
13//! **DDS** and **SCE-UA** — with pluggable objective functions
14//! (NSE / KGE / log-NSE / DC / −RMSE) and normalised decision variables
15//! (`x ∈ [0,1]` per parameter, mapped to the named field's `[min, max]` range
16//! inside the model's JSON params). The calibration entry point is
17//! [`calibrate`]; the underlying optimisers ([`dds_optimize`], [`sce_ua_optimize`])
18//! are also exposed for general black-box use.
19//!
20//! ## Optimisers
21//!
22//! - **Dynamically Dimensioned Search (DDS)** — Tolson & Shoemaker (2007),
23//! *"Cannonsim Hydrologic Model Calibrations with Implicitly Generated
24//! Dynamically Dimensioned Search"*, Water Resources Research **43**,
25//! W01422. A single-trajectory greedy search whose per-dimension inclusion
26//! probability decays as `P(m) = 1 − ln(m)/ln(M)` — coarse global early,
27//! fine local late. Best default when the evaluation budget is modest
28//! (≤ a few hundred model runs) and the response surface is moderately
29//! rough.
30//! - **Shuffled Complex Evolution (SCE-UA)** — Duan, Gupta & Sorooshian
31//! (1992), *"Effective and Efficient Model Global Optimization for the
32//! Conceptual Rainfall-Runoff Models"*, Water Resources Research **28**,
33//! pp. 1015–1031. A population-based method that partitions candidates
34//! into complexes, evolves each with competitive complex evolution (Nelder–Mead
35//! style reflection / contraction / mutation), and reshuffles. Strong
36//! convergence at the cost of more evaluations; classic for conceptual
37//! rainfall–runoff models.
38//!
39//! ## Determinism / dependencies
40//!
41//! Both optimisers draw randomness from an internal **`xorshift64`**
42//! pseudo-random generator seeded by the caller (`seed: u64`). The same
43//! seed reproduces the same trajectory bit-for-bit across platforms. The
44//! generator is the *only* source of randomness; there are **zero external
45//! dependencies** beyond `hydro-core` (for the model trait + forcing) and
46//! `serde_json` (for parameter overrides). No `rand`, no BLAS, no platform
47//! RNG.
48//!
49//! ## Verification
50//!
51//! - `dds_converges_quadratic` / `sce_ua_converges_quadratic` — both
52//! optimisers recover the known optimum `(0.7, 0.3)` of a 2-D quadratic
53//! bowl to `< 0.08` absolute error.
54//! - `calibrate_xinanjiang_recovers_known_hydrograph` — DDS recovers
55//! synthetic-truth `sm` / `kg` for `hydro-xinanjiang` with NSE `> 0.85`.
56
57use hydro_core::{DynHydroModel, Forcing, nse, kge, rmse};
58
59// ── 目标函数 ────────────────────────────────────────────────────────
60
61/// 率定目标(皆"越大越好";RMSE 取负)。
62///
63/// Calibration objective. All variants are **maximised** (RMSE is negated so
64/// that "higher score = better fit" uniformly). Select via [`Objective::Nse`]
65/// / [`Objective::Kge`] / [`Objective::LogNse`] / [`Objective::Dc`] /
66/// [`Objective::NegRmse`] when calling [`calibrate`] or [`evaluate`].
67#[derive(Clone, Copy, Debug, PartialEq, Eq)]
68pub enum Objective {
69 /// Nash–Sutcliffe Efficiency, `NSE = 1 − Σ(o−s)² / Σ(o−ō)²`.
70 ///
71 /// Range `(−∞, 1]`; `1.0` = perfect. Equivalent to the deterministic
72 /// coefficient DC of GB/T 22482. The standard calibration default for
73 /// flood-forecast models.
74 Nse,
75 /// Kling–Gupta Efficiency, `KGE = 1 − √( (r−1)² + (α−1)² + (β−1)² )`.
76 ///
77 /// Range `(−∞, 1]`; `1.0` = perfect. Decomposes error into correlation,
78 /// variability, and bias — preferred over NSE when bias and peak timing
79 /// both matter.
80 Kge,
81 /// Log-space NSE — [`log_nse`]; NSE computed on `ln(Q + ε)`.
82 ///
83 /// Range `(−∞, 1]`. Emphasises low-flow / recession fit by compressing
84 /// high flows logarithmally; use for drought or base-flow-dominated
85 /// regimes. `ε = 1e-6` avoids `ln(0)`.
86 LogNse,
87 /// Deterministic coefficient DC (GB/T 22482-2008 确定性系数).
88 ///
89 /// Numerically identical to [`Objective::Nse`] — provided as a separate
90 /// variant so that downstream tooling can distinguish "NSE as optimisation
91 /// target" from "DC as the Chinese-standard grade metric" when reporting.
92 Dc,
93 /// Negative RMSE, `-√( (1/N) Σ(o−s)² )`.
94 ///
95 /// Range `(−∞, 0]`; `0.0` = perfect. Maximising this is equivalent to
96 /// minimising RMSE. Same units as the discharge series (typically m³/s).
97 /// Prefer [`Objective::Nse`] / [`Objective::Kge`] unless you need
98 /// absolute-error (not normalised-error) scoring.
99 NegRmse,
100}
101
102/// 对数空间 NSE(枯水敏感):NSE on ln(Q+ε)。
103///
104/// Log-space Nash–Sutcliffe Efficiency — NSE computed on `ln(Q + ε)` of both
105/// series. Useful for low-flow / recession calibration where small errors in
106/// small discharges matter as much as large errors in peaks. `ε = 1e-6` keeps
107/// `ln` finite for dry steps. Returns NSE on the transformed series; range
108/// `(−∞, 1]`, `1.0` = perfect.
109pub fn log_nse(obs: &[f64], sim: &[f64]) -> f64 {
110 let eps = 1e-6;
111 let lo: Vec<f64> = obs.iter().map(|q| (q.max(0.0) + eps).ln()).collect();
112 let ls: Vec<f64> = sim.iter().map(|q| (q.max(0.0) + eps).ln()).collect();
113 nse(&lo, &ls)
114}
115
116fn score_of(obs: &[f64], sim: &[f64], obj: Objective) -> f64 {
117 match obj {
118 Objective::Nse | Objective::Dc => nse(obs, sim),
119 Objective::Kge => kge(obs, sim),
120 Objective::LogNse => log_nse(obs, sim),
121 Objective::NegRmse => -rmse(obs, sim),
122 }
123}
124
125// ── 参数规格 / 结果 ────────────────────────────────────────────────
126
127/// 单个率定参数:JSON 字段名 + 区间(归一化 `x∈[0,1]` 映射到 `[min,max]`)。
128///
129/// One free parameter for calibration. The optimiser searches in normalised
130/// space `x ∈ [0, 1]`; [`vector_to_json`] maps `x` back to the physical range
131/// via `value = min + x · (max − min)` and writes it into the JSON field
132/// identified by [`name`](ParamSpec::name). The remaining fields of the
133/// model's params JSON are inherited unchanged from `base_params`.
134#[derive(Clone, Debug)]
135pub struct ParamSpec {
136 /// JSON field name to override inside the model's params object (must
137 /// match the `Serialize` field name of the model's `Params` struct, e.g.
138 /// `"sm"` or `"kg"` for `hydro-xinanjiang::XinanjiangParams`).
139 pub name: String,
140 /// Lower bound (inclusive) — value when `x = 0`.
141 pub min: f64,
142 /// Upper bound (inclusive) — value when `x = 1`.
143 pub max: f64,
144}
145
146/// 优化器原始结果(归一化空间)。
147///
148/// Raw optimiser result in **normalised space** (`x ∈ [0,1]^n`). Convert to
149/// physical parameters with [`vector_to_json`] when integrating with a
150/// hydrological model. All fields are populated by [`dds_optimize`] /
151/// [`sce_ua_optimize`].
152#[derive(Clone, Debug)]
153pub struct OptResult {
154 /// Best decision vector found, in `[0,1]^n`.
155 pub x: Vec<f64>,
156 /// Best objective score achieved (maximised). `NaN` only if every
157 /// evaluation returned `NaN`.
158 pub score: f64,
159 /// Total number of objective evaluations performed (≤ `budget`).
160 pub evaluations: usize,
161 /// Convergence history — best score so far after each evaluation.
162 /// Monotone non-decreasing under a deterministic objective; length
163 /// equals `evaluations`. Use this to plot convergence curves.
164 pub history: Vec<f64>, // 每评估后的历史最优分数(最大化)
165}
166
167/// 率定结果(参数 JSON + 最优分数 + 评估次数 + 收敛历史)。
168///
169/// Hydrology-facing calibration result. [`calibrate`] returns this. Unlike
170/// [`OptResult`] (normalised space), here the best parameters are already
171/// mapped back to the model's JSON representation by applying [`ParamSpec`]
172/// ranges to `base_params`.
173#[derive(Clone, Debug)]
174pub struct CalibResult {
175 /// Best parameter set as a JSON object: `base_params` with the
176 /// [`ParamSpec`] fields overwritten by their calibrated physical values.
177 /// Round-trips through `set_params_json` on `DynHydroModel`.
178 pub best_params: serde_json::Value,
179 /// Best objective score achieved (maximised). Units depend on
180 /// [`Objective`] — e.g. dimensionless for `Nse` / `Kge`, m³/s for
181 /// `NegRmse`.
182 pub best_score: f64,
183 /// Total number of model evaluations performed (≤ `budget`).
184 pub evaluations: usize,
185 /// Convergence history — best score so far after each evaluation
186 /// (monotone non-decreasing). Same as [`OptResult::history`].
187 pub history: Vec<f64>,
188}
189
190/// 率定方法。
191///
192/// Which optimiser [`calibrate`] dispatches to. Pick by the trade-off below.
193///
194/// - [`Method::Dds`] — best for **small evaluation budgets** (≤ a few hundred
195/// model runs) and moderate-dimensional parameter spaces (≤ ~10). Single
196/// trajectory; no population to maintain.
197/// - [`Method::SceUa`] — best for **larger budgets** and rugged / multimodal
198/// response surfaces where a single trajectory can get stuck. Population
199/// `p · m` with `p` complexes (default 5) and `m = 2n+1` points each.
200#[derive(Clone, Copy, Debug, PartialEq, Eq)]
201pub enum Method {
202 /// Dynamically Dimensioned Search (Tolson & Shoemaker 2007).
203 Dds,
204 /// Shuffled Complex Evolution (Duan et al. 1992).
205 SceUa,
206}
207
208/// SCE-UA 配置(默认:complexes=5,每 complex m=2n+1 点,subcomplex q=n+1)。
209///
210/// Tuning knobs for [`sce_ua_optimize`]. The defaults (Duan et al. 1992
211/// recommended values) are good for most conceptual rainfall–runoff models;
212/// override only if you have a specific reason.
213///
214/// - `complexes = p` (default **5**) — number of parallel complexes. Total
215/// population is `p · m` where `m = 2n + 1` and `n` is the parameter
216/// dimension. Larger `p` ⇒ better global coverage, more evaluations per
217/// generation.
218/// - Each complex runs Competitive Complex Evolution (CCE) on a subcomplex of
219/// `q = min(n + 1, m)` points drawn by triangular rank-weighted sampling
220/// (better points are more likely to be picked). New points are produced
221/// by reflection → contraction → mutation fallback.
222#[derive(Clone, Copy, Debug)]
223pub struct SceConfig {
224 /// Number of complexes `p` (default `5`). Must be `≥ 1`.
225 pub complexes: usize, // p
226}
227
228impl Default for SceConfig {
229 fn default() -> Self {
230 Self { complexes: 5 }
231 }
232}
233
234// ── 确定性 PRNG(xorshift64,无外部依赖) ────────────────────────────
235
236struct Rng {
237 state: u64,
238}
239impl Rng {
240 fn new(seed: u64) -> Self {
241 Self { state: if seed == 0 { 0x9E3779B97F4A7C15 } else { seed } }
242 }
243 fn u64(&mut self) -> u64 {
244 let mut x = self.state;
245 x ^= x << 13;
246 x ^= x >> 7;
247 x ^= x << 17;
248 self.state = x;
249 x
250 }
251 fn unit(&mut self) -> f64 {
252 // [0,1)
253 (self.u64() >> 11) as f64 / (1u64 << 53) as f64
254 }
255 fn gaussian(&mut self) -> f64 {
256 let u1 = self.unit().max(1e-12);
257 let u2 = self.unit();
258 (-2.0 * u1.ln()).sqrt() * (2.0 * std::f64::consts::PI * u2).cos()
259 }
260}
261
262/// 把 x∈[0,1] 反射回 [0,1](越界镜像)。
263fn reflect01(x: f64) -> f64 {
264 let mut v = x;
265 for _ in 0..10 {
266 if v < 0.0 { v = -v; } else if v > 1.0 { v = 2.0 - v; } else { break; }
267 }
268 v.clamp(0.0, 1.0)
269}
270
271// ── DDS(Tolson & Shoemaker 2007) ──────────────────────────────────
272
273/// 动态降维搜索。`obj`:归一化空间 `[0,1]^n` → 分数(最大化)。`budget`:模型评估上限。
274///
275/// Dynamically Dimensioned Search (Tolson & Shoemaker 2007). A single-trajectory
276/// greedy global optimiser. At iteration `m` of `M = budget`, each dimension
277/// is independently perturbed (Gaussian, σ = 0.2 in normalised space) with
278/// probability `P(m) = 1 − ln(m)/ln(M)`. This schedule is coarse early
279/// (many dimensions move, global exploration) and fine late (most dimensions
280/// frozen, local refinement). The new point is accepted iff it improves on
281/// the current best (greedy ascent). Out-of-range perturbations are mirrored
282/// back into `[0, 1]`.
283///
284/// # Arguments
285/// - `n` — parameter dimension (length of the decision vector). Returns an
286/// empty result if `0`.
287/// - `obj` — objective function `f: [0,1]^n → ℝ` to **maximise**. Called with
288/// the normalised decision vector; the caller maps back to physical
289/// parameters (see [`vector_to_json`]).
290/// - `budget` — total number of objective evaluations. DDS is designed for
291/// modest budgets (50–500 is typical for hydrology models). Returns an
292/// empty result if `0`.
293/// - `seed` — `xorshift64` seed. Same seed ⇒ same trajectory across
294/// platforms (deterministic).
295///
296/// # Returns
297/// Best-found `x`, its score, total evaluations used (`= budget` unless
298/// `budget = 0`), and the convergence history (one entry per evaluation).
299pub fn dds_optimize(n: usize, obj: &dyn Fn(&[f64]) -> f64, budget: usize, seed: u64) -> OptResult {
300 if n == 0 || budget == 0 {
301 return OptResult { x: vec![], score: f64::NEG_INFINITY, evaluations: 0, history: vec![] };
302 }
303 let mut rng = Rng::new(seed);
304 let sigma = 0.2; // 扰动标准差(归一化空间)
305 let mut x_best: Vec<f64> = (0..n).map(|_| rng.unit()).collect();
306 let mut best = obj(&x_best);
307 let mut evals = 1;
308 let mut history = vec![best];
309 let m_total = budget;
310 for m in 1..m_total {
311 // 每维纳入概率 P(m) = 1 - ln(m)/ln(M),随迭代递减(粗→细)
312 let p = if m_total > 1 {
313 1.0 - (m as f64).ln() / (m_total as f64).ln()
314 } else {
315 1.0
316 };
317 let p = p.clamp(0.0, 1.0);
318 let mut x_new = x_best.clone();
319 let mut included = false;
320 for i in 0..n {
321 if rng.unit() < p {
322 x_new[i] = reflect01(x_best[i] + sigma * rng.gaussian());
323 included = true;
324 }
325 }
326 if !included {
327 let i = (rng.u64() as usize) % n;
328 x_new[i] = reflect01(x_best[i] + sigma * rng.gaussian());
329 }
330 let s = obj(&x_new);
331 evals += 1;
332 if !s.is_nan() && (best.is_nan() || s > best) {
333 best = s;
334 x_best = x_new;
335 }
336 history.push(best);
337 }
338 OptResult { x: x_best, score: best, evaluations: evals, history }
339}
340
341// ── SCE-UA(Duan et al. 1992) ──────────────────────────────────────
342
343/// 洗牌复杂演化。`obj`:归一化空间 → 分数(最大化)。
344///
345/// Shuffled Complex Evolution — University of Arizona (Duan, Gupta &
346/// Sorooshian 1992). A population-based global optimiser, classical for
347/// conceptual rainfall–runoff calibration.
348///
349/// # Algorithm sketch
350/// 1. **Initialise** a population of `s = p · m` points sampled uniformly in
351/// `[0,1]^n` and scored, where `p = cfg.complexes` (default 5) and
352/// `m = 2n + 1` (so each complex has the recommended sample count). The
353/// population is capped at `budget` if `p · m` would exceed it.
354/// 2. **Partition** the population (sorted best-first) into `p` complexes by
355/// round-robin assignment so each complex spans the full quality range.
356/// 3. **Competitive Complex Evolution (CCE)** per complex: pick `q = min(n+1, m)`
357/// points by triangular rank-weighted sampling (better points more
358/// likely), reflect the worst through the centroid of the best `q−1`
359/// (`x_r = 2·centroid − x_worst`); if that does not beat the worst,
360/// contract (`x_c = 0.5·(centroid + x_worst)`); if that also fails,
361/// mutate uniformly at random. Replace the worst with the new point.
362/// 4. **Shuffle** — re-sort the whole population and re-partition each
363/// generation so good genes migrate between complexes.
364/// 5. Stop when the evaluation `budget` is exhausted.
365///
366/// All out-of-range points are mirrored back into `[0,1]` via an internal
367/// `reflect01` helper (private).
368///
369/// # Arguments
370/// - `n` — parameter dimension. Returns empty result if `0`.
371/// - `obj` — objective `f: [0,1]^n → ℝ` to **maximise**.
372/// - `budget` — total evaluation cap. Returns empty result if `0`.
373/// - `seed` — `xorshift64` seed (deterministic).
374/// - `cfg` — population topology ([`SceConfig`]). `cfg.complexes = 5` is the
375/// original 1992 recommendation for `n ≤ 6`.
376///
377/// # Returns
378/// Best-found `x`, its score, total evaluations actually used (can exceed
379/// `budget` by 1 in the CCE inner loop — see source), and the convergence
380/// history (one entry per generation, i.e. per outer loop iteration).
381pub fn sce_ua_optimize(
382 n: usize,
383 obj: &dyn Fn(&[f64]) -> f64,
384 budget: usize,
385 seed: u64,
386 cfg: SceConfig,
387) -> OptResult {
388 if n == 0 || budget == 0 {
389 return OptResult { x: vec![], score: f64::NEG_INFINITY, evaluations: 0, history: vec![] };
390 }
391 let mut rng = Rng::new(seed);
392 let p = cfg.complexes.max(1);
393 let m = (2 * n + 1).max(3); // 每 complex 点数
394 let q = (n + 1).max(2).min(m); // subcomplex 大小
395 let mut s_size = p * m;
396 if s_size > budget {
397 s_size = budget;
398 }
399 // 1. 初始种群
400 let mut pop: Vec<(Vec<f64>, f64)> = (0..s_size)
401 .map(|_| {
402 let x: Vec<f64> = (0..n).map(|_| rng.unit()).collect();
403 (x.clone(), obj(&x))
404 })
405 .collect();
406 let mut evals = s_size;
407 let mut best_x = pop
408 .iter()
409 .max_by(|a, b| a.1.partial_cmp(&b.1).unwrap_or(std::cmp::Ordering::Equal))
410 .map(|(x, _)| x.clone())
411 .unwrap_or_default();
412 let mut best = pop
413 .iter()
414 .map(|(_, s)| *s)
415 .fold(f64::NEG_INFINITY, f64::max);
416 let mut history = vec![best];
417 // 主循环
418 while evals < budget {
419 // 种群按分数降序(最大化)
420 pop.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
421 // 分配到 p 个 complex(轮转)
422 let mut complexes: Vec<Vec<usize>> = vec![Vec::new(); p];
423 for (i, _) in pop.iter().enumerate() {
424 complexes[i % p].push(i);
425 }
426 // 每 complex 做一次 CCE(产生 1 个新点)
427 for c in 0..p {
428 if evals >= budget {
429 break;
430 }
431 let idxs = &complexes[c];
432 if idxs.is_empty() {
433 continue;
434 }
435 // 三角概率选 q 个进 subcomplex(好的概率高)
436 let mm = idxs.len();
437 let mut chosen: Vec<usize> = Vec::with_capacity(q.min(mm));
438 let mut pool: Vec<usize> = (0..mm).collect();
439 for rank in 0..q.min(mm) {
440 // weight[j] ∝ (mm + 1 - (j+1));按剩余池顺序
441 let wsum: f64 = pool.iter().enumerate().map(|(j, &pi)| {
442 let _ = pi;
443 (mm + 1 - (j + 1)) as f64
444 }).sum();
445 let mut r = rng.unit() * wsum;
446 let mut pick = 0;
447 for (j, _) in pool.iter().enumerate() {
448 r -= (mm + 1 - (j + 1)) as f64;
449 if r <= 0.0 {
450 pick = j;
451 break;
452 }
453 pick = j;
454 }
455 chosen.push(pool.remove(pick));
456 let _ = rank;
457 }
458 // subcomplex 点(按分数降序)
459 let mut sub: Vec<(usize, f64)> = chosen.iter().map(|&ci| (idxs[ci], pop[idxs[ci]].1)).collect();
460 sub.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));
461 let worst_global_idx = sub.last().unwrap().0;
462 // centroid of best (q-1)
463 let qm1 = (sub.len().saturating_sub(1)).max(1);
464 let centroid: Vec<f64> = (0..n)
465 .map(|d| {
466 sub[..qm1].iter().map(|(gi, _)| pop[*gi].0[d]).sum::<f64>() / qm1 as f64
467 })
468 .collect();
469 let x_worst = &pop[worst_global_idx].0;
470 // reflection x_r = 2*centroid - worst
471 let x_r: Vec<f64> = (0..n).map(|d| reflect01(2.0 * centroid[d] - x_worst[d])).collect();
472 let s_r = obj(&x_r);
473 evals += 1;
474 let new_pt = if !s_r.is_nan() && s_r > pop[worst_global_idx].1 {
475 (x_r, s_r)
476 } else {
477 // contraction x_c = 0.5*(centroid + worst)
478 let x_c: Vec<f64> = (0..n)
479 .map(|d| reflect01(0.5 * (centroid[d] + x_worst[d])))
480 .collect();
481 let s_c = obj(&x_c);
482 evals += 1;
483 if !s_c.is_nan() && s_c > pop[worst_global_idx].1 {
484 (x_c, s_c)
485 } else {
486 // mutation:全随机
487 let x_m: Vec<f64> = (0..n).map(|_| rng.unit()).collect();
488 let s_m = obj(&x_m);
489 evals += 1; // mutation 也计入评估数(原漏计 → evaluations 少算)
490 (x_m, s_m)
491 }
492 };
493 let _ = evals; // 三个 CCE 分支(reflect/contract/mutate)均已 evals+=1
494 pop[worst_global_idx] = (new_pt.0, new_pt.1);
495 if new_pt.1 > best || best.is_nan() {
496 best = new_pt.1;
497 best_x = pop[worst_global_idx].0.clone();
498 }
499 }
500 // 洗牌:种群保持(已在 pop 内更新,下轮重新分配)
501 history.push(best);
502 if evals >= budget {
503 break;
504 }
505 }
506 OptResult { x: best_x, score: best, evaluations: evals, history }
507}
508
509// ── Hydro 模型率定包装 ─────────────────────────────────────────────
510
511/// 用 base params JSON + specs 把归一化向量 → 实际参数 JSON(覆盖命名字段)。
512///
513/// Map a normalised decision vector back to the model's params JSON. Each
514/// `x[i] ∈ [0,1]` is mapped through the corresponding [`ParamSpec`] as
515/// `value = min + x[i] · (max − min)` and written into the JSON field
516/// `specs[i].name`. All other fields are inherited unchanged from `base`.
517/// This is what [`calibrate`] / [`evaluate`] use to feed parameters into
518/// `DynHydroModel::set_params_json`.
519///
520/// If `base` is not a JSON object (or `specs` / `x` are empty), `base` is
521/// returned unchanged.
522pub fn vector_to_json(base: &serde_json::Value, specs: &[ParamSpec], x: &[f64]) -> serde_json::Value {
523 let mut v = base.clone();
524 if let Some(obj) = v.as_object_mut() {
525 for (spec, xi) in specs.iter().zip(x.iter()) {
526 let val = spec.min + xi * (spec.max - spec.min);
527 obj.insert(spec.name.clone(), serde_json::json!(val));
528 }
529 }
530 v
531}
532
533/// 评估一次:建模型 → 设参数 → 步进 → 算分数(最大化)。
534///
535/// Single model evaluation: build a fresh model via `make_model`, override
536/// its params from `params` (JSON), step through `forcing`, score the
537/// resulting discharge series against `observed` under `objective`. Returns
538/// the (maximised) score. This is the building block of [`calibrate`]; it is
539/// exposed so callers can re-score a parameter set on a different basin /
540/// period without re-running the optimiser.
541///
542/// The model is **not** reused across calls — `make_model` must return a
543/// fresh default-state instance each time (see [`calibrate`] for the
544/// contract).
545pub fn evaluate(
546 make_model: &dyn Fn() -> Box<dyn DynHydroModel>,
547 forcing: &[Forcing],
548 observed: &[f64],
549 dt_h: f64,
550 params: &serde_json::Value,
551 objective: Objective,
552) -> f64 {
553 let mut m = make_model();
554 m.set_params_json(params);
555 let sim: Vec<f64> = forcing
556 .iter()
557 .map(|f| {
558 m.step(f, dt_h);
559 m.discharge()
560 })
561 .collect();
562 score_of(observed, &sim, objective)
563}
564
565/// 模型率定入口。`make_model`:每次调用返回一个全新默认模型(闭包内 create_model)。
566///
567/// Calibrate a [`DynHydroModel`] against an observed discharge series.
568/// Dispatches to [`dds_optimize`] or [`sce_ua_optimize`] based on `method`,
569/// wrapping each candidate `x` through [`vector_to_json`] so the model sees
570/// physical parameter values.
571///
572/// # Arguments
573/// - `make_model` — closure that returns a **fresh, default-state**
574/// `Box<dyn DynHydroModel>` each call. The optimiser invokes this once per
575/// evaluation; the returned model must start from a clean state (no
576/// residual soil moisture / storage from the previous run). Typical body:
577/// `Box::new(XinanjiangModel::new(XinanjiangParams::default()))`.
578/// - `base_params` — JSON template for the model's params. The fields named
579/// in `specs` will be overwritten; all other fields are inherited
580/// unchanged. Generate via `serde_json::to_value(ModelParams::default())`.
581/// - `specs` — parameters to calibrate, with physical `[min, max]` ranges.
582/// Order determines the order of the optimiser's decision vector.
583/// - `forcing` — driving meteorology (P / PET / T), one entry per time step.
584/// - `observed` — observed discharge series (m³/s), aligned with `forcing`
585/// in time. Must be the same length as `forcing`.
586/// - `dt_h` — time-step length (hours). Forwarded to `HydroModel::step`.
587/// - `objective` — score to maximise; see [`Objective`].
588/// - `method` — which optimiser to run; see [`Method`].
589/// - `budget` — upper bound on model evaluations.
590/// - `seed` — `xorshift64` seed for reproducibility.
591///
592/// # Returns
593/// A [`CalibResult`] with `best_params` already in JSON form (physical
594/// values), `best_score` in `objective`'s units, total evaluations
595/// performed, and the convergence history.
596///
597/// # Example
598/// See `examples/calibrate_xaj.rs` for a runnable end-to-end calibration of
599/// `hydro-xinanjiang`'s `sm` / `kg`.
600pub fn calibrate(
601 make_model: &dyn Fn() -> Box<dyn DynHydroModel>,
602 base_params: &serde_json::Value,
603 specs: &[ParamSpec],
604 forcing: &[Forcing],
605 observed: &[f64],
606 dt_h: f64,
607 objective: Objective,
608 method: Method,
609 budget: usize,
610 seed: u64,
611) -> CalibResult {
612 let base = base_params.clone();
613 let specs_owned: Vec<ParamSpec> = specs.to_vec();
614 let obj = |x: &[f64]| {
615 let json = vector_to_json(&base, &specs_owned, x);
616 evaluate(make_model, forcing, observed, dt_h, &json, objective)
617 };
618 let opt = match method {
619 Method::Dds => dds_optimize(specs.len(), &obj, budget, seed),
620 Method::SceUa => sce_ua_optimize(specs.len(), &obj, budget, seed, SceConfig::default()),
621 };
622 CalibResult {
623 best_params: vector_to_json(base_params, specs, &opt.x),
624 best_score: opt.score,
625 evaluations: opt.evaluations,
626 history: opt.history,
627 }
628}
629
630#[cfg(test)]
631mod tests {
632 use super::*;
633
634 fn quadratic(x: &[f64]) -> f64 {
635 // 最大化 → 最优 (0.7, 0.3),分数 0
636 -((x[0] - 0.7).powi(2) + (x[1] - 0.3).powi(2))
637 }
638
639 #[test]
640 fn dds_converges_quadratic() {
641 let r = dds_optimize(2, &quadratic, 500, 42);
642 assert!((r.x[0] - 0.7).abs() < 0.08, "x0→0.7, 得 {} score {}", r.x[0], r.score);
643 assert!((r.x[1] - 0.3).abs() < 0.08, "x1→0.3, 得 {}", r.x[1]);
644 assert!(r.score > -0.05, "score 应≈0, 得 {}", r.score);
645 assert_eq!(r.evaluations, 500);
646 }
647
648 #[test]
649 fn sce_ua_converges_quadratic() {
650 let r = sce_ua_optimize(2, &quadratic, 800, 42, SceConfig::default());
651 assert!((r.x[0] - 0.7).abs() < 0.08, "x0→0.7, 得 {} score {}", r.x[0], r.score);
652 assert!((r.x[1] - 0.3).abs() < 0.08, "x1→0.3, 得 {}", r.x[1]);
653 assert!(r.score > -0.05, "score 应≈0, 得 {}", r.score);
654 }
655
656 #[test]
657 fn reflect01_bounces() {
658 assert!((reflect01(-0.3) - 0.3).abs() < 1e-9);
659 assert!((reflect01(1.4) - 0.6).abs() < 1e-9);
660 assert!(reflect01(0.5) >= 0.0 && reflect01(0.5) <= 1.0);
661 }
662
663 #[test]
664 fn vector_to_json_maps_bounds() {
665 let base = serde_json::json!({"a": 0.0, "b": 0.0, "c": 99.0});
666 let specs = vec![
667 ParamSpec { name: "a".into(), min: 10.0, max: 30.0 },
668 ParamSpec { name: "b".into(), min: -5.0, max: 5.0 },
669 ];
670 let v = vector_to_json(&base, &specs, &[1.0, 0.5]);
671 assert_eq!(v["a"], 30.0);
672 assert_eq!(v["b"], 0.0);
673 assert_eq!(v["c"], 99.0, "未率定字段保持 base");
674 }
675
676 #[test]
677 fn rng_deterministic() {
678 let mut r1 = Rng::new(123);
679 let mut r2 = Rng::new(123);
680 for _ in 0..10 {
681 assert_eq!(r1.u64(), r2.u64());
682 }
683 }
684
685 /// 真模型端到端:用 XAJ(sm=25,kg=0.4) 生成"观测",从 base(sm=15,kg=0.3)
686 /// 率定 sm/kg,验证能恢复出接近一致的流量过程线(NSE 高)。
687 #[test]
688 fn calibrate_xinanjiang_recovers_known_hydrograph() {
689 use hydro_core::{DynHydroModel, Forcing, HydroModel};
690 use hydro_xinanjiang::{XinanjiangModel, XinanjiangParams};
691
692 let forcing: Vec<Forcing> = (0..48)
693 .map(|i| Forcing {
694 p_mm: if i < 6 { 25.0 } else { 0.0 },
695 pet_mm: 2.0,
696 t_c: 20.0,
697 })
698 .collect();
699 let dt_h = 1.0;
700 // 观测 = 真值参数跑出来的流量
701 let mut truth = XinanjiangParams::default();
702 truth.sm = 25.0;
703 truth.kg = 0.4;
704 truth.area_km2 = 1000.0;
705 let observed: Vec<f64> = {
706 let mut m: Box<dyn DynHydroModel> = Box::new(XinanjiangModel::new(truth.clone()));
707 forcing.iter().map(|f| { m.step(f, dt_h); m.discharge() }).collect()
708 };
709 // base = 真值但 sm/kg 故意设错(待率定)
710 let mut base = truth.clone();
711 base.sm = 15.0;
712 base.kg = 0.3;
713 let base_json = serde_json::to_value(&base).unwrap();
714
715 let specs = vec![
716 ParamSpec { name: "sm".into(), min: 5.0, max: 50.0 },
717 ParamSpec { name: "kg".into(), min: 0.1, max: 0.7 },
718 ];
719 let factory = || -> Box<dyn DynHydroModel> {
720 Box::new(XinanjiangModel::new(XinanjiangParams::default()))
721 };
722 let r = calibrate(&factory, &base_json, &specs, &forcing, &observed, dt_h, Objective::Nse, Method::Dds, 400, 7);
723 assert!(r.best_score > 0.85, "率定后 NSE 应>0.85, 得 {}", r.best_score);
724 // 率定出的 sm/kg 应接近真值
725 let sm = r.best_params["sm"].as_f64().unwrap();
726 let kg = r.best_params["kg"].as_f64().unwrap();
727 assert!((sm - 25.0).abs() < 6.0, "sm 应→25, 得 {}", sm);
728 assert!((kg - 0.4).abs() < 0.15, "kg 应→0.4, 得 {}", kg);
729 }
730}