plans.hydrology.core#

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

Features#

todo docstring

{feature 1}
{feature 2}
{feature 3}
{etc}

Overview#

todo docstring {Overview description}

Examples#

todo docstring {Examples in rST}

Print a message

# print message
print("Hello world!")
# [Output] >> 'Hello world!'

Functions

`compute_decay`(s, dt, k)
`compute_flow`(flow_pot, flow_cap)
`convert_deg_to_percent`(theta_deg)	Converts a slope angle from degrees to a percentage value.
`convert_deg_to_ratio`(theta_deg)	Converts a slope angle from degrees to a decimal ratio (m/m).
`convert_m2_to_km2`(values)	Convert area from square meters (m²) to square kilometers (km²).
`convert_m_to_ft`(L)	Converts a length measurement from meters to feet.
`convert_mm_to_m3s`(values, area_km2[, dt_seconds])	Convert rainfall/runoff from mm per timestep to m³/s.
`uh_convolution`(flow, uh)	Convolve a flow time series with a unit hydrograph (full output).

Classes

Model([name, alias])

The core Model base object.

plans.hydrology.core.compute_decay(s, dt, k)[source]#

plans.hydrology.core.compute_flow(flow_pot, flow_cap)[source]#

plans.hydrology.core.uh_convolution(flow: numpy.ndarray, uh: numpy.ndarray) → numpy.ndarray[source]#

Convolve a flow time series with a unit hydrograph (full output).

The routed discharge is computed via discrete convolution:

\[Q(t) = \sum_{\tau=0}^{t} P_e(\tau) \cdot UH(t - \tau)\]

The output length is:

\[N_{out} = N_{flow} + N_{UH} - 1\]

which represents the full hydrograph including the recession limb.

Parameters:

flow (numpy.ndarray) – Input flow time series.
uh (numpy.ndarray) – Unit hydrograph ordinates (must sum to 1).

Returns:

Routed hydrograph (full length).

Return type:

numpy.ndarray

Raises:

ValueError – If inputs are not 1D or UH does not sum to unity.

Note

This implementation always preserves mass (no truncation).
Additional timesteps correspond to routing memory.
Time alignment must be handled externally.

plans.hydrology.core.convert_deg_to_ratio(theta_deg)[source]#

Converts a slope angle from degrees to a decimal ratio (m/m).

\[S_{ratio} = \tan(\theta_{deg})\]

Parameters:: theta_deg (float or numpy.ndarray) – Slope angle in degrees
Returns:: Slope expressed as m/m
Return type:: float or numpy.ndarray

plans.hydrology.core.convert_deg_to_percent(theta_deg)[source]#

Converts a slope angle from degrees to a percentage value.

\[S_{\%} = 100 \cdot \tan(\theta_{deg})\]

Parameters:: theta_deg (float or numpy.ndarray) – Slope angle in degrees
Returns:: Slope expressed as a percentage
Return type:: float or numpy.ndarray

plans.hydrology.core.convert_m_to_ft(L)[source]#

Converts a length measurement from meters to feet.

\[L_{ft} = L_{m} \cdot 3.28084\]

Parameters:: L (float) – Length in meters
Returns:: Length in feet
Return type:: float

plans.hydrology.core.convert_m2_to_km2(values) → numpy.ndarray[source]#

Convert area from square meters (m²) to square kilometers (km²).

\[A_{km^2} = \frac{A_{m^2}}{10^6}\]

Parameters:: values (array-like) – Area values in m².
Returns:: Area values in km².
Return type:: numpy.ndarray

plans.hydrology.core.convert_mm_to_m3s(values, area_km2, dt_seconds=3600.0)[source]#

Convert rainfall/runoff from mm per timestep to m³/s.

\[Q = \frac{P \cdot A \cdot 10^{3}}{\Delta t}\]

where:

\(P\) is depth [mm]
\(A\) is area [km²]
\(\Delta t\) is timestep [s]

Parameters:

values (float or array-like) – Input series (mm per timestep, e.g. mm/h if dt=3600 s).
area_km2 (float) – Drainage area.
dt_seconds (float) – Time step in seconds.

Returns:

Discharge in m³/s.

Return type:

float or numpy.ndarray

class plans.hydrology.core.Model(name='MyModel', alias='HM01')[source]#

Bases: DataSet

The core Model base object. Expected to hold one pandas.DataFrame as simulation data and a dictionary as parameters. This is a dummy class to be developed downstream.

__init__(name='MyModel', alias='HM01')[source]#

_set_fields()[source]#: Set fields names. Expected to increment superior methods.

_set_model_vars()[source]#

_set_model_params()[source]#

Internal method for setting up model parameters data

Returns:: None
Return type:: None

_set_view_specs()[source]#

Set view specifications. Expected to increment superior methods.

Returns:: None
Return type:: None

get_vars()[source]#

get_params()[source]#

get_metadata()[source]#

Get a dictionary with object metadata. Expected to increment superior methods.

Note

Metadata does not necessarily inclue all object attributes.

Returns:: dictionary with all metadata
Return type:: dict

setter(dict_setter)[source]#

Set selected attributes based on an incoming dictionary. This is calling the superior method using load_data=False.

Parameters:: dict_setter (dict) – incoming dictionary with attribute values
Returns:: None
Return type:: None

update()[source]#

Refresh all mutable attributes based on data (includins paths). Base method. This is overwrinting the superior method.

Returns:: None
Return type:: None

update_dt()[source]#

Update Time Step value, units and tag to match the model reference time parameter (like k)

Returns:: None
Return type:: None

load_params()[source]#

Load parameter data

Returns:: None
Return type:: None

load_data()[source]#

Load simulation data. Expected to overwrite superior methods.

Returns:: None
Return type:: None

load()[source]#

Load parameters and data

Returns:: None
Return type:: None

setup()[source]#

Set model simulation. Expected to be incremented downstream.

Warning

This method overwrites model data.

Returns:: None
Return type:: None

solve()[source]#

Solve the model for boundary and initial conditions by numerical methods.

Warning

This method overwrites model data.

Returns:: None
Return type:: None

evaluate()[source]#

Evaluate model.

Returns:: None
Return type:: None

run(setup_model=True)[source]#

Simulate model (full procedure).

Parameters:: setup_model (bool) – flag for setting up data (default=True)
Returns:: None
Return type:: None

export(folder, filename)[source]#

Export object resources

Parameters:

folder (str) – path to folder
filename (str) – file name without extension

Returns:

None

Return type:

None

save(folder)[source]#

Save to sourced files is not allowed for Model() family. Use .export() instead. This is overwriting superior methods.

Returns:: None
Return type:: None

view(show=True)[source]#

Get the basic visualization.

Parameters:: show (bool) – option for showing instead of saving.

Note

Uses values in the view_specs() attribute for plotting.

static get_timestep_factor(from_unit: str, to_unit: str) → float[source]#

Calculates the conversion factor between two time units.

For instance, to find out how many days are in a given number of ‘10min’ intervals, this function provides the multiplier.

Parameters:

from_unit (str) – The starting time unit (e.g., ‘10min’, ’15s’).
to_unit (str) – The desired time unit (e.g., ‘days’, ‘min’).

Returns:

The factor to convert from the starting to the desired time unit.

Return type:

float

static get_timestep_series(start_time: str, end_time: str, time_unit: str) → pandas.DatetimeIndex[source]#

Generates a time series of timestamps.

Creates a sequence of timestamps between a start and end time, with a specified frequency.

Parameters:

start_time (str) – The starting timestamp for the series (e.g., ‘2024-01-01’, ‘2024-01-01 00:00:00’).
end_time (str) – The ending timestamp for the series (e.g., ‘2024-01-10’, ‘2024-01-10 23:59:59’).
time_unit (str) – The frequency or interval between timestamps (e.g., ‘D’ for day, ‘H’ for hour, ‘10min’).

Returns:

A pandas DatetimeIndex representing the generated time series.

Return type:

pd.DatetimeIndex

static get_gaussian_signal(value_max, size, sigma=50, position_factor=5, reverse=False)[source]#

Generates a vector of normally (gaussian) distributed values. Useful for testing inputs inflows.

Parameters:

value_max (float) – actual maximum value in the vector
size (int) – size of vector (time series size)
sigma (float) – standard deviation for gaussian (normal) distribution.
position_factor (float) – where to place the peak in the vector
reverse (bool) – boolean to reverse position in order

Returns:

vector of values

Return type:

Numpy array