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

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

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

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

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: FlowUnits, data, param, mass_units: MassUnits = MassUnits.mg, pressure_units: Optional[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: FlowUnits, data, param, mass_units: MassUnits = MassUnits.mg, pressure_units: Optional[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

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

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

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

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

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

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

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

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

Extended period simulation results type

property is_node¶: Is a nodal property result

property is_link¶: 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: 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

class wntr.epanet.util.SizeLimits(value)[source]¶

Bases: Enum

Limits on the size of character arrays used to store ID names and text messages.

class wntr.epanet.util.InitHydOption(value)[source]¶

Bases: Enum

Hydraulic initialization options. These options are used to initialize a new hydraulic analysis when EN_initH is called.