plans.hydrology.design#

{Short module description (1-3 sentences)} todo docstring

Functions

`discharge_manning`(A, P, S, n)	Calculates water discharge using the Manning equation.
`hydrograph_scs`(df, CN)	Compute effective rainfall (runoff) from a hyetograph using the SCS Curve Number method (SI units).
`hyetograph_scs`(P, storm_type[, start, factor])	Generate a discrete rainfall time series (Hyetograph) using SCS dimensionless distributions.
`intensity_idf`(recurrence, duration, parameters)	Calculates the average rain intensity given and IDF curve
`propagate_scs`(df, tc[, runoff_field, ...])	Route a runoff time series using the SCS unit hydrograph, returning an extended hydrograph including the recession limb.
`runoff_scs`(P, CN)	Calculates accumulated runoff depth using the SCS Curve Number method (SI units).
`tc_kirpich`(L, S)	Calculates the time of concentration using the Kirpich formula.
`tc_scs`(L, S, CN)	Calculates the time of concentration using the SCS Lag method.
`uh_scs`(dt, tc[, duration])	Generate an SCS synthetic unit hydrograph at a given time resolution.
`velocity_manning`(R, S, n)	Calculates flow velocity using the Manning equation.

plans.hydrology.design.uh_scs(dt: float, tc: float, duration: float | None = None) → numpy.ndarray[source]#

Generate an SCS synthetic unit hydrograph at a given time resolution.

The hydrograph is derived from the dimensionless SCS curve:

\[\frac{Q(t)}{Q_p} = f\left(\frac{t}{t_p}\right)\]

with time to peak:

\[t_p = 0.6 t_c + \frac{D}{2}\]

The resulting hydrograph is normalized such that:

\[\sum UH = 1\]

Parameters:

dt (float) – Time step in seconds.
tc (float) – Time of concentration in seconds.
duration (float, optional) – Effective rainfall duration. Defaults to dt.

Returns:

Unit hydrograph ordinates (sum = 1).

Return type:

numpy.ndarray

Note

Linear interpolation is used to resample the dimensionless curve.
No peak scaling is required due to normalization.

plans.hydrology.design.propagate_scs(df: pandas.DataFrame, tc: float, runoff_field: str = 'r', datetime_field: str = 'datetime', output_field: str = 'q') → pandas.DataFrame[source]#

Route a runoff time series using the SCS unit hydrograph, returning an extended hydrograph including the recession limb.

The routed discharge is computed via full convolution:

\[Q(t) = P_e(t) * UH(t)\]

The unit hydrograph is constructed using the dataframe time step.

Parameters:

df (pandas.DataFrame) – Input dataframe with time series.
tc (float) – Time of concentration in seconds.
runoff_field (str) – Column name for runoff input.
datetime_field (str) – Column name for timestamps.

Returns:

Extended dataframe including routed hydrograph.

Return type:

pandas.DataFrame

Raises:

ValueError – If columns are missing or timestep is inconsistent.

Note

Time step is inferred from the dataframe and used consistently.
Output includes full recession limb (mass-conserving).

plans.hydrology.design.hyetograph_scs(P, storm_type, start='2020-01-01 00:00:00', factor=1)[source]#

Generate a discrete rainfall time series (Hyetograph) using SCS dimensionless distributions.

Parameters:

P (float) – Total storm precipitation [mm]
storm_type (str) – Storm distribution type. One of: “I”, “IA”, “II”, “III”
start (str or pandas.Timestamp) – Start datetime of the storm (string or pandas.Timestamp). Defaults to “2000-01-01 00:00:00”
factor (int) – Length multiplier of the time window (1=24h, 2=48h, 3=72h, …)

Returns:

DataFrame with columns: - datetime: datetime series starting at start - time: time since start [hr] - p: incremental precipitation [mm] - p_acc: cumulative precipitation [mm]

Return type:

pandas.DataFrame

plans.hydrology.design.hydrograph_scs(df, CN)[source]#

Compute effective rainfall (runoff) from a hyetograph using the SCS Curve Number method (SI units).

The method is applied to cumulative precipitation to ensure consistency with the analytical formulation, and incremental runoff is obtained by differencing the accumulated runoff.

Incremental runoff is computed as:

\[r_i = R(P_i) - R(P_{i-1})\]

Parameters:

df (pandas.DataFrame) – Input hyetograph with columns: - datetime - time - p (incremental rainfall) [mm] - p_acc (cumulative rainfall) [mm]
CN (int or float) – SCS Curve Number [-]

Returns:

DataFrame with additional columns: - r: incremental runoff [mm] - r_acc: cumulative runoff [mm] - r_c: runoff coefficient (r / p), NaN where p = 0

Return type:

pandas.DataFrame

plans.hydrology.design.runoff_scs(P, CN)[source]#

Calculates accumulated runoff depth using the SCS Curve Number method (SI units).

\[\begin{split}R = \begin{cases} 0, & P \leq I_a \\ \frac{(P - I_a)^2}{P + 0.8S}, & P > I_a \end{cases}\end{split}\]

Where:

\[S = \frac{25400}{CN} - 254\]

\[I_a = 0.2S\]

Parameters:

P (float or numpy.ndarray) – Accumulated rainfall depth [mm]
CN (int or float or numpy.ndarray) – SCS Curve Number [-]

Returns:

Accumulated runoff depth [mm]

Return type:

float or numpy.ndarray

plans.hydrology.design.intensity_idf(recurrence, duration, parameters)[source]#

Calculates the average rain intensity given and IDF curve

\[i = \frac{k \cdot T^{a}}{(d + b)^{c}}\]

Parameters:

recurrence (float) – recurrence time in years
duration (float) – event duration in minutes
parameters (dict) – IDF dict of parameters in consistent units

Returns:

IDF rain intensity in mm/h

Return type:

float

plans.hydrology.design.velocity_manning(R, S, n)[source]#

Calculates flow velocity using the Manning equation.

\[V = \frac{1}{n} \cdot R^{2/3} \cdot S^{1/2}\]

Parameters:

R (float) – Hydraulic radius [m]
S (float) – Energy slope [m/m]
n (float) – Manning roughness coefficient [-]

Returns:

Velocity [m/s]

Return type:

float

plans.hydrology.design.discharge_manning(A, P, S, n)[source]#

Calculates water discharge using the Manning equation.

\[Q = \frac{1}{n} \cdot A \cdot \left(\frac{A}{P}\right)^{2/3} \cdot S^{1/2}\]

Parameters:

A (float) – Cross-sectional area [m^2]
P (float) – Wetted perimeter [m]
S (float) – Energy slope [m/m]
n (float) – Manning roughness coefficient [-]

Returns:

Discharge [m^3/s]

Return type:

float

plans.hydrology.design.tc_scs(L, S, CN)[source]#

Calculates the time of concentration using the SCS Lag method.

\[t_{c} = \frac{100 \cdot L^{0.8} \cdot \left(\frac{1000}{CN} - 9\right)^{0.7}}{1900 \cdot S^{0.5}}\]

Warning

Input units must be in the S.I. Conversion is performed internally.

Parameters:

L (float or numpy.ndarray) – Flow length in meters
S (float or numpy.ndarray) – Slope in degrees
CN (int) – SCS Curve Number

Returns:

Time of concentration in minutes

Return type:

float or numpy.ndarray

plans.hydrology.design.tc_kirpich(L, S)[source]#

Calculates the time of concentration using the Kirpich formula.

\[t_{c} = 0.0078 \cdot L^{0.77} \cdot S^{-0.385}\]

Warning

Input units must be in the S.I. Conversion is performed internally.

Parameters:

L (float or numpy.ndarray) – Maximum flow path length [m]
S (float or numpy.ndarray) – Watershed slope in degrees

Returns:

Time of concentration in minutes

Return type:

float or numpy.ndarray