hydro-platform
Multi-model hydrology orchestration: run 新安江 / TOPMODEL / SWAT / API-CONT on one basin, compare, and score (NSE / KGE / CRPS + GB/T 22482).
hydro-platform is the orchestration layer of the hydro-suite multi-model
hydrology platform. Build a single [Scenario] (basin + forcing + selected
models + optional observation), call [run_scenario], and you get back a
[ComparisonResult] holding every model's discharge hydrograph (m³/s) plus —
when an observation is supplied — full evaluation metrics (NSE / KGE / RMSE /
PBIAS / R² + GB/T 22482-2008 flood-forecast qualification). Multi-model
ensemble diagnostics (per-step mean / median / quartiles, fair CRPS / Brier /
POD-FAR-CSI, Talagrand rank histogram) and event-based SCS unit-hydrograph
forecasting are also included.
All four models are constructed behind the shared hydro_core::DynHydroModel
trait via JSON parameter blobs, so adding a new model to a scenario is a
one-line change. The platform itself adds no numerical content of its own —
it dispatches to the four model crates and to hydro-core's metrics.
Install
[]
= "0.1.0"
Quickstart
use ;
use ;
let forcing: = .map.collect;
let scenario = Scenario ;
let res = run_scenario;
for r in &res.results
let stats = ensemble_stats;
let mean_peak = stats.mean.iter.cloned.fold;
println!;
Run the full example:
Re-exports
hydro-platform re-exports the common items from its dependencies so you can
write most workflows without naming the member crates individually:
| Re-exported from | What you get |
|---|---|
hydro_core |
HydroModel / DynHydroModel traits, Forcing, BasinInfo, Outlet, ModelType, the full metrics toolkit (compute_metrics, compute_metrics_gbt, crps, brier, pod_far_csi, ensemble_exceedance, compute_probabilistic, rank_histogram), and the GB/T 22482 qualification types (GbtEventErrors, QualificationTolerance, QualificationReport). |
hydro_calib |
calibrate, ParamSpec, Objective, Method, SceConfig, CalibResult. |
The four model crates (hydro-xinanjiang, hydro-topmodel, hydro-swat,
hydro-apicont) are dependencies used internally by [create_model] /
[run_scenario]; reach into them directly when you need to construct
parameter structs (use hydro_xinanjiang::XinanjiangParams;).
Workflow
A typical multi-model run is three steps:
- Build a [
Scenario] — fillbasin(BasinInfo),forcing(aVec<Forcing>),dt_h(hours), and themodelslist (Vec<ModelType>). Optionally populateobserved(discharge series of the same length asforcing) to enable per-model metrics, andparams_overrides(JSON keyed byModelType::name()) to swap in non-default parameters per model. - Call [
run_scenario] — every selected model is built via [create_model] from its resolved params, stepped through the forcing, and its discharge recorded at each step. Returns a [ComparisonResult] whoseresultskeep the order ofscenario.modelsand whosetime_stepsequalsscenario.forcing.len(). - Inspect / aggregate — read per-member
ModelResult::dischargeand (optional)metrics; call [ComparisonResult::best_nse] for the best-fitting member; feed the result into [ensemble_stats] (per-step mean / median / min / max / p25 / p75), [ensemble_probabilistic] (fair CRPS / Brier / POD-FAR-CSI at a discharge threshold), or [ensemble_rank_histogram] (Talagrand reliability, M+1 bins).
For event-based design-storm routing (no continuous state), use
[event_uh_forecast] with a unit hydrograph kernel — e.g. one built by
[scs_unit_hydrograph] — independently of the HydroModel trait.
Verification / Provenance
- 7 unit tests cover scenario execution across all four models, observation
wiring (XAJ-vs-itself NSE > 0.99), default-params JSON shape, dynamic
dispatch via
create_model, the ensemble stats reducer, and the SCS unit-hydrograph + event-UH-forecast helpers. - The platform itself adds no numerical content — it dispatches to the
four model crates (each independently verified, see their READMEs) and to
hydro-core's metrics. Bit-exactness is preserved per member model.
Run them with cargo test.
Related crates
hydro-core— traits, forcing types, evaluation metricshydro-xinanjiang— distributed Xinanjiang model (3-source + UH routing)hydro-topmodel— TOPMODEL (Beven & Kirkby 1979)hydro-swat— SWAT+ LTE hydrology-only subsethydro-apicont— API-CONT continuous baselinehydro-calib— DDS + SCE-UA calibratorhydro-suite— umbrella crate (one dependency for the full suite)
License
MIT.
中文
hydro-platform 是 hydro-suite 多模型水文平台的编排层。构造一个
[Scenario](basin + forcing + 选择模型 + 可选观测),调用 [run_scenario],
即可得到一个 [ComparisonResult]:包含每个模型的出流过程线(m³/s)+ 可选的
完整评价指标(NSE / KGE / RMSE / PBIAS / R² + GB/T 22482-2008 洪水预报合格
判定)。同时提供多模型集合诊断(逐时步均值/中位/分位、fair CRPS / Brier /
POD-FAR-CSI、Talagrand 秩直方图)与基于事件的 SCS 单位线预报。
四个模型都通过共享的 hydro_core::DynHydroModel trait + JSON 参数构造,
切换模型只需改 Scenario::models 一行。本 crate 自身不引入任何数值内容,
仅做派发——数值正确性由四个模型 crate 与 hydro-core 指标各自守护。
Re-exports:从 hydro-platform 一行 use 即可拿到 hydro-core 的 trait
- forcing + 全套指标(NSE / KGE / CRPS + GB/T 22482 合格)与
hydro-calib的calibrate/ParamSpec/Objective/Method。四个模型 crate 是本 crate 的依赖,在 [create_model] / [run_scenario] 内部使用;需要构造具体 参数结构时直接use hydro_xinanjiang::XinanjiangParams;即可。
工作流:(1) 构造 [Scenario];(2) 调用 [run_scenario] 得到
[ComparisonResult];(3) 读取每个成员的 discharge/metrics,或用
[ensemble_stats] / [ensemble_probabilistic] / [ensemble_rank_histogram]
做集合诊断;事件制汇流用 [event_uh_forecast] + [scs_unit_hydrograph]。
安装:
[]
= "0.1.0"
7 条单元测试覆盖:四模型 scenario 执行、观测接入(XAJ-vs-自身 NSE > 0.99)、
默认参数 JSON 形状、create_model 动态派发、集合统计 reducer、SCS 单位线 +
事件单位线预报辅助函数(cargo test)。