wntr.metrics.hydraulic module

The wntr.metrics.hydraulic module contains hydraulic metrics.

Contents

expected_demand(wn[, start_time, end_time, ...])	Compute expected demand at each junction and time using base demands and demand patterns along with the demand multiplier
average_expected_demand(wn[, category])	Compute average expected demand per day at each junction using base demands and demand patterns along with the demand multiplier
water_service_availability(expected_demand, ...)	Compute water service availability (WSA) at junctions, defined as follows:
todini_index(head, pressure, demand, ...)	Compute Todini index, equations from [Todi00].
modified_resilience_index(pressure, ...[, ...])	Compute the modified resilience index, equations from [JaSr08].
tank_capacity(pressure, wn)	Compute tank capacity, the ratio of water volume stored in tanks to the maximum volume of water that can be stored.
entropy(G[, sources, sinks])	Compute entropy, equations from [AwGB90].

wntr.metrics.hydraulic.expected_demand(wn, start_time=None, end_time=None, timestep=None, category=None)

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)

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)

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)

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)

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)

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)

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)