mizuRoute Routing Model Guide#

Overview#

mizuRoute (mizuRoute: Standalone Runoff Routing) is a multi-method river network routing model developed at the University of Washington and NCAR. It routes runoff generated by land surface or hydrological models through river networks, transforming catchment-scale runoff into streamflow at any point in the network.

Key Capabilities:

  • Multiple routing methods (IRF, KWT, KW, MC, DW)

  • Scalable from headwaters to continental basins

  • NetCDF-based input/output

  • Parallel execution support

  • Lake and reservoir representation

  • Flexible river network structures

  • Couples with multiple hydrological models

  • Configurable routing parameters

Typical Applications:

  • Distributed hydrological model routing (SUMMA, FUSE, GR, HYPE)

  • Continental-scale streamflow routing

  • Flood wave propagation

  • Reservoir operations

  • Water resources management

  • Multi-model ensembles

  • Climate change impact assessment

Spatial Scales: Sub-basin (1 km²) to continental (millions of km²)

Temporal Resolution: Sub-hourly to daily

Routing Methods#

mizuRoute supports five routing schemes with varying complexity and computational cost:

1. Impulse Response Function (IRF)#

Method: Unit hydrograph convolution

Characteristics:

  • Fastest method

  • Lumped river reach routing

  • Based on gamma distribution

  • No backwater effects

  • Good for large-scale applications

Parameters:

  • Shape parameter (unitShape)

  • Time scale (unitScale)

Best for: Continental/regional scale, operational forecasting

Equation:

Q(t) = Σ runoff(τ) × IRF(t-τ)

where IRF(t) = Gamma distribution(shape, scale)

2. Kinematic Wave Tracking (KWT)#

Method: Kinematic wave with particle tracking

Characteristics:

  • Moderate computational cost

  • Tracks water parcels through network

  • Accounts for variable wave speed

  • No diffusion

  • Good accuracy for most applications

Parameters:

  • Manning’s n

  • Channel geometry

  • Wave celerity

Best for: Regional applications, research studies

Advantages:

  • Mass conservative

  • Handles complex networks well

  • Reasonable computational cost

3. Kinematic Wave (KW)#

Method: Simplified kinematic wave

Characteristics:

  • Similar to KWT but simplified

  • Faster than KWT

  • Good for steep channels

  • No backwater effects

Parameters:

  • Manning’s n

  • Channel slope

  • Channel geometry

Best for: Mountainous regions, headwater routing

4. Muskingum-Cunge (MC)#

Method: Variable parameter Muskingum-Cunge

Characteristics:

  • Moderate complexity

  • Accounts for some diffusion

  • Better for lowland rivers

  • More physically-based than IRF

Parameters:

  • X: Weighting factor (0-0.5)

  • K: Storage coefficient

Best for: Lowland rivers, moderate slopes

5. Diffusive Wave (DW)#

Method: Diffusive wave approximation

Characteristics:

  • Most complex/accurate

  • Accounts for backwater effects

  • Computationally expensive

  • Good for flat terrain

Parameters:

  • Manning’s n

  • Channel geometry

  • Boundary conditions

Best for: Lowland/delta regions, backwater-dominated systems

Limitations: Slow for large networks

Method Comparison#

Method

Speed

Accuracy

Backwater

Best Use

Complexity

IRF

Fastest

Moderate

No

Continental

Low

KWT

Fast

Good

No

Regional

Moderate

KW

Fast

Good

No

Mountains

Moderate

MC

Moderate

Good

Partial

Lowlands

Moderate

DW

Slow

Best

Yes

Deltas

High

Configuration in SYMFLUENCE#

Enabling mizuRoute#

ROUTING_MODEL: mizuRoute

# Specify for model-specific integration
FUSE_ROUTING_INTEGRATION: mizuRoute
# or
GR_ROUTING_INTEGRATION: mizuRoute

Key Configuration Parameters#

Routing Method Selection#

Parameter

Default

Description

MIZUROUTE_METHOD

KWT

Routing method (IRF, KWT, KW, MC, DW)

MIZUROUTE_DT

3600

Routing timestep (seconds)

Network Configuration#

Parameter

Default

Description

MIZUROUTE_NETWORK_FILE

auto

River network topology file

MIZUROUTE_PARAM_FILE

auto

River reach parameters file

Channel Parameters#

Parameter

Default

Description

MIZUROUTE_MANNING_N

0.03

Manning’s roughness coefficient

MIZUROUTE_CHANNEL_WIDTH

auto

Channel width [m] (from network or default)

MIZUROUTE_CHANNEL_SLOPE

auto

Channel slope [-] (from DEM)

Output Configuration#

Parameter

Default

Description

MIZUROUTE_OUTPUT_VARS

all

Variables to output

MIZUROUTE_OUTPUT_FREQ

daily

Output frequency (hourly, daily, monthly)

Input File Specifications#

River Network Topology#

File: network_topology.nc

NetCDF file defining river network structure:

dimensions:
  seg = 5000        ! Number of river segments
  upSegments = 10   ! Max upstream segments per segment

variables:
  int segId(seg)                  ! Segment ID
  int downSegId(seg)              ! Downstream segment ID (-999 = outlet)
  int upSegIds(seg, upSegments)   ! Upstream segment IDs
  int nUpstream(seg)              ! Number of upstream segments

  ! Segment attributes
  float length(seg)               ! Segment length [m]
  float slope(seg)                ! Channel slope [-]
  float width(seg)                ! Channel width [m]
  float mannings_n(seg)           ! Manning's n [-]

Example values:

segId:      [1, 2, 3, 4, 5, ...]
downSegId:  [2, 3, 4, -999, 3, ...]  ! Seg 4 is outlet
length:     [5000, 8000, 12000, 15000, 6000, ...]  ! meters
slope:      [0.01, 0.008, 0.005, 0.002, 0.012, ...]
width:      [15, 25, 40, 80, 12, ...]  ! meters

Runoff Input#

File: runoff_input.nc

Catchment runoff time series:

dimensions:
  time = UNLIMITED
  seg = 5000

variables:
  double time(time)               ! Time coordinate
  float runoff(time, seg)         ! Runoff [mm/timestep or m³/s]
  float runoffArea(seg)           ! Catchment area [m²]

Units:

  • Runoff: Can be [mm/timestep], [mm/day], or [m³/s]

  • mizuRoute converts based on runoffArea

Example:

time:   [0, 3600, 7200, 10800, ...]  ! seconds since reference
runoff(seg=1): [2.5, 2.3, 3.8, ...]  ! mm/hour
runoff(seg=2): [1.8, 1.6, 2.4, ...]

Parameter File#

File: mizuRoute_param.nc

Method-specific routing parameters:

dimensions:
  seg = 5000

variables:
  ! IRF parameters
  float IRFroutingParams_shape(seg)    ! Gamma shape
  float IRFroutingParams_scale(seg)    ! Gamma scale [hours]

  ! KWT parameters
  float KWTroutingParams_waveSpeed(seg) ! Wave celerity [m/s]

  ! MC parameters
  float MCroutingParams_K(seg)         ! Storage coefficient
  float MCroutingParams_X(seg)         ! Weighting factor

Lake/Reservoir Data#

File (optional): lake_data.nc

dimensions:
  lake = 50
  time = UNLIMITED

variables:
  int lakeId(lake)
  int lakeSegId(lake)             ! Segment containing lake
  float lakeArea(lake)            ! Lake area [m²]
  float lakeDepth(lake)           ! Mean depth [m]
  float lakeOutflow(time, lake)   ! Prescribed outflow [m³/s]

Output File Specifications#

Routed Streamflow#

File: mizuRoute_output.nc

dimensions:
  time = UNLIMITED
  seg = 5000

variables:
  double time(time)

  ! Streamflow by routing method
  float dlayRunoff(time, seg)      ! IRF routed flow [m³/s]
  float KWTroutedRunoff(time, seg) ! KWT routed flow [m³/s]
  float KWroutedRunoff(time, seg)  ! KW routed flow [m³/s]
  float MCroutedRunoff(time, seg)  ! MC routed flow [m³/s]
  float DWroutedRunoff(time, seg)  ! DW routed flow [m³/s]

  ! Instantaneous (unrouted) runoff
  float instRunoff(time, seg)      ! Direct runoff [m³/s]

  ! States
  float reachVolume(time, seg)     ! Water volume in reach [m³]
  float reachDepth(time, seg)      ! Water depth [m]

State Files#

File: restart_state.nc

For continuing simulations:

dimensions:
  seg = 5000
  wave = 1000  ! Number of tracked waves (for KWT)

variables:
  float reachVolume(seg)
  float waveTime(seg, wave)
  float waveVolume(seg, wave)

Model-Specific Workflows#

Basic mizuRoute Workflow#

Route distributed FUSE output:

# config.yaml
DOMAIN_NAME: my_basin
HYDROLOGICAL_MODEL: FUSE

# Distributed FUSE
FUSE_SPATIAL_MODE: distributed
DOMAIN_DEFINITION_METHOD: semidistributed
POUR_POINT_COORDS: [-120.0, 45.0]

# Enable mizuRoute
ROUTING_MODEL: mizuRoute
FUSE_ROUTING_INTEGRATION: mizuRoute

# Routing configuration
MIZUROUTE_METHOD: KWT  # Kinematic wave tracking
MIZUROUTE_DT: 3600     # 1-hour timestep

Run:

symfluence workflow run --config config.yaml

# FUSE generates runoff per HRU
# mizuRoute routes through river network
# Output: Streamflow at basin outlet

Continental-Scale Routing#

For large domains (e.g., CONUS, Europe):

# config.yaml
DOMAIN_DEFINITION_METHOD: merit_basins
MERIT_BASIN_IDS: [...]  # 10,000+ subcatchments

HYDROLOGICAL_MODEL: SUMMA
ROUTING_MODEL: mizuRoute

# Use fast IRF method for computational efficiency
MIZUROUTE_METHOD: IRF

# Parallel execution
NUM_PROCESSES: 256

# Daily output sufficient for large scale
MIZUROUTE_OUTPUT_FREQ: daily

Flood Forecasting Application#

Hourly routing for flood events:

# config.yaml
HYDROLOGICAL_MODEL: GR
GR_SPATIAL_MODE: distributed

ROUTING_MODEL: mizuRoute

# Use accurate method
MIZUROUTE_METHOD: MC  # Muskingum-Cunge

# Sub-hourly timestep for flood peaks
MIZUROUTE_DT: 1800  # 30 minutes

# Hourly output
MIZUROUTE_OUTPUT_FREQ: hourly

Reservoir Operations#

Include reservoir routing:

# config.yaml
ROUTING_MODEL: mizuRoute

# Provide lake/reservoir data
MIZUROUTE_LAKE_FILE: ./reservoirs.nc

# Use method that handles storage well
MIZUROUTE_METHOD: KWT

# Reservoirs controlled by release rules in lake file

Calibration Strategies#

Routing Parameters#

For IRF method:

# Calibrate gamma distribution parameters
MIZUROUTE_PARAMS_TO_CALIBRATE: "IRF_shape,IRF_scale"

IRF_shape:  [1.0, 5.0]       # Gamma shape parameter
IRF_scale:  [1.0, 100.0]     # Time scale [hours]

For KWT/KW methods:

MIZUROUTE_PARAMS_TO_CALIBRATE: "mannings_n,channel_width"

mannings_n:     [0.01, 0.15]   # Roughness coefficient
channel_width:  [5, 200]       # Channel width [m]

For MC method:

MIZUROUTE_PARAMS_TO_CALIBRATE: "MC_K,MC_X"

MC_K:  [0.5, 48.0]      # Storage coefficient [hours]
MC_X:  [0.0, 0.5]       # Weighting factor [-]

Parameter Regionalization#

For large networks, use regional relationships:

# Manning's n by stream order
stream_order_1-2:  n = 0.05-0.10  # Small streams
stream_order_3-4:  n = 0.03-0.05  # Medium rivers
stream_order_5+:   n = 0.02-0.04  # Large rivers

# Channel width by drainage area
width = a × Area^b
# Typical: a = 2-5, b = 0.4-0.5

Calibration Workflow#

  1. Run hydrological model first (SUMMA, FUSE, etc.)

  2. Generate runoff fields

  3. Calibrate routing separately:

    # Fix hydrology parameters
# Calibrate only routing parameters
CALIBRATION_PHASE: routing_only

OPTIMIZATION_ALGORITHM: DDS
OPTIMIZATION_MAX_ITERATIONS: 500

# Use streamflow gauge at outlet
OPTIMIZATION_METRIC: KGE

Known Limitations#

  1. Network Topology Required:

    • Accurate DEM and flow directions needed

    • Errors in network propagate

    • Manual corrections often necessary

  2. Channel Geometry:

    • Width, depth often poorly constrained

    • Default relationships may not apply everywhere

    • Observations rare except for large rivers

  3. Computational Cost:

    • DW method very slow for large networks

    • KWT faster but still expensive for 10,000+ reaches

    • IRF fastest but least accurate

  4. Limitations of Methods:

    • IRF: No backwater, lumped routing

    • KW/KWT: No backwater, steep channels only

    • MC: Approximation, not full St. Venant

    • DW: Expensive, numerical instability possible

  5. Parameter Identifiability:

    • Manning’s n correlated with channel width

    • Limited observations for calibration

    • Often need to fix some parameters

  6. Lakes and Reservoirs:

    • Simplified representation

    • Operations rules often unknown

    • Natural lake rating curves uncertain

Troubleshooting#

Common Issues#

Error: “Network topology file not found”

# Ensure network file exists
MIZUROUTE_NETWORK_FILE: /path/to/network_topology.nc

# Or let SYMFLUENCE generate from domain delineation
# (automatic if using delineate or merit_basins)

Error: “Runoff input dimension mismatch”

Check that runoff file has same segments as network:

ncdump -h runoff_input.nc | grep "seg ="
ncdump -h network_topology.nc | grep "seg ="

# Should match!

Error: “Negative streamflow”

  1. Check routing parameters (Manning’s n too high?)

  2. Verify runoff inputs (no negative values)

  3. Check timestep (too large?)

  4. Inspect network topology (cycles? disconnected segments?)

Very slow execution

# Switch to faster method
MIZUROUTE_METHOD: IRF  # From DW or KWT

# Increase timestep (if appropriate)
MIZUROUTE_DT: 86400  # Daily instead of hourly

# Reduce output frequency
MIZUROUTE_OUTPUT_FREQ: daily  # From hourly

Unrealistic routing delays

# For IRF: Reduce time scale
IRF_scale: 5  # From 50 hours

# For KWT: Increase wave speed
# (or decrease Manning's n)
mannings_n: 0.025  # From 0.10

Flood peaks too attenuated

  1. Use more accurate method (MC or DW instead of IRF)

  2. Reduce timestep (hourly instead of daily)

  3. Calibrate routing parameters (reduce storage/diffusion)

Missing segments in output

# Check for disconnected segments
python
>>> import netCDF4 as nc
>>> ds = nc.Dataset('network_topology.nc')
>>> down = ds.variables['downSegId'][:]
>>> # Segments with downSegId = -999 are outlets
>>> # All others should connect to an outlet

Performance Optimization#

Speed up routing:

  1. Use IRF method for large-scale applications

  2. Aggregate small headwater reaches

  3. Use coarser timestep (daily vs hourly)

  4. Parallel execution (if network allows decomposition)

  5. Reduce output frequency and variables

Improve accuracy:

  1. Use MC or DW for lowland rivers

  2. Use KWT for moderate complexity

  3. Finer timestep (hourly or sub-hourly)

  4. Calibrate reach-specific parameters (if data supports)

  5. Include lakes/reservoirs explicitly

Optimal method selection:

# Decision tree
if network_size > 10000 and slope > 0.001:
    method = 'IRF'  # Fast, adequate for steep
elif slope < 0.0001:
    method = 'DW'   # Backwater important
elif slope > 0.01:
    method = 'KW'   # Kinematic valid
else:
    method = 'KWT'  # Good balance

Additional Resources#

mizuRoute Documentation:

Publications:

River Routing Theory:

  • Lohmann et al. (1996): “A large-scale horizontal routing model”

  • Chow et al. (1988): “Applied Hydrology” (Muskingum-Cunge method)

SYMFLUENCE-specific:

River Network Data:

  • MERIT-Basins: Global river network

  • NHDPlus: US high-resolution network

  • HydroSHEDS: Global drainage network

  • GRDC: Global discharge data for calibration

Example Configurations:

# View mizuRoute examples
symfluence examples list | grep routing

Coupling with Other Models:

  • SUMMA + mizuRoute: Detailed physics + routing

  • FUSE + mizuRoute: Structural uncertainty + routing

  • GR + mizuRoute: Fast benchmarking + routing

  • HYPE: Has internal routing, mizuRoute optional

Best Practices:

  1. Validate network topology before routing

  2. Start with simple method (IRF) for testing

  3. Use observations at multiple gauges for calibration

  4. Check mass balance (inflow = outflow + storage change)

  5. Visualize results along river network to spot issues