hydro-topmodel 0.1.1

TOPMODEL hydrological model (Beven & Kirkby 1979, 11-param distributed, bit-exact vs R topmodel)
Documentation
  • Coverage
  • 100%
    32 out of 32 items documented0 out of 6 items with examples
  • Size
  • Source code size: 1.3 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 360.8 kB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 11s Average build duration of successful builds.
  • all releases: 10s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Repository
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • virki

hydro-topmodel

TOPMODEL (Beven & Kirkby 1979) — 11-parameter distributed model, clean-room port of the R topmodel v0.7.5 C numerical core.

crates.io docs.rs license

hydro-topmodel is a faithful Rust implementation of TOPMODEL (Beven & Kirkby 1979; 1995 Fortran release), the classic variable-source-area rainfall–runoff model. Each step runs Green–Ampt infiltration, eq 6.33 baseflow recession, eq 18.8 local-deficit saturation-excess production, eq 6.26 unsaturated drainage, and kinematic channel routing driven by a topographic wetness index (TWI) histogram and a channel-delay histogram.

Clean-room statement: this is a clean-room port of the C numerical core of the R topmodel package v0.7.5 (core_topmodel.c / get_f.c / param_init.c / misc.c). The algorithm (Beven's published equations) is not copyrightable; the C source was used only as a behaviour oracle for cross-verification. No R/C source code is reproduced here.

Install

[dependencies]
hydro-topmodel = "0.1.1"

Quickstart

use hydro_core::{Forcing, HydroModel};
use hydro_topmodel::{TopmodelModel, TopmodelParams};

let mut model = TopmodelModel::new(TopmodelParams::default());
let dt_h = 1.0;
let forcing: Vec<Forcing> = (0..48).map(|i| Forcing {
    p_mm: if (5..15).contains(&i) { 10.0 } else { 0.0 },
    pet_mm: 1.0,
    t_c: 15.0,
}).collect();

let q: Vec<f64> = forcing.iter().map(|f| {
    model.step(f, dt_h);
    model.discharge()
}).collect();

let peak = q.iter().cloned().fold(f64::NEG_INFINITY, f64::max);
println!("peak Q = {:.2} m^3/s", peak);

Run the full example:

cargo run --example topmodel_demo

Note: with default parameters the model degrades to a lumped single-TWI-class configuration (degenerate hydrograph) — this is expected and useful for smoke tests. Real distributed runs require a basin topidx histogram and a channel delay histogram; see Inputs below.

Inputs

TOPMODEL needs two distributed inputs in addition to scalar parameters. Both come from a basin DEM (e.g. via topmodel::topidx() in R, or any TWI pipeline).

topidx histogram — basin TWI distribution

use hydro_topmodel::TopidxHistogram;

let topidx = TopidxHistogram {
    // ln(a/tanβ) values, DESCENDING order (wettest class first)
    atb: vec![8.0, 7.5, 7.0, /* ... */],
    // Cumulative area fraction at the lower bound of each class (ends at 1.0)
    Aatb_r: vec![0.05, 0.20, 0.45, /* ... */ 1.0],
};

channel delay histogram — distance-to-outlet distribution

use hydro_topmodel::ChannelDelay;

let channel = ChannelDelay {
    // Channel distance (m), ASCENDING order
    d: vec![100.0, 400.0, 1200.0, /* ... */],
    // Cumulative drained-area fraction for each distance class
    Ad_r: vec![0.10, 0.35, 0.70, /* ... */ 1.0],
};

The huagrahuma reference dataset (the standard TOPMODEL test basin, used in Beven 1997 and shipped with the R topmodel package) is the recommended source for cross-verification. Install R topmodel and load system.file("huagrahuma", package = "topmodel").

Parameters

Field Unit Physical meaning Typical range
qs0 m/h Initial baseflow per unit area (seeds S_mean[0] via eq 6.33) calibrated
lnTe ln(m²/h) Areal average of ln(T₀) (saturated effective transmissivity) ~5
m m Exponential recession scale (1/m in eq 6.33 + 18.8) 0.01–0.05
Sr0 m Initial root-zone storage deficit 0–0.1
Srmax m Maximum root-zone storage deficit (bounds actual ET) 0.03–0.1
td h/m Unsaturated-zone time delay per unit deficit (eq 6.26 scale) 10–50
vch m/h Channel wave velocity (tch[0] = d[0]/(vch·dt)) 1e3–1e4
vr m/h Overland / hillslope wave velocity 1e2–1e4
K0 m/h Saturated hydraulic conductivity (Green–Ampt infiltration) 0.5–10
CD m Capillary drive at the wetting front 0.1–2.0
dt h Internal model time step 1 (hourly)
topidx — Optional TWI histogram; None → lumped single-class from DEM
channel — Optional channel-delay histogram; None → instant outflow from DEM
area_km2 km² Basin area (mm/Δt → m³/s conversion only) basin-specific

Key equations

Equation numbers follow Beven, Hydrological Processes / R topmodel source comments:

  • Baseflow recession (eq 6.33): qs = qss · exp(−S_mean / m), with qss = exp(lnTe + ln(dt) − λ) and λ the areal integral of ln(a/tanβ).
  • Local deficit (eq 18.8): S[j] = S_mean + m · (λ − atb[j]), distributing the basin-mean deficit S_mean across TWI classes.
  • Unsaturated drainage (eq 6.26): qv = suz / (S · td) · dt, draining the unsaturated store into the saturated zone.
  • Infiltration: Green–Ampt / Morel-Seytoux solved by Newton-Raphson with ponding-state tracking across time steps.
  • Routing: each step's lateral inflow qt = qs + qo is distributed across delay lags Qt[k] += qt · Ad[j] with k = i + j + ndelay.

Verification / Provenance

  • tests/topmodel_crosscheck.rs — bit-exact crosscheck against R topmodel on the huagrahuma dataset. Pass criterion: 6 sequences (Q / qs / qo / S_mean / fex / Ea) per-variable NSE > 0.999 and relative bias < 0.1 %. Reference data lives under tests/topmodel_data/, generated by validation/topmodel/gen_reference.R (run once: needs R + the topmodel package + jsonlite).
  • 4 in-crate unit tests cover λ identity for the degenerate single-class case, rain→flow response, mass conservation under constant rain, and dynamic dispatch via Box<dyn DynHydroModel>.

Run them with cargo test.

Related crates

License

MIT.


中文

hydro-topmodel 是 TOPMODEL(Beven & Kirkby 1979;1995 Fortran 版)的忠实 Rust 实现,经典变动源区降雨–径流模型。单步演算包含 Green–Ampt 下渗、eq 6.33 基流退水、 eq 18.8 局部亏缺(分布式饱和溢流)、eq 6.26 非饱和排水,以及由 TWI 直方图 + 河道 延迟直方图驱动的运动波河道汇流。

**Clean-room 声明:**从 R topmodel 包 v0.7.5 的 C 数值核心(core_topmodel.c / get_f.c / param_init.c / misc.c)净室移植;算法(Beven 公式)不可版权, C 源仅作行为 oracle,不复制任何 R/C 源代码。单位 mm/h(与 R 参考一致,便于 bit-exact 校验)。

安装:

[dependencies]
hydro-topmodel = "0.1.1"

默认参数退化成集总(单 TWI 类)——输出可能看起来很小/退化,这是预期行为,便于 冒烟测试。真实分布式运行必须从流域 DEM 提供 topidx(TWI 直方图),通常还需 channel(河道延迟直方图);huagrahuma 数据集从 R topmodel 包 system.file("huagrahuma", package = "topmodel") 获取。

交叉验证在 tests/topmodel_crosscheck.rs(6 序列 NSE>0.999 + 相对偏差<0.1%, oracle 由 validation/topmodel/gen_reference.R 生成)。实现了 hydro_core::HydroModel trait,可被 hydro-platform 统一编排。