MSXepanet#

module wntr.epanet.msx.toolkit

class MSXepanet[source]#

Bases: ENepanet

ENaddcontrol(iType, iLinkIndex, dSetting, iNodeIndex, dLevel)#

Add a new simple control

Parameters:

  • iType (int) – the type of control

  • iLinkIndex (int) – the index of the link

  • dSetting (float) – the new link setting value

  • iNodeIndex (int) – Set to 0 for time of day or timer

  • dLevel (float) – the level to compare against

Returns:

the new control number

Return type:

int

ENclose()[source]#

Frees all memory and files used by EPANET

ENcloseH()#

Frees data allocated by hydraulics solver

ENcloseQ()#

Frees data allocated by water quality solver

ENdeletecontrol(iControlIndex)#

Delete a control.

Parameters:

iControlIndex (int) – the simple control to delete

ENgetcontrol(iIndex)#

Get values defined by a control.

Parameters:

iIndex (int) – the control number

ENgetcount(iCode)#

Retrieves the number of components of a given type in the network

Parameters:

iCode (int) – Component code (see toolkit.optComponentCounts)

Returns:

Number of components in network

Return type:

int

ENgetflowunits()#

Retrieves flow units code

Return type:

Code of flow units in use (see toolkit.optFlowUnits)

ENgetlinkindex(sId)#

Retrieves index of a link with specific ID

Parameters:

sId (int) – Link ID

Return type:

Index of link in list of links

ENgetlinktype(iIndex)#

Retrieves a link’s type given its index.

Parameters:

iIndex (int) – The index of the link

Returns:

the link type as an integer

Return type:

int

ENgetlinkvalue(iIndex, iCode)#

Retrieves parameter value for a link

Parameters:

  • iIndex (int) – Link index

  • iCode (int) – Link parameter code (see toolkit.optLinkParams)

Return type:

Value of link’s parameter

ENgetnodeid(iIndex)#

Gets the ID name of a node given its index.

Parameters:

iIndex (int) – a node’s index (starting from 1).

Returns:

the node name

Return type:

str

ENgetnodeindex(sId)#

Retrieves index of a node with specific ID

Parameters:

sId (int) – Node ID

Return type:

Index of node in list of nodes

ENgetnodetype(iIndex)#

Retrieves a node’s type given its index.

Parameters:

iIndex (int) – The index of the node

Returns:

the node type as an integer

Return type:

int

ENgetnodevalue(iIndex, iCode)#

Retrieves parameter value for a node

Parameters:

  • iIndex (int) – Node index

  • iCode (int) – Node parameter code (see toolkit.optNodeParams)

Return type:

Value of node’s parameter

ENgettimeparam(eParam)#

Get a time parameter value

Parameters:

eParam (int) – the time parameter to get

Returns:

the value of the time parameter, in seconds

Return type:

long

ENinitH(iFlag)#

Initializes hydraulic analysis

Parameters:

iFlag (2-digit flag) – 2-digit flag where 1st (left) digit indicates if link flows should be re-initialized (1) or not (0) and 2nd digit indicates if hydraulic results should be saved to file (1) or not (0)

ENinitQ(iSaveflag)#

Initializes water quality analysis

Parameters:

iSaveflag (int) – EN_SAVE (1) if results saved to file, EN_NOSAVE (0) if not

ENnextH()#

Determines time until next hydraulic event

This function is used in a loop with ENrunH() to run an extended period hydraulic simulation. See ENsolveH() for an example.

Returns:

Time (seconds) until next hydraulic event (0 marks end of simulation period)

Return type:

int

ENnextQ()#

Advances water quality simulation to next hydraulic event

This function is used in a loop with ENrunQ() to run an extended period water quality simulation. See ENsolveQ() for an example.

Returns:

Time (seconds) until next hydraulic event (0 marks end of simulation period)

Return type:

int

ENopen(inpfile=None, rptfile=None, binfile=None)[source]#

Opens an EPANET input file and reads in network data

Parameters:

  • inpfile (str) – EPANET INP file (default to constructor value)

  • rptfile (str) – Output file to create (default to constructor value)

  • binfile (str) – Binary output file to create (default to constructor value)

ENopenH()#

Sets up data structures for hydraulic analysis

ENopenQ()#

Sets up data structures for water quality analysis

ENreport()#

Writes report to report file

ENrunH()#

Solves hydraulics for conditions at time t

This function is used in a loop with ENnextH() to run an extended period hydraulic simulation. See ENsolveH() for an example.

Returns:

Current simulation time (seconds)

Return type:

int

ENrunQ()#

Retrieves hydraulic and water quality results at time t

This function is used in a loop with ENnextQ() to run an extended period water quality simulation. See ENsolveQ() for an example.

Returns:

Current simulation time (seconds)

Return type:

int

ENsaveH()#

Solves for network hydraulics in all time periods

Must be called before ENreport() if no water quality simulation made. Should not be called if ENsolveQ() will be used.

ENsavehydfile(filename)#

Copies binary hydraulics file to disk

Parameters:

filename (str) – Name of hydraulics file to output

ENsaveinpfile(inpfile)#

Saves EPANET input file

Parameters:

inpfile (str) – EPANET INP output file

ENsetcontrol(iIndex, iType, iLinkIndex, dSetting, iNodeIndex, dLevel)#

Change values on a simple control

Parameters:

  • iIndex (int) – the control index

  • iType (int) – the type of control comparison

  • iLinkIndex (int) – the link being changed

  • dSetting (float) – the setting to change to

  • iNodeIndex (int) – the node being compared against, Set to 0 for time of day or timer

  • dLevel (float) – the level being checked

Warning

There is an error in EPANET 2.2 that sets the dLevel parameter to 0.0 on Macs regardless of the value the user passes in. This means that to use this toolkit functionality on a Mac, the user must delete and create a new control to change the level.

ENsetlinkvalue(iIndex, iCode, fValue)#

Set the value on a link

Parameters:

  • iIndex (int) – the link index

  • iCode (int) – the parameter enum integer

  • fValue (float) – the value to set on the link

ENsetnodevalue(iIndex, iCode, fValue)#

Set the value on a node

Parameters:

  • iIndex (int) – the node index

  • iCode (int) – the parameter enum integer

  • fValue (float) – the value to set on the node

ENsettimeparam(eParam, lValue)#

Set a time parameter value

Parameters:

  • eParam (int) – the time parameter to set

  • lValue (long) – the value to set, in seconds

ENsolveH()#

Solves for network hydraulics in all time periods

ENsolveQ()#

Solves for network water quality in all time periods

ENusehydfile(filename)#

Opens previously saved binary hydraulics file

Parameters:

filename (str) – Name of hydraulics file to use

MSXaddpattern(patternid)[source]#

Add a new, empty MSX source time pattern to an MSX project.

Parameters:

patternid (str) – Name of the new pattern

MSXclose()[source]#

Closes down the Toolkit system (including all files being processed)

MSXgetID(_type, index)[source]#

Get the ID name of an object given its internal index number

Parameters:

  • _type (int, str or ObjectType) – Type of object to get an index for

  • index (int) – Index of the object to get the ID for

Returns:

Object ID

Return type:

str

MSXgetIDlen(_type, index)[source]#

Get the number of characters in the ID name of an MSX object given its internal index number.

Parameters:

  • _type (int, str or ObjectType) – Type of object to get an index for

  • index (int) – Index of the object to get the ID length for

Returns:

Length of the object ID

Return type:

int

MSXgetconstant(constant_index)[source]#

Get the value of a particular reaction constant

Parameters:

constant_index (int) – Index to the constant

Returns:

Value of the constant

Return type:

float

Raises:

EpanetMsxException – Toolkit error occurred

MSXgetcount(_type)[source]#

Get the number of objects of a specified type.

Parameters:

_type (int or str or Enum) – Type of object to count

Returns:

Number of objects of specified type

Return type:

int

Raises:

MSXKeyError – If the _type is invalid

MSXgeterror(errcode, len=100)[source]#

Get the text for an error message given its error code

Parameters:

  • errcode (int) – Error code

  • len (int, optional) – Length of the error message, by default 100 and minimum 80

Returns:

String decoded from the DLL

Return type:

str

Warning

Getting string parameters in this way is not recommended, because it requires setting up string arrays that may or may not be the correct size. Use the wntr.epanet.msx.enums package to get error information.

MSXgetindex(_type, name)[source]#

Gets the internal index of an MSX object given its name.

Parameters:

  • _type (int, str or ObjectType) – Type of object to get an index for

  • name (str) – Name of the object to get an index for

Returns:

Internal index

Return type:

int

Raises:
MSXgetinitqual(_type, node_link_index, species_index)[source]#

Get the initial concentration of a particular chemical species assigned to a specific node or link of the pipe network

Parameters:

  • _type (str, int or ObjectType) – Type of object

  • node_link_index (int) – Object index

  • species_index (int) – Species index

Returns:

Initial quality value for that node or link

Return type:

float

Raises:
MSXgetparameter(_type, node_link_index, param_index)[source]#

Get the value of a particular reaction parameter for a given TANK or PIPE.

Parameters:

  • _type (int or str or Enum) – Get the type of the parameter

  • node_link_index (int) – Link index

  • param_index (int) – Parameter variable index

Returns:

Parameter value

Return type:

float

Raises:
MSXgetpatternlen(pat)[source]#

Get the number of time periods within a SOURCE time pattern.

Parameters:

pat (int) – Pattern index

Returns:

Number of time periods in the pattern

Return type:

int

MSXgetpatternvalue(pat, period)[source]#

Get the multiplier at a specific time period for a given SOURCE time pattern

Parameters:

  • pat (int) – Pattern index

  • period (int) – 1-indexed period of the pattern to retrieve

Return type:

Multiplier

MSXgetqual(_type, node_link_index, species_index)[source]#

Get a chemical species concentration at a given node or the average concentration along a link at the current simulation time step

Parameters:

  • _type (str, int or ObjectType) – Type of object

  • node_link_index (int) – Object index

  • species_index (int) – Species index

Returns:

Current quality value for that node or link

Return type:

float

Raises:
MSXgetsource(node_index, species_index)[source]#

Get information on any external source of a particular chemical species assigned to a specific node of the pipe network

Parameters:

  • node_index (int) – Node index

  • species_index (int) – Species index

Returns:

[source type, level, and pattern] where level is the baseline concentration (or mass flow rate) of the source and pattern the index of the time pattern used to add variability to the source’s baseline level (0 if no pattern defined for the source)

Return type:

list

MSXgetspecies(species_index)[source]#

Get the attributes of a chemical species given its internal index number.

Parameters:

species_index (int) – Species index to query (starting from 1 as listed in the MSX input file)

Returns:

Type, units, aTol, and rTol for the species

Return type:

int, str, float, float

MSXinit(saveFlag=0)[source]#

Initializes the MSX system before solving for water quality results in step-wise fashion set saveFlag to 1 if water quality results should be saved to a scratch binary file, or to 0 is not saved to file

MSXopen(msxfile)[source]#

Opens the MSX Toolkit to analyze a particular distribution system.

Parameters:

msxfile (str) – Name of the MSX input file

MSXreport()[source]#

Writes water quality simulations results as instructed by the MSX input file to a text file

MSXsavemsxfile(filename)[source]#

Saves the data associated with the current MSX project into a new MSX input file

Parameters:

filename (str) – Name of the MSX input file to create

MSXsaveoutfile(filename)[source]#

Saves water quality results computed for each node, link and reporting time period to a named binary file

Parameters:

filename (str) – Save a binary results file

MSXsetconstant(ind, value)[source]#

Set a new value to a specific reaction constant

Parameters:

  • ind (int) – Index to the variable

  • value (float) – Value to give the constant

MSXsetinitqual(_type, ind, spe, value)[source]#

Set the initial concentration of a particular chemical species assigned to a specific node or link of the pipe network.

Parameters:

  • _type (int or str or enum) – Type of network element to set

  • ind (int) – Index of the network element

  • spe (int) – Index of the species

  • value (float) – Initial quality value

MSXsetparameter(_type, ind, param, value)[source]#

Set a value to a particular reaction parameter for a given TANK or PIPE

Parameters:

  • _type (int or str or enum) – Type of value to set

  • ind (int) – Tank or pipe index

  • param (int) – Parameter variable index

  • value (float) – Value to be set

Raises:
MSXsetpattern(pat, mult)[source]#

Set multipliers to a given MSX SOURCE time pattern

Parameters:

  • pat (int) – Pattern index

  • mult (list-like) – Pattern multipliers

MSXsetpatternvalue(pat, period, value)[source]#

Set the multiplier factor for a specific period within a SOURCE time pattern.

Parameters:

  • pat (int) – Pattern index

  • period (int) – 1-indexed pattern time period index

  • value (float) – Value to set at that time period

MSXsetsource(node, spe, _type, level, pat)[source]#

Set the attributes of an external source of a particular chemical species in a specific node of the pipe network

Parameters:

  • node (int) – Node index

  • spe (int) – Species index

  • _type (int or str or enum) – Type of source

  • level (float) – Source quality value

  • pat (int) – Pattern index

MSXsolveH()[source]#

Runs a complete hydraulic simulation with results for all time periods written to the binary Hydraulics file.

MSXsolveQ()[source]#

Solves for water quality over the entire simulation period and saves the results to an internal scratch file

MSXstep()[source]#

Advances the water quality simulation one water quality time step. The time remaining in the overall simulation is returned as tleft, the current time as t.

MSXusehydfile(filename)[source]#

Uses the contents of the specified file as the current binary hydraulics file

Parameters:

filename (str) – Name of the hydraulics file to use

__init__(inpfile='', rptfile='', binfile='', msxfile='')[source]#
isOpen()#

Checks to see if the file is open