Expand description
hydro-calib: 模型无关率定器(对标 SPOTPY/OSTRICH)。
针 hydro_core::DynHydroModel trait(set_params_json + step/discharge 管线已就绪)。
两个原生 Rust 全局优化器:
- DDS(Tolson & Shoemaker 2007):动态降维搜索,少评估、稳健,默认首选。
- SCE-UA(Duan et al. 1992):洗牌复杂演化,经典、强收敛,评估多。
目标函数可插拔(NSE/KGE/logNSE/DC/NegRMSE),归一化决策变量
[0,1]→实际参数区间。
§English
hydro-calib is a model-agnostic calibrator for any type that implements
hydro_core::DynHydroModel. It pairs two native-Rust global optimisers —
DDS and SCE-UA — with pluggable objective functions
(NSE / KGE / log-NSE / DC / −RMSE) and normalised decision variables
(x ∈ [0,1] per parameter, mapped to the named field’s [min, max] range
inside the model’s JSON params). The calibration entry point is
calibrate; the underlying optimisers (dds_optimize, sce_ua_optimize)
are also exposed for general black-box use.
§Optimisers
- Dynamically Dimensioned Search (DDS) — Tolson & Shoemaker (2007),
“Cannonsim Hydrologic Model Calibrations with Implicitly Generated
Dynamically Dimensioned Search”, Water Resources Research 43,
W01422. A single-trajectory greedy search whose per-dimension inclusion
probability decays as
P(m) = 1 − ln(m)/ln(M)— coarse global early, fine local late. Best default when the evaluation budget is modest (≤ a few hundred model runs) and the response surface is moderately rough. - Shuffled Complex Evolution (SCE-UA) — Duan, Gupta & Sorooshian (1992), “Effective and Efficient Model Global Optimization for the Conceptual Rainfall-Runoff Models”, Water Resources Research 28, pp. 1015–1031. A population-based method that partitions candidates into complexes, evolves each with competitive complex evolution (Nelder–Mead style reflection / contraction / mutation), and reshuffles. Strong convergence at the cost of more evaluations; classic for conceptual rainfall–runoff models.
§Determinism / dependencies
Both optimisers draw randomness from an internal xorshift64
pseudo-random generator seeded by the caller (seed: u64). The same
seed reproduces the same trajectory bit-for-bit across platforms. The
generator is the only source of randomness; there are zero external
dependencies beyond hydro-core (for the model trait + forcing) and
serde_json (for parameter overrides). No rand, no BLAS, no platform
RNG.
§Verification
dds_converges_quadratic/sce_ua_converges_quadratic— both optimisers recover the known optimum(0.7, 0.3)of a 2-D quadratic bowl to< 0.08absolute error.calibrate_xinanjiang_recovers_known_hydrograph— DDS recovers synthetic-truthsm/kgforhydro-xinanjiangwith NSE> 0.85.
Structs§
- Calib
Result - 率定结果(参数 JSON + 最优分数 + 评估次数 + 收敛历史)。
- OptResult
- 优化器原始结果(归一化空间)。
- Param
Spec - 单个率定参数:JSON 字段名 + 区间(归一化
x∈[0,1]映射到[min,max])。 - SceConfig
- SCE-UA 配置(默认:complexes=5,每 complex m=2n+1 点,subcomplex q=n+1)。
Enums§
Functions§
- calibrate
- 模型率定入口。
make_model:每次调用返回一个全新默认模型(闭包内 create_model)。 - dds_
optimize - 动态降维搜索。
obj:归一化空间[0,1]^n→ 分数(最大化)。budget:模型评估上限。 - evaluate
- 评估一次:建模型 → 设参数 → 步进 → 算分数(最大化)。
- log_nse
- 对数空间 NSE(枯水敏感):NSE on ln(Q+ε)。
- sce_
ua_ optimize - 洗牌复杂演化。
obj:归一化空间 → 分数(最大化)。 - vector_
to_ json - 用 base params JSON + specs 把归一化向量 → 实际参数 JSON(覆盖命名字段)。