hydro-platform 0.1.0

Multi-model hydrology platform: scenario orchestration, comparison, and metrics
Documentation

hydro-platform

Multi-model hydrology orchestration: run 新安江 / TOPMODEL / SWAT / API-CONT on one basin, compare, and score (NSE / KGE / CRPS + GB/T 22482).

crates.io docs.rs license

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

[dependencies]
hydro-platform = "0.1.0"

Quickstart

use hydro_core::{BasinInfo, Forcing, ModelType};
use hydro_platform::{run_scenario, ensemble_stats, Scenario};

let forcing: Vec<Forcing> = (0..48).map(|i| Forcing {
    p_mm: if (8..20).contains(&i) { 6.0 } else { 0.0 },
    pet_mm: 2.0,
    t_c: 18.0,
}).collect();

let scenario = Scenario {
    basin: BasinInfo {
        id: "demo".into(), name: "Demo".into(),
        area_km2: 1000.0, outlet_lat: 30.0, outlet_lon: 120.0,
    },
    forcing,
    dt_h: 1.0,
    models: vec![ModelType::Xinanjiang, ModelType::Topmodel,
                 ModelType::Swat, ModelType::Apicont],
    observed: None,
    params_overrides: None,
};

let res = run_scenario(&scenario);
for r in &res.results {
    let peak = r.discharge.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
    println!("{:10}: peak Q = {:7.2} m^3/s", r.name, peak);
}
let stats = ensemble_stats(&res);
let mean_peak = stats.mean.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
println!("ensemble mean peak = {:.2} m^3/s", mean_peak);

Run the full example:

cargo run --example compare_demo

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:

  1. Build a [Scenario] — fill basin (BasinInfo), forcing (a Vec<Forcing>), dt_h (hours), and the models list (Vec<ModelType>). Optionally populate observed (discharge series of the same length as forcing) to enable per-model metrics, and params_overrides (JSON keyed by ModelType::name()) to swap in non-default parameters per model.
  2. 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] whose results keep the order of scenario.models and whose time_steps equals scenario.forcing.len().
  3. Inspect / aggregate — read per-member ModelResult::discharge and (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

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]。

安装:

[dependencies]
hydro-platform = "0.1.0"

7 条单元测试覆盖:四模型 scenario 执行、观测接入(XAJ-vs-自身 NSE > 0.99)、 默认参数 JSON 形状、create_model 动态派发、集合统计 reducer、SCS 单位线 + 事件单位线预报辅助函数(cargo test)。