model.processes.river_routing

River routing module for ADELM.

Routes the runoff generated by the land column (runoff_mmday + underflow_mmday) laterally across a river network and diagnoses river discharge and floodplain inundation. This is the first ADELM process that couples cells to one another, through a downstream-pointer network.

Two pieces of physics live here:

_flood_stage Given the total water stored in a cell and its sub-grid floodplain hypsometry (flood_depth_table, a depth-versus-width profile), splits the storage into channel and floodplain water and returns river depth, flood depth and the inundated fraction of the cell.

make_river_routing Builds an ADELM process function for a chosen routing scheme. Each scheme calculates a per-cell outflow (channel outflow for the hydraulic schemes), routes it to the downstream cell via scatter_add on downstream_idx, updates storage by continuity, and re-evaluates the flood stage. The step uses differentiable, out-of-place tensor operations, so gradients from a discharge or flood-extent loss flow back to the selected routing parameter and, through shared parameter networks, to upstream runoff-producing cells.

The static routing geometry is captured by closure rather than passed through the process signature, since this is the only process that consumes it.

Module Contents

Functions

make_river_routing

Build an ADELM river-routing process bound to a static geometry.

API

model.processes.river_routing.make_river_routing(geometry, scheme='linear_reservoir', n_substeps=1, seconds_per_day=86400.0)

Build an ADELM river-routing process bound to a static geometry.

The returned callable has the standard ADELM process signature and is meant to be appended to the process chain. The routing geometry is captured here by closure so it never travels through the per-step signature.

Parameters:

  • geometry (dict) – Static per-cell tensors: downstream_idx (long [n], array-position space), sink_mask (bool [n]), cell_area_m2, river_length_m, river_width_m, river_height_m and flood_depth_table ([n, n_levels]).

  • scheme (str) – Channel-routing formulation: "linear_reservoir", "kinematic_wave", "diffusive_wave", or "local_inertial".

  • n_substeps (int) – Number of routing sub-steps per land day. Fixed, so the graph depth is deterministic for reverse-mode differentiation.

  • seconds_per_day (float) – Length of one land timestep in seconds.

Returns:

calculate_river_routing(drivers, states, fluxes, diagnos, params, consts, errors, structure, debugs).

Return type:

callable