wntr.epanet.util module

The wntr.epanet.util module contains unit conversion utilities based on EPANET units.

Contents

FlowUnits(value)

Epanet Units Enum class

MassUnits(value)

Mass units used by EPANET, plus SI conversion factor.

QualParam(value)

EPANET water quality parameters conversion.

HydParam(value)

EPANET hydraulics and energy parameter conversion.

to_si(from_units, data, param[, mass_units, ...])

Convert an EPANET parameter from internal to SI standard units.

from_si(to_units, data, param[, mass_units, ...])

Convert an EPANET parameter from SI standard units back to internal units.

StatisticsType(value)

EPANET time series statistics processing.

QualType(value)

Provide the EPANET water quality simulation mode.

SourceType(value)

What type of EPANET Chemical source is used.

PressureUnits(value)

EPANET output pressure units.

FormulaType(value)

Formula used for determining head loss due to roughness.

ControlType(value)

The type of control.

LinkTankStatus(value)

The link tank status.

MixType(value)

Tank mixing model type.

ResultType(value)

Extended period simulation results type

EN(value)

All the EN_ constants for the EPANET toolkit.

class wntr.epanet.util.FlowUnits(value)[source]

Bases: enum.Enum

Epanet Units Enum class

EPANET has defined unit codes that are used in its INP input files. This enumerated type class provides the appropriate values, rather than setting up a large number of constants. Additionally, each Enum value has a property that identifies it as either traditional or metric flow unit. EPANET does not use fully SI units - these are provided for WNTR compatibility.

Enum Members

CFS

\(ft^3\,/\,s\)

is_traditional

GPM

\(gal\,/\,min\)

is_traditional

MGD

\(10^6\,gal\,/\,day\)

is_traditional

IMGD

\(10^6\,Imp.\,gal\,/\,day\)

is_traditional

AFD

\(acre\cdot\,ft\,/\,day\)

is_traditional

LPS

\(L\,/\,s\)

is_metric

LPM

\(L\,/\,min\)

is_metric

MLD

\(ML\,/\,day\)

is_metric

CMH

\(m^3\,\,hr\)

is_metric

CMD

\(m^3\,/\,day\)

is_metric

SI

\(m^3\,/\,s\)

Enum Member Attributes

factor

The conversion factor to convert units into SI units of \(m^3\,s^{-1}\).

is_traditional

True if flow unit is a US Customary (traditional) unit.

is_metric

True if flow unit is an SI Derived (metric) unit.

Examples

>>> from wntr.epanet import FlowUnits
>>> FlowUnits.GPM
<FlowUnits.GPM: (1, 6.30901964e-05)>

Units can be converted to the EPANET integer values by casting as an int and can be converted to a string by accessing the name property. The factor to convert to SI units is accessed using the factor property.

>>> FlowUnits.LPS.name
'LPS'
>>> int(FlowUnits.LPS)
5

The reverse is also true, where an int from an EPANET run or the string from and input file can be used to get a FlowUnits object.

>>> FlowUnits(4)
<FlowUnits.AFD: (4, 0.014276410185185185)>
>>> FlowUnits['CMD']
<FlowUnits.CMD: (9, 1.1574074074074073e-05)>

Units can be checked for metric or US customary status using the is_traditional or is_metric options.

>>> FlowUnits.GPM.is_traditional
True
>>> FlowUnits.GPM.is_metric
False

Conversion can be done using the factor attribute. For example, to convert 10 AFD to SI units, and to convert 10 MGD to MLD,

>>> 10 * FlowUnits.AFD.factor
0.14276410185185184
>>> 10 * FlowUnits.MGD.factor / FlowUnits.MLD.factor
37.85411784000001

Note

This Enum uses a value of 0 for one of its members, and therefore acts in a non-standard way when evaluating truth values. Use None / is None to check for truth values for variables storing a FlowUnits.

property factor

The conversion factor to convert units into SI units of \(m^3\,s^{-1}\).

Letting values in the original units be \(v\), and the resulting values in SI units be \(s\), the conversion factor, \(f\), such that

\[v f = s\]
Type

float

property is_traditional

True if flow unit is a US Customary (traditional) unit.

Traditional units include CFS, GPM, MGD, IMGD and AFD.

Examples

>>> FlowUnits.MGD.is_traditional
True
>>> FlowUnits.MLD.is_traditional
False
>>> FlowUnits.SI.is_traditional
False
Type

bool

property is_metric

True if flow unit is an SI Derived (metric) unit.

Metric units include LPS, LPM, MLD, CMH, and CMD. This ‘does not’ include FlowUnits.SI itself, only ‘derived’ units.

Examples

>>> FlowUnits.MGD.is_metric
False
>>> FlowUnits.MLD.is_metric
True
>>> FlowUnits.SI.is_metric
False
Type

bool

class wntr.epanet.util.MassUnits(value)[source]

Bases: enum.Enum

Mass units used by EPANET, plus SI conversion factor.

Mass units are defined in the EPANET INP file when the QUALITY option is set to a chemical. This is parsed to obtain the mass part of the concentration units, and is used to set this enumerated type.

Enum Members

mg

miligrams; EPANET as “mg/L” or “mg/min”

ug

micrograms; EPANET as “ug/L” or “ug/min”

g

grams

kg

kilograms; WNTR standard

Enum Member Attributes

factor

The scaling factor to convert to kg.

property factor

The scaling factor to convert to kg.

Type

float

class wntr.epanet.util.QualParam(value)[source]

Bases: enum.Enum

EPANET water quality parameters conversion.

These parameters are separated from the HydParam parameters because they are related to a logically separate model in EPANET, but also because conversion to SI units requires additional information, namely, the MassUnits that were specified in the EPANET input file. Additionally, the reaction coefficient conversions require information about the reaction order that was specified. See the to_si and from_si functions for details.

Enum Members

Concentration

General concentration parameter

Quality

Nodal water quality

LinkQuality

Link water quality

BulkReactionCoeff

Bulk reaction coefficient (req. reaction_order to convert)

WallReactionCoeff

Wall reaction coefficient (req. reaction_order to convert)

ReactionRate

Average reaction rate within a link

SourceMassInject

Injection rate for water quality sources

WaterAge

Water age at a node

class wntr.epanet.util.HydParam(value)[source]

Bases: enum.Enum

EPANET hydraulics and energy parameter conversion.

The hydraulic parameter enumerated type is used to perform unit conversion between EPANET internal units and SI units used by WNTR. The units for each parameter are determined based on the FlowUnits used.

Parameters that are unitless or otherwise require no conversion are not members of this Enum type.

Enum Members

Elevation

Nodal elevation

Demand

Nodal demand

HydraulicHead

Nodal head

Pressure

Nodal pressure

EmitterCoeff

Emitter coefficient

TankDiameter

Tank diameter

Volume

Tank volume

Length

Link length

PipeDiameter

Pipe diameter

Flow

Link flow

Velocity

Link velocity

HeadLoss

Link headloss (from start node to end node)

RoughnessCoeff

Link roughness (requires darcy_weisbach setting for conversion)

Energy

Pump energy

Power

Pump power

wntr.epanet.util.to_si(from_units: wntr.epanet.util.FlowUnits, data, param, mass_units: wntr.epanet.util.MassUnits = MassUnits.mg, pressure_units: Optional[wntr.epanet.util.PressureUnits] = None, darcy_weisbach: bool = False, reaction_order: int = 0)[source]

Convert an EPANET parameter from internal to SI standard units.

Note

See the Units page for details on the units for each HydParam or QualParam. Other than for flows, most parameters only have one US and one metric unit that is used by EPANET. For example, even though flow might be specified in gallons, volumes would be specified in cubic feet for any US/English flow rates, and in cubic meters for all metric flow units; e.g., never liters for volumes even when flow is declared as LPS.

Rememeber that internally, WNTR is always expecting the values for a parameter to be in true SI units – meters, kilograms, and seconds – unless explicitly stated otherwise (e.g., hours for control times).

Parameters
  • from_units (FlowUnits) – The EPANET flow units (and therefore units system) to use for conversion

  • data (float, array-like, dict) – The data to be converted

  • param (HydParam or QualParam) – The parameter type for the data

  • mass_units (MassUnits, optional) – The EPANET mass units (mg or ug internal to EPANET)

  • pressure_units (PressureUnits, optional) – The EPANET pressure units being used (based on flow_units, normally)

  • darcy_weisbach (bool, optional) – For roughness coefficients, is this used in a Darcy-Weisbach formula?

  • reaction_order (int, optional) – For reaction coefficients, what is the reaction order?

Returns

float, array-like, or dict – The data values convert into SI standard units

Examples

First, we convert an array of flows from GPM to cubic meters per second (the SI units).

>>> from wntr.epanet.util import *
>>> flow_si = to_si(FlowUnits.GPM, [0.1, 1.0, 4.3], HydParam.Flow)
>>> print(flow_si)
[6.309019640000001e-06, 6.30901964e-05, 0.00027128784452]

Next, we show how to convert the quality parameter from the EPANET units of mg/L to kg/m3. If that is not the mass units you prefer, it is possible to change them to ug/L, g/L, or kg/L, as shown in the second example.

>>> to_si(FlowUnits.GPM, 4.6, QualParam.Quality)
0.0046
>>> to_si(FlowUnits.GPM, 4.6, QualParam.Quality, mass_units=MassUnits.ug)
4.599999999999999e-06

It is also possible to convert a dictionary of values.

>>> to_si(FlowUnits.GPM, {'node1': 5.6, 'node2': 1.2}, HydParam.Pressure)
{'node1': 3.9392568659127623, 'node2': 0.8441264712670206}

For certain coefficients, there are flags that will change how the conversion occurs. For example, reaction coefficients depend on the reaction order.

>>> to_si(FlowUnits.GPM, 0.45, QualParam.BulkReactionCoeff, reaction_order=0)
0.45
>>> to_si(FlowUnits.GPM, 0.45, QualParam.BulkReactionCoeff, reaction_order=1)
5.208333333333333e-06
wntr.epanet.util.from_si(to_units: wntr.epanet.util.FlowUnits, data, param, mass_units: wntr.epanet.util.MassUnits = MassUnits.mg, pressure_units: Optional[wntr.epanet.util.PressureUnits] = None, darcy_weisbach: bool = False, reaction_order: int = 0)[source]

Convert an EPANET parameter from SI standard units back to internal units.

Note

See the Units page for details on the units for each HydParam or QualParam. Other than for flows, most parameters only have one US and one metric unit that is used by EPANET. For example, even though flow might be specified in gallons, volumes would be specified in cubic feet for any US/English flow rates, and in cubic meters for all metric flow units; e.g., never liters for volumes even when flow is declared as LPS.

Rememeber that internally, WNTR is always expecting the values for a parameter to be in true SI units – meters, kilograms, and seconds – unless explicitly stated otherwise (e.g., hours for control times).

Parameters
  • to_units (FlowUnits) – The EPANET flow units (and therefore units system) to use for conversion

  • data (float, array-like, dict) – The data to be converted

  • param (HydParam or QualParam) – The parameter type for the data

  • mass_units (MassUnits, optional) – The EPANET mass units (mg or ug internal to EPANET)

  • pressure_units (PressureUnits, optional) – The EPANET pressure units being used (based on flow_units, normally)

  • darcy_weisbach (bool, optional) – For roughness coefficients, is this used in a Darcy-Weisbach formula?

  • reaction_order (int, optional) – For reaction coefficients, what is the reaction order?

Returns

float, array-like, or dict – The data values converted into EPANET internal units

Examples

First, we convert an array of flows from SI (cubic meters per second) to GPM.

>>> from wntr.epanet.util import *
>>> flow_us = from_si(FlowUnits.GPM, [6.309019640000001e-06, 6.30901964e-05, 0.00027128784452], HydParam.Flow)
>>> print(flow_us)
[0.1, 1.0, 4.3]

Next, we show how to convert the quality parameter from kg/m3 to mg/L and then to ug/L.

>>> from_si(FlowUnits.GPM, 0.0046, QualParam.Quality)
4.6
>>> from_si(FlowUnits.GPM, 0.0046, QualParam.Quality, mass_units=MassUnits.ug)
4600.0

It is also possible to convert a dictionary of values.

>>> from_si(FlowUnits.GPM, {'node1': 3.9392568659127623, 'node2': 0.8441264712670206}, HydParam.Pressure)
{'node1': 5.6, 'node2': 1.2}

Finally, an example showing the conversion of 1000 cubic meters per second into the different flow units.

>>> from_si(FlowUnits.GPM, 1000.0, HydParam.Flow)  # to gallons per minute
15850323.141488904
>>> from_si(FlowUnits.LPS, 1000.0, HydParam.Flow)  # to liters per second
1000000.0
>>> from_si(FlowUnits.MGD, 1000.0, HydParam.Flow)  # to million gallons per day
22824.465323744018
class wntr.epanet.util.StatisticsType(value)[source]

Bases: enum.Enum

EPANET time series statistics processing.

Enum Members

none

Do no processing, provide instantaneous values on output at time t.

Average

Average the value across the report period ending at time t.

Minimum

Provide the minimum value across all complete reporting periods.

Maximum

Provide the maximum value across all complete reporting periods.

Range

Provide the range (max - min) across all complete reporting periods.

class wntr.epanet.util.QualType(value)[source]

Bases: enum.Enum

Provide the EPANET water quality simulation mode.

Enum Members

none

Do not perform water quality simulation.

Chem

Do chemical transport simulation.

Age

Do water age simulation.

Trace

Do a tracer test (results in percentage of water is from trace node).

class wntr.epanet.util.SourceType(value)[source]

Bases: enum.Enum

What type of EPANET Chemical source is used.

Enum Members

Concen

Concentration – cannot be used at nodes with non-zero demand.

Mass

Mass – mass per minute injection. Can be used at any node.

Setpoint

Setpoint – force node quality to be a certain concentration.

FlowPaced

Flow paced – set variable mass injection based on flow.

class wntr.epanet.util.PressureUnits(value)[source]

Bases: enum.Enum

EPANET output pressure units.

Enum Members

psi

Pounds per square inch (flow units are traditional)

kPa

kilopascals (flow units are metric)

meters

meters of H2O

class wntr.epanet.util.FormulaType(value)[source]

Bases: enum.Enum

Formula used for determining head loss due to roughness.

Enum Members

HW

Hazen-Williams headloss formula

DW

Darcy-Weisbach formala; requires units conversion

CM

Chezy-Manning formula

class wntr.epanet.util.ControlType(value)[source]

Bases: enum.Enum

The type of control.

Enum Members

LowLevel

Act when grade below set level

HiLevel

Act when grade above set level

Timer

Act when set time reached (from start of simulation)

TimeOfDay

Act when time of day occurs (each day)

class wntr.epanet.util.LinkTankStatus(value)[source]

Bases: enum.Enum

The link tank status.

Enum Members

XHead

Pump cannot deliver head (closed)

TempClosed

Temporarily closed

Closed

Closed

Open

Open

Active

Valve active (partially open)

XFlow

Pump exceeds maximum flow

XFCV

FCV cannot supply flow

XPressure

Valve cannot supply pressure

Filling

Tank filling

Emptying

Tank emptying

class wntr.epanet.util.MixType(value)[source]

Bases: enum.Enum

Tank mixing model type.

Enum Members

Mix1

Single compartment mixing model

Mix2

Two-compartment mixing model

FIFO

First-in/first-out model

LIFO

Last-in/first-out model

class wntr.epanet.util.ResultType(value)[source]

Bases: enum.Enum

Extended period simulation results type

property is_node

Is a nodal property result

Is a link property result

property is_qual

Is related to quality

property is_hyd

Is related to hydraulics

class wntr.epanet.util.EN(value)[source]

Bases: enum.IntEnum

All the EN_ constants for the EPANET toolkit.

For example, EN_LENGTH is accessed as EN.LENGTH, instead. Please see the EPANET toolkit documentation for the description of these enums. Several enums are duplicated in separate classes above for clarity during programming.

The enums can be broken in the following groups.

  • Node parameters: ELEVATION, BASEDEMAND, PATTERN, EMITTER, INITQUAL, SOURCEQUAL, SOURCEPAT, SOURCETYPE, TANKLEVEL, DEMAND, HEAD, PRESSURE, QUALITY, SOURCEMASS, INITVOLUME, MIXMODEL, MIXZONEVOL, TANKDIAM, MINVOLUME, VOLCURVE, MINLEVEL,, MAXLEVEL, MIXFRACTION, TANK_KBULK, TANKVOLUME, MAXVOLUME

  • Link parameters: DIAMETER, LENGTH, ROUGHNESS, MINORLOSS, INITSTATUS, INITSETTING, KBULK, KWALL, FLOW, VELOCITY, HEADLOSS, STATUS, SETTING, ENERGY, LINKQUAL, LINKPATTERN

  • Time parameters: DURATION, HYDSTEP, QUALSTEP, PATTERNSTEP, PATTERNSTART, REPORTSTEP, REPORTSTART, RULESTEP, STATISTIC, PERIODS, STARTTIME, HTIME, HALTFLAG, NEXTEVENT

  • Solver parameters: ITERATIONS, RELATIVEERROR

  • Component counts: NODECOUNT, TANKCOUNT, LINKCOUNT, PATCOUNT, CURVECOUNT, CONTROLCOUNT

  • Node types: JUNCTION, RESERVOIR, TANK

  • Link types: CVPIPE, PIPE, PUMP, PRV, PSV, PBV, FCV, TCV, GPV

  • Quality analysis types: NONE, CHEM, AGE, TRACE

  • Source quality types: CONCEN, MASS, SETPOINT, FLOWPACED

  • Flow unit types: CFS, GPM, MGD, IMGD, AFD, LPS, LPM, MLD, CMH, CMD

  • Miscelaneous options: TRIALS, ACCURACY, TOLERANCE, EMITEXPON, DEMANDMULT

  • Control types: LOWLEVEL, HILEVEL, TIMER, TIMEOFDAY

  • Time statistic types: NONE, AVERAGE, MINIMUM, MAXIMUM, RANGE

  • Tank mixing model types: MIX1, MIX2, FIFO, LIFO

  • Save results flag: NOSAVE, SAVE, INITFLOW

  • Pump behavior types: CONST_HP, POWER_FUNC, CUSTOM