Unit Hydrographs
river_route.uhkernels.UnitHydrograph
UnitHydrograph
Stateful runoff transformer driven by a precomputed kernel loaded from file.
Two convolution modes are provided:
convolve— full timeseries FFT convolution for a 2D array of runoff timeseriesconvolve_incrementally— incremental convolution for one timestep of runoff from a 1D vector
Both modes maintain internal state so that carryover between successive calls is handled automatically.
Parameters
kernel_file : path to a scipy sparse npz file
Notes
All times should be given in seconds; areas in m². See the Math Derivations page in the documentation for kernel structure and convolution details.
set_state(path)
Read convolution carryover state from a parquet file.
The file should have shape (n_basins, n_kernel_steps) — basins as rows.
write_state(path)
Write convolution carryover state to a parquet file with shape (n_basins, n_kernel_steps).
convolve_incrementally(runoff_vector)
Incremental single-step convolution.
Convolves one timestep of runoff with the kernel, advances the internal state, and returns the convolved output for this step.
convolve(lateral)
Full timeseries convolution in one pass.
Convolves a (t, n_basins) lateral inflow array with the kernel, incorporates carryover state from previous calls, and updates the internal state with the new tail carryover.
Parameters
lateral : array of shape (t, n_basins), runoff depth per timestep per basin
Returns
convolved : array of shape (t, n_basins), convolved lateral inflow (m³/s)
river_route.uhkernels.SCSTriangular
SCSTriangular
Bases: _SCSBase
SCS triangular dimensionless unit hydrograph transformer.
Source: NRCS National Engineering Handbook (NEH) Part 630, Chapter 16, Table 16-1.
Parameters
tc : 1D array of time-of-concentration values in seconds, one per basin area : 1D array of basin areas in m², one per basin tr : duration of runoff generation in seconds (tr > 0)
Notes
See the Math Derivations page in the documentation for the parameterization equations.
river_route.uhkernels.SCSCurvilinear
SCSCurvilinear
Bases: _SCSBase
SCS curvilinear dimensionless unit hydrograph transformer.
Source: NRCS National Engineering Handbook (NEH) Part 630, Chapter 16, Table 16-1.
Parameters
tc : 1D array of time-of-concentration values in seconds, one per basin area : 1D array of basin areas in m², one per basin tr : duration of runoff generation in seconds (tr > 0)
Notes
See the Math Derivations page in the documentation for the parameterization equations.