wntr.metrics.hydraulic module¶
The wntr.metrics.hydraulic module contains hydraulic metrics.
Contents
|
Compute expected demand at each junction and time using base demands and demand patterns along with the demand multiplier |
|
Compute average expected demand per day at each junction using base demands and demand patterns along with the demand multiplier |
|
Compute water service availability (WSA) at junctions, defined as follows: |
|
Compute Todini index, equations from [Todi00]. |
|
Compute the modified resilience index, equations from [JaSr08]. |
|
Compute tank capacity, the ratio of water volume stored in tanks to the maximum volume of water that can be stored. |
|
Compute entropy, equations from [AwGB90]. |
- wntr.metrics.hydraulic.expected_demand(wn, start_time=None, end_time=None, timestep=None, category=None)[source]¶
Compute expected demand at each junction and time using base demands and demand patterns along with the demand multiplier
- Parameters
wn (wntr WaterNetworkModel) – Water network model. The water network model is needed to get demand timeseries at junctions and options related to duration, timestep, and demand multiplier.
start_time (int (optional)) – Start time in seconds, if None then value is set to 0
end_time (int (optional)) – End time in seconds, if None then value is set to wn.options.time.duration
timestep (int (optional)) – Timestep, if None then value is set to wn.options.time.report_timestep
category (str (optional)) – Demand category name. If None, all demand categories are used.
- Returns
A pandas DataFrame that contains expected demand in m3/s (index = times, columns = junction names).
- wntr.metrics.hydraulic.average_expected_demand(wn, category=None)[source]¶
Compute average expected demand per day at each junction using base demands and demand patterns along with the demand multiplier
- Parameters
wn (wntr WaterNetworkModel) – Water network model. The water network model is needed to get demand timeseries at junctions and options related to duration, timestep, and demand multiplier.
category (str (optional)) – Demand category name. If None, all demand categories are used.
- Returns
A pandas Series that contains average expected demand in m3/s (index = junction names).
- wntr.metrics.hydraulic.water_service_availability(expected_demand, demand)[source]¶
Compute water service availability (WSA) at junctions, defined as follows:
\[WSA = \dfrac{demand}{expected\_demand}\]where \(demand\) is the actual demand computed from a hydraulic simulation, and \(expected\_demand\) is the expected demand computed from base demands and demand patterns. Expected demand can be computed using the
expected_demand
method.WSA can be averaged over times and/or nodes (see below). If expected demand is 0 for a particular junction, water service availability will be set to NaN for that junction.
To compute water service availability for each junction and timestep, expected_demand and demand should be pandas DataFrames (index = times, columns = junction names).
To compute an average water service availability for each junction (averaged over time), expected_demand and demand should be a pandas Series, indexed by junction. To convert a DataFrame (index = times, columns = junction names) to a Series indexed by junction, use the following code:
\(expected\_demand.sum(axis=0)\)
\(demand.sum(axis=0)\)
To compute an average water service availability for each timestep (averaged over junctions), expected_demand and demand should be a pandas Series, indexed by time. To convert a DataFrame (index = times, columns = junction names) to a Series indexed by time, use the following code:
\(expected\_demand.sum(axis=1)\)
\(demand.sum(axis=1)\)
- Parameters
expected_demand (pandas DataFrame or pandas Series (see note above)) – Expected demand at junctions
demand (pandas DataFrame or pandas Series (see note above)) – Actual demand (generally from a PDD hydraulic simulation) at junctions
- Returns
A pandas DataFrame or pandas Series that contains water service
availability.
- wntr.metrics.hydraulic.todini_index(head, pressure, demand, flowrate, wn, Pstar)[source]¶
Compute Todini index, equations from [Todi00].
The Todini index is related to the capability of a system to overcome failures while still meeting demands and pressures at the nodes. The Todini index defines resilience at a specific time as a measure of surplus power at each node and measures relative energy redundancy.
- Parameters
head (pandas DataFrame) – A pandas DataFrame containing node head (index = times, columns = node names).
pressure (pandas DataFrame) – A pandas DataFrame containing node pressure (index = times, columns = node names).
demand (pandas DataFrame) – A pandas DataFrame containing node demand (index = times, columns = node names).
flowrate (pandas DataFrame) – A pandas DataFrame containing pump flowrates (index = times, columns = pump names).
wn (wntr WaterNetworkModel) – Water network model. The water network model is needed to find the start and end node to each pump.
Pstar (float) – Pressure threshold.
- Returns
A pandas Series that contains a time-series of Todini indexes
- wntr.metrics.hydraulic.modified_resilience_index(pressure, elevation, Pstar, demand=None, per_junction=True)[source]¶
Compute the modified resilience index, equations from [JaSr08].
The modified resilience index is the total surplus power available at demand junctions as a percentage of the total minimum required power at demand junctions. The metric can be computed as a timeseries for each junction or as a system average timeseries.
- Parameters
pressure (pandas DataFrame) – A pandas DataFrame containing junction pressure (index = times, columns = junction names).
elevation (pandas Series) – Junction elevation (which can be obtained using wn.query_node_attribute(‘elevation’)) (index = junction names)
Pstar (float) – Pressure threshold.
demand (pandas DataFrame) – A pandas DataFrame containing junction demand (only needed if per_junction=False) (index = times, columns = junction names).
per_junction (bool (optional)) – If True, compute the modified resilience index per junction. If False, compute the modified resilience index over all junctions.
- Returns
pandas Series or DataFrame – Modified resilience index time-series. If per_junction=True, columns=junction names.
- wntr.metrics.hydraulic.tank_capacity(pressure, wn)[source]¶
Compute tank capacity, the ratio of water volume stored in tanks to the maximum volume of water that can be stored.
- Parameters
pressure (pandas DataFrame) – A pandas DataFrame containing tank water level (pressure) (index = times, columns = tank names).
wn (wntr WaterNetworkModel) – Water network model. The water network model is needed to get the tank object to compute current and max volume.
- Returns
pandas DataFrame – Tank capacity (index = times, columns = tank names)
- wntr.metrics.hydraulic.entropy(G, sources=None, sinks=None)[source]¶
Compute entropy, equations from [AwGB90].
Entropy is a measure of uncertainty in a random variable. In a water distribution network model, the random variable is flow in the pipes and entropy can be used to measure alternate flow paths when a network component fails. A network that carries maximum entropy flow is considered reliable with multiple alternate paths.
- Parameters
G (NetworkX or WNTR graph) – Entropy is computed using a directed graph based on pipe flow direction. The ‘weight’ of each link is equal to the flow rate.
sources (list of strings, optional (default = all reservoirs)) – List of node names to use as sources.
sinks (list of strings, optional (default = all nodes)) – List of node names to use as sinks.
- Returns
A tuple which includes –
A pandas Series that contains entropy for each node
System entropy (float)