hydro-topmodel
TOPMODEL (Beven & Kirkby 1979) — 11-parameter distributed model, clean-room port of the R
topmodelv0.7.5 C numerical core.
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
[]
= "0.1.1"
Quickstart
use ;
use ;
let mut model = new;
let dt_h = 1.0;
let forcing: = .map.collect;
let q: = forcing.iter.map.collect;
let peak = q.iter.cloned.fold;
println!;
Run the full example:
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
topidxhistogram 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 TopidxHistogram;
let topidx = TopidxHistogram ;
channel delay histogram — distance-to-outlet distribution
use ChannelDelay;
let channel = ChannelDelay ;
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), withqss = exp(lnTe + ln(dt) − λ)andλthe areal integral ofln(a/tanβ). - Local deficit (eq 18.8):
S[j] = S_mean + m · (λ − atb[j]), distributing the basin-mean deficitS_meanacross 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 + qois distributed across delay lagsQt[k] += qt · Ad[j]withk = i + j + ndelay.
Verification / Provenance
tests/topmodel_crosscheck.rs— bit-exact crosscheck against Rtopmodelon 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 undertests/topmodel_data/, generated byvalidation/topmodel/gen_reference.R(run once: needs R + thetopmodelpackage +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
hydro-core— traits, forcing types, evaluation metricshydro-xinanjiang— Xinanjiang model (saturation-excess)hydro-swat— SWAT+ LTE hydrology-only subsethydro-apicont— API-CONT continuous baselinehydro-calib— DDS + SCE-UA calibratorhydro-platform— multi-model orchestration + scenario comparisonhydro-suite— umbrella crate (one dependency for the full suite)
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 校验)。
安装:
[]
= "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 统一编排。