Skip to main content

Crate hydro_calib

Crate hydro_calib 

Source
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.08 absolute error.
  • calibrate_xinanjiang_recovers_known_hydrograph — DDS recovers synthetic-truth sm / kg for hydro-xinanjiang with NSE > 0.85.

Structs§

CalibResult
率定结果(参数 JSON + 最优分数 + 评估次数 + 收敛历史)。
OptResult
优化器原始结果(归一化空间)。
ParamSpec
单个率定参数:JSON 字段名 + 区间(归一化 x∈[0,1] 映射到 [min,max])。
SceConfig
SCE-UA 配置(默认:complexes=5,每 complex m=2n+1 点,subcomplex q=n+1)。

Enums§

Method
率定方法。
Objective
率定目标(皆“越大越好“;RMSE 取负)。

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(覆盖命名字段)。