[MODEL] mizuRoute #132

Proposer

Yuanhang Liu, Independent Researcher, Changchun, China. ORCID 0009-0005-9633-6004

Model name

mizuRoute

Model category

physics

Model code repository

https://github.com/ESCOMP/mizuRoute

Version, release, or commit

v3.1.1, tag commit 28514dea3fd28a2f820c7ecaa9014f820c1bb220, released 2026-04-15.

Weights repository (optional)

None required.

Paper or model reference (optional)

https://doi.org/10.5194/gmd-9-2223-2016 — Mizukami, Clark, Sampson, Nijssen, Mao, McMillan, Viger, Markstrom, Hay, Woods, Arnold and Brekke (2016), mizuRoute version 1: a river network routing tool for a continental domain water resources applications, Geoscientific Model Development 9(6):2223-2238.

https://doi.org/10.5194/hess-27-3505-2023 — Cortés-Salazar, Vásquez, Mizukami, Mendoza and Vargas (2023), To what extent does river routing matter in hydrological modeling?, Hydrology and Earth System Sciences 27:3505-3524. Describes the Euler kinematic wave and diffusive wave schemes added after version 1.

Documentation: https://mizuroute.readthedocs.io/ . Concept DOI: https://doi.org/10.5281/zenodo.595402 .

Code and weights licenses

Code: Apache-2.0 (LICENSE.txt; GitHub reports Apache-2.0). No weights.

Supported timestep

PT1H (hourly) — its documented configuration. Every example control file in docs/source/users_guide/Control_file.rst sets <dt_qsim> to 3600 s, and the history-output rules state that <dt_qsim> must be less than 86400 s, so daily aggregation is reachable but hourly is the native step.

Required inputs

Forcing: runoff, not weather. mizuRoute consumes lateral runoff depth, not precipitation, temperature or potential evapotranspiration. The control file names the runoff NetCDF with <fname_qsim> and its units with <units_qsim>, accepting m or mm over s, h or d (e.g. mm/s), with <dt_rof> giving the runoff interval in seconds. The suite's pr/tas/pet forcing is not an input to this model.

Static: a river network NetCDF carrying segId, downSegId, hruSegId, HRUid, reach length, reach slope and HRU area (the variable names are configurable); hillslope unit-hydrograph parameters (a gamma shape/scale pair, or the equivalent tscale/wscale); and optionally per-reach Manning n and channel bottom width. Without the optional per-reach hydraulics mizuRoute derives bottom width and bankfull depth from simple functions of upstream area.

Initialization: cold start, or a restart NetCDF carrying channel states from the step immediately preceding the resume point.

Outputs produced by the model

dis — river discharge

Its native history output is a per-reach netCDF table indexed by time, basinID and reachID, and it carries the three quantities the suite's new reach-indexed routing contract asks for:

• <outputInflow> — inflow [m3/s] to each reach, for all active routing methods;
• <IRFroutedRunoff>, <KWTroutedRunoff>, <KWroutedRunoff>, <MCroutedRunoff>, <DWroutedRunoff> — outflow [m3/s] from each reach, one per routing scheme;
• <IRFvolume>, <KWTvolume>, <KWvolume>, <MCvolume>, <DWvolume> — volume [m3] in each reach, one per routing scheme.

Those map onto emits.routing: [q_in, q_out, channel_storage] directly, per reach.

What is deliberately not claimed, and why it is checkable. mizuRoute has no land phase: it does not partition precipitation, does not transpire, and does not carry soil or snow storage. pr, evspsbl, mrro, mrso, snw and canopy are therefore not claimed, and every probe whose requires.fluxes/requires.states names any of them returns N/A (INCOMPLETE) for this model. That is the honest outcome and it is stated here rather than left to be discovered.

Evaluation window (optional)

Default.

Packaging status

Help is needed with both Docker packaging and the adapter.

Installation and inference notes

Fortran 90 or later, built with CMake against netCDF; CPU-only, no network at inference, and modest memory on a small synthetic network. The repository builds in CI. A run is driven by a namelist control file plus three NetCDF inputs — the river network topology, the runoff time series, and the hillslope unit-hydrograph parameters.

The adapter's real work is to synthesise a small network consistent with the probe's declared reaches, write the generated inflow as a runoff NetCDF on the model's grid, choose a routing scheme with <route_opt> (1 IRF, 2 Lagrangian kinematic wave, 3 Euler kinematic wave, 4 Muskingum-Cunge, 5 diffusive wave), run, and parse the per-reach history file into routing.csv with time, reach_id, q_in, q_out, channel_storage. <outputFrequency> must be set so the history file lands on the probe's forcing interval. The restart mechanism gives a clean way to carry channel storage across the spinup boundary.

Why this model belongs in the benchmark

No merged model is mizuRoute and no open or closed proposal names it (checked against models/*/model.yaml and the full issue list, including closed issues, on 2026-09-20). The closest entry is RVIC, accepted as #119 — also a routing-only model, also taking runoff rather than weather. RVIC is the grid-based, source-to-outlet convolution of Lohmann et al.; mizuRoute is the reach-based vector-network model, and the two are different structures rather than duplicates.

The field. mizuRoute is the river routing component of CTSM/CESM at NCAR and is used for regional-to-global routing experiments and model intercomparison studies. The paper that introduced it reports the tool for continental-domain water-resources applications, and a later paper in HESS is specifically about how much the choice of routing scheme changes a hydrological simulation. A benchmark that reports on land-surface models and conceptual buckets but has no verdict on the routing layer that those models are read through is missing the step where the water actually arrives.

This suite. Two things make mizuRoute a different data point from every model already here.

The first is that it is the only model whose native output is per-reach. Every other model in the suite reports at a catchment, a grid cell or an HRU, so a routing probe can only ever ask it whether the whole control volume closed, or whether the outlet hydrograph is consistent. mizuRoute reports inflow, outflow and storage for each reach by name. The reach-by-reach closure identity Σ_t |(Q_in,i,t − Q_out,i,t)Δt − (V_i,t+1 − V_i,t)| ≤ 0.05 Σ_t Q_in,i,t Δt, and the junction identity that goes with it, are the quantity it is built to satisfy — which is what mass/routing-network-closure (#108) asks for, and what the reach-indexed routing contract now under review in #130 exists to carry. Whether mizuRoute satisfies that identity at a junction, where two upstream reaches meet a zero-storage node, is a result the suite cannot currently obtain from any model.

The second is that the model states its conservation claim explicitly, in its own technical note. On the hillslope unit hydrograph: "a probability density function (PDF) is used as a unit-hydrograph, so that cumulative sum of PDF is 1.0. This means that runoff volume at a current time step is just distributed in the future, with the sum of future distributed runoff is equal to the current runoff volume (i.e., volume conserved)." That is a published claim of exact volume conservation, and it is the kind of claim this benchmark exists to test rather than assume.

One condition on the argument above, stated rather than discovered. A routing-only model can only be scored by a probe that supplies the runoff itself and reads routing output back. Of the momentum probes, momentum/routing-conservation (#83, merged) and momentum/channel-routing-mass (#71) both require mrro from the model, which mizuRoute does not produce, so those are N/A (INCOMPLETE) for it however the adapter is written. The scorable surface is the reach-indexed routing probe and anything built on the same contract. If the adapter can be driven by the probe's prescribed headwater inflow, the per-reach and junction closures are scored; if it cannot, the honest headline is N/A across the suite and the proposal is still worth having, because the verdict that a routing model cannot be put to a routing benchmark is itself informative. The first outcome is the one to aim for, and the second is worth having knowingly.

A note on the routing schemes. mizuRoute implements five of them behind one switch — impulse response function, Lagrangian kinematic wave, Euler kinematic wave, Muskingum-Cunge and diffusive wave — all derived from the same Saint-Venant starting point. Because they share a network and an inflow series, a single packaged adapter can report whether the closure holds for each, which is a within-model structural comparison no other entry in the suite can offer.

Submission confirmation

• I have identified a reproducible code revision and have permission to use the linked code and weights for this evaluation. (Apache-2.0 permits use, reproduction and modification; tag v3.1.1 is the pinned, reproducible revision.)
• I understand that HydroTuring may report PASS, FAIL or N/A on each probe, with a reason of VIOLATION, INCOMPLETE, INCOMPATIBLE or ERROR.