Rainfall

Piecewise-constant rainfall forcing and optional antecedent histories.

Rainfall and infiltration forcing.

RainfallSeries dataclass

Piecewise-constant rainfall-intensity series.

The object stores time breakpoints in hours and one rainfall rate per interval in m/s. The column solver caps this rate at the local Ks to obtain effective infiltration; the excess is discarded locally.

duration property

duration: float

Total duration in hours.

max_flux property

max_flux: float

Maximum rainfall rate in m/s.

max_flux_mm_h property

max_flux_mm_h: float

Maximum rainfall rate in mm/h.

constant classmethod

constant(intensity: float, duration: float, *, intensity_units: str = 'mm/h', duration_units: str = 'h') -> 'RainfallSeries'

Create a constant event; duration defaults to hours.

Alternative duration_units (min or s) are explicitly converted to hours.

from_intervals classmethod

from_intervals(intensities: ndarray, durations: ndarray, *, intensity_units: str = 'mm/h', duration_units: str = 'h') -> 'RainfallSeries'

Create rainfall from successive intensity/duration pairs.

Both arrays must be one-dimensional, non-empty, and equally sized. Intensities must be finite and non-negative; durations must be finite and positive. The history starts at zero and its breakpoints are the cumulative durations. Include zero-intensity intervals for dry gaps.

Accepted intensity units are mm/h and m/s; duration units are h, min and s. Stored values always use hours and m/s.

from_intensities classmethod

from_intensities(intensities: ndarray, time_step: float, *, intensity_units: str = 'mm/h', time_units: str = 'h', start_time: float = 0.0) -> 'RainfallSeries'

Create regular intervals; time_step and start_time default to hours.

time_units converts the interval spacing only; start_time is always hours.

capped

capped(maximum_flux: float) -> 'RainfallSeries'

Return a copy whose rainfall rate cannot exceed maximum_flux.

The solver uses this operation with local Ks to create effective infiltration; removed rainfall is reported as rainfall_excess_flux.

with_antecedent_rainfall

with_antecedent_rainfall(total_rainfall_mm: float, duration: float, *, duration_units: str = 'h') -> 'RainfallSeries'

Return combined forcing for uniform antecedent rain and this event.

For event-relative simulation with stage-specific drainage, pass an AntecedentRainfall object to run_single_column instead.

flux_changes

flux_changes(background_flux: float) -> np.ndarray

Flux increments relative to the equilibrium before the first interval.

After the final breakpoint the forcing is zero. Each increment is applied once by the analytical step response, preserving continuity of the internal state at forcing transitions.

flux_at

flux_at(time: float) -> float

Return instantaneous rainfall rate at time in hours using intervals [start, end).

At an interior breakpoint the next interval is active. At the final breakpoint the event has ended and flux is zero. This is not an interval average; plot samples with steps rather than linear segments.

AntecedentRainfall dataclass

Rainfall history preceding a trigger, with optional basal drainage.

Parameters:

Name	Type	Description	Default
rainfall	RainfallSeries	Gross antecedent rainfall beginning at zero. Its final breakpoint is the trigger's time origin, even if the triggering series starts later. Include explicit zero-rain intervals for dry periods within this window.	required
drainage_efficiency	float	Capacity multiplier in [0, 1] during the antecedent. None uses the event boundary's efficiency. This is not a fraction of rainfall drained; even 1 cannot guarantee a fixed water table under intense input.	None

Notes

Use uniform when only total rainfall and duration are known. The solver caps all rates at local Ks, without evapotranspiration or interception. This object does not change the pre-history long_term_infiltration.

duration property

duration: float

Antecedent period in hours.

duration_days property

duration_days: float

Explicit calendar conversion of the canonical duration to days.

total_rainfall_mm property

total_rainfall_mm: float

Integrated gross precipitation in mm, including all intervals.

uniform classmethod

uniform(total_rainfall_mm: float, duration: float, *, drainage_efficiency: float | None = None, duration_units: str = 'h') -> 'AntecedentRainfall'

Uniform gross rainfall from depth in mm and duration in hours.

Other duration units require an explicit duration_units: days, min or s. The canonical stored history and duration always use hours.

prepend_to

prepend_to(event: RainfallSeries) -> RainfallSeries

Combine histories while preserving any dry gap before the event.