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)[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)