wntr.epanet.util module

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

Contents

FlowUnits(EN_id, flow_factor) Epanet Units Enum class.
MassUnits 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(val) EPANET time series statistics processing.
QualType(val) Provide the EPANET water quality simulation mode.
SourceType(val) What type of EPANET Chemical source is used.
PressureUnits(val) EPANET output pressure units.
FormulaType(eid, inpcode) Formula used for determining head loss due to roughness.
ControlType(val) The type of control.
LinkTankStatus(val) The link tank status.
MixType(val) Tank mixing model type.
ResultType Extended period simulation results type
EN All the EN_ constants for the EPANET toolkit.
class wntr.epanet.util.FlowUnits(EN_id, flow_factor)[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 float: The conversion factor to convert units into SI units of \(m^3\,s^{-1}\).
is_traditional bool: True if flow unit is a US Customary (traditional) unit.
is_metric bool: 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.

class wntr.epanet.util.MassUnits[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 float : The scaling factor to convert to kg.
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, data, param, mass_units=<MassUnits.mg: (1, 1e-06)>, pressure_units=None, darcy_weisbach=False, reaction_order=0)[source]

Convert an EPANET parameter from internal to SI standard units.

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

wntr.epanet.util.from_si(to_units, data, param, mass_units=<MassUnits.mg: (1, 1e-06)>, pressure_units=None, darcy_weisbach=False, reaction_order=0)[source]

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

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

class wntr.epanet.util.StatisticsType(val)[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(val)[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(val)[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(val)[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(eid, inpcode)[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(val)[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(val)[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(val)[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[source]

Bases: enum.Enum

Extended period simulation results type

class wntr.epanet.util.EN[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