Skip to main content

Crate hydro_topmodel

Crate hydro_topmodel 

Source
Expand description

TOPMODEL(Beven & Kirkby 1979;1995 Fortran 版)——忠实分布式实现。

Clean-room 从 R topmodel 包 v0.7.5 的 C 数值核心(core_topmodel.c/get_f.c/ param_init.c/misc.c)移植:算法(Beven 公式)不可版权,C 源仅作行为 oracle。 11 参数 + TWI 直方图 + 河道延迟;单位 mm / hour(与 R 参考一致,便于 bit-exact 校验)。 交叉验证:tests/topmodel_crosscheck.rs(待加)vs R topmodel on huagrahuma 数据集。

关键方程(eq 号同 Beven HESS 2021 / R 源注释):

  • 基流退水 qs = qss·exp(-S_mean/m)(eq 6.33),qss = exp(lnTe + ln(dt) - λ)
  • 局部亏缺 S[j] = S_mean + m·(λ - atb[j])(eq 18.8)
  • 非饱和排水 qv = Suz/(S·td)·dt(eq 6.26)
  • 下渗 Green-Ampt/Morel-Seytoux(Newton-Raphson,get_f)
  • 路由:河道延迟 Qt[k] += qt·Ad[j],k = i + j + ndelay

§English summary

TOPMODEL (Beven & Kirkby 1979; 1995 Fortran release) — faithful distributed implementation. Hydrological quantities are kept in mm per hour to match the R reference numerically and enable bit-exact regression.

Clean-room statement: this Rust implementation 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 underlying 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.

The model takes 11 scalar parameters plus a topographic wetness index (TWI) histogram and an optional channel-delay histogram, and produces per-step output series (outflow, baseflow, saturation-excess runoff, mean saturation deficit, infiltration, infiltration excess, actual ET).

Key equations (equation numbers follow Beven, Hydrological Processes / R source comments):

  • Baseflow recession qs = qss · exp(−S_mean / m) (eq 6.33), where qss = exp(lnTe + ln(dt) − λ).
  • Local deficit S[j] = S_mean + m · (λ − atb[j]) (eq 18.8).
  • Unsaturated drainage qv = Suz / (S · td) · dt (eq 6.26).
  • Infiltration: Green–Ampt / Morel-Seytoux solved by Newton-Raphson (the crate-internal Infiltration::get_f).
  • Routing: channel delay Qt[k] += qt · Ad[j], with k = i + j + ndelay.

Cross-verification: tests/topmodel_crosscheck.rs against R topmodel on the huagrahuma dataset (available from the R topmodel package).

Implements hydro_core::HydroModel so the model can be orchestrated by hydro-platform. With default parameters the model degrades to a lumped single-TWI-class configuration; supply a real topidx histogram for distributed runs.

Structs§

ChannelDelay
Channel-delay histogram describing how long it takes water to travel to the outlet from each distance class.
TopidxHistogram
TWI (topographic wetness index) histogram, the distributed input that partitions the basin into saturation classes.
TopmodelModel
hydro_core::HydroModel wrapper that runs TOPMODEL one step at a time.
TopmodelOutput
Full per-step output of run_topmodel_full, all in mm per dt step. Each Vec has one entry per input time step, suitable for direct variable-by-variable comparison against the R topmodel oracle.
TopmodelParams
TOPMODEL parameters: 11 scalar model parameters plus the basin TWI histogram, the optional channel-delay histogram, and the basin area used to convert mm/Δt to m³/s.

Functions§

run_topmodel_full
Run the full TOPMODEL loop step-by-step, mirroring the R topmodel run sequence (param_init → per-step production + routing). All inputs and outputs are in mm per dt step so the result can be compared variable-by-variable against the R reference.