Skip to content

Router Classes

river_route.Configs dataclass

Accepts and validates configuration options. The class will validates in the following ways:

  1. Keys that are required are set.
  2. Values that must be from a specific list of options are valid.
  3. Paths or directories exist which are necessary
  4. File paths are converted to absolute paths.

deep_validate()

Perform deep validation of file contents and inter-file consistency. Raise ValueError if any issues found.

river_route.Muskingum

Muskingum

Muskingum channel routing using a matrix formulation solved by forward substitution. Inflow to each river segment is the sum of discharge from upstream segments. No lateral inflow — channel routing only.

See the Math Derivations and Forward Substitution pages in the documentation for the full equations and algorithm details.

route()

Execute the simulation described by the provided configs and routing parameters. All configs, file paths, parameters, and options must be set when the object is initialized so that validation is performed before the simulation.

Returns:

Name Type Description
Self Self

the class instance with updated channel_state and output files written to disk

set_write_discharges(func)

Overwrites the default write_discharges method to a custom function and returns the class instance so that you can chain the method with the constructor.

Parameters:

Name Type Description Default
func callable

function that takes dates, discharge_array, discharge_file, runoff_file and returns None

 required

river_route.RapidMuskingum

RapidMuskingum

Bases: TransformMuskingum

Muskingum channel routing with direct lateral inflow. Lateral flow is the runoff volume divided by the runoff timestep — all runoff enters the channel in the interval it is generated, ignoring overland flow delay.

See the Math Derivations page in the documentation for the full equations.

river_route.UnitMuskingum

UnitMuskingum

Bases: TransformMuskingum

Muskingum channel routing with unit hydrograph lateral inflow. Lateral inflow at each segment is determined by convolving runoff depths (m) with a precomputed unit hydrograph kernel. Discharge is the superposition of overland flow by unit hydrograph and channel routing merged at each time step.

Notation used in the code and solvers:

  • q_full = q_channel + q_lateral
  • q_channel is the routed flow from Muskingum routing
  • q_lateral is the unit hydrograph convolved runoff transformation
  • _hw marks headwater segments (UH convolution only, excluded from matrix solve)
  • _inner marks non-headwater segments needing both convolution and routing

See the Math Derivations page in the documentation for the full equations.