Skip to main content

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}