MSX Functions

These are the methods exposed by EPANET-MSX, the multi-species extension of EPANET. It enables performing simulations of chemical species transport and concentration changes through a network.

MSX requires an `-msx` engine variant

These functions are only available when you load an EPANET engine built with MSX support. Pick the default loader or any of the *-msx engine variants (v2.2-msx, v2.3.5-msx, master-msx, dev-msx, …) via the slim loader. See Workspace for an example.

The typical sequence for a complete MSX run is:

1. Load an -msx engine and create a Project.
2. Open the EPANET project (open) and write the MSX configuration file into the workspace.
3. Call msxOpen with the path of the MSX file.
4. Run hydraulics — either msxSolveH for a single run, or msxUseHydFile to reuse a previously saved hydraulics file.
5. Run quality — either msxSolveQ for a single run, or the msxInit → msxStep loop to step through the simulation.
6. Read results with msxGetQual, then call msxClose.

Function	Versions	Description
msxOpen	MSX 2.2+	Opens an MSX configuration file and binds it to the EPANET project.
msxClose	MSX 2.2+	Releases all memory used by the MSX solver.
msxSolveH	MSX 2.2+	Solves hydraulics for the EPANET project.
msxUseHydFile	MSX 2.2+	Re-uses a previously saved hydraulics file.
msxSolveQ	MSX 2.2+	Runs a complete MSX water-quality simulation.
msxInit	MSX 2.2+	Initializes the MSX solver before stepping through the simulation.
msxStep	MSX 2.2+	Advances the MSX simulation by one water-quality step.
msxReport	MSX 2.2+	Writes a formatted MSX report to the project’s report file.
msxSaveOutFile	MSX 2.2+	Saves the binary MSX output file.
msxSaveMsxFile	MSX 2.2+	Saves the current MSX configuration to a text file.
msxGetCount	MSX 2.2+	Returns the number of MSX objects of a given type.
msxGetIndex	MSX 2.2+	Looks up the index of an MSX object by its ID.
msxGetId	MSX 2.2+	Looks up the ID of an MSX object by its index.
msxGetIdLen	MSX 2.2+	Returns the length of an MSX object’s ID.
msxGetSpecies	MSX 2.2+	Returns type, units and tolerances of a chemical species.
msxGetConstant	MSX 2.2+	Reads the value of an MSX reaction constant.
msxSetConstant	MSX 2.2+	Writes the value of an MSX reaction constant.
msxGetParameter	MSX 2.2+	Reads an MSX reaction parameter for a node/link.
msxSetParameter	MSX 2.2+	Writes an MSX reaction parameter for a node/link.
msxGetInitQual	MSX 2.2+	Reads the initial concentration of a species at a node or link.
msxSetInitQual	MSX 2.2+	Writes the initial concentration of a species at a node or link.
msxGetQual	MSX 2.2+	Reads the current computed concentration of a species at a node or link.
msxGetSource	MSX 2.2+	Reads the source definition of a species at a node.
msxSetSource	MSX 2.2+	Writes the source definition of a species at a node.
msxAddPattern	MSX 2.2+	Adds a new MSX time pattern.
msxSetPattern	MSX 2.2+	Replaces all multipliers of an MSX time pattern.
msxSetPatternValue	MSX 2.2+	Updates a single period of an MSX time pattern.
msxGetPatternLen	MSX 2.2+	Returns the number of periods in an MSX time pattern.
msxGetPatternValue	MSX 2.2+	Returns a single multiplier from an MSX time pattern.

---

msxOpen MSX 2.2+

Opens an MSX configuration file and binds it to the underlying EPANET project.

msxOpen(msxFilePath: string): void;

Parameters

Parameter	Type	Description
msxFilePath	string	path of the .msx file inside the workspace filesystem.

open on the EPANET project must have been called first.

---

msxClose MSX 2.2+

Releases all memory used by the MSX solver.

msxClose(): void;

---

msxSolveH MSX 2.2+

Runs a full hydraulic simulation and saves its results so MSX can consume them. Equivalent to solveH for the MSX solver.

msxSolveH(): void;

---

msxUseHydFile MSX 2.2+

Uses a previously saved EPANET hydraulics file as the input to the MSX solver instead of re-running hydraulics.

msxUseHydFile(hydFilePath: string): void;

Parameters

Parameter	Type	Description
hydFilePath	string	path of the hydraulics file inside the workspace.

---

msxSolveQ MSX 2.2+

Runs a complete MSX quality simulation in one call. After it returns, results can be inspected with msxGetQual.

msxSolveQ(): void;

Use the msxInit → msxStep loop instead if you want to read intermediate concentrations.

---

msxInit MSX 2.2+

Initializes the MSX quality solver before stepping through the simulation.

msxInit(saveFlag: number): void;

Parameters

Parameter	Type	Description
saveFlag	number	set to 1 to save intermediate results to the MSX binary file, 0 not.

---

msxStep MSX 2.2+

Advances the MSX simulation by one water-quality step. Returns the current simulation time and the time remaining.

msxStep(): {
  t: number;
  tleft: number;
};

Returns

Object

Property	Type	Description
t	number	current simulation time in seconds.
tleft	number	time remaining in the simulation, in seconds (0 = done).

Drive a full simulation by calling msxStep in a loop until tleft reaches 0.

---

msxReport MSX 2.2+

Writes a formatted MSX report to the project’s report file.

msxReport(): void;

---

msxSaveOutFile MSX 2.2+

Saves the MSX binary output file to disk (within the workspace virtual filesystem).

msxSaveOutFile(outFilePath: string): void;

Parameters

Parameter	Type	Description
outFilePath	string	path of the file to create in the workspace.

---

msxSaveMsxFile MSX 2.2+

Saves the current MSX configuration (species, reactions, sources, patterns, …) back out to a text .msx file.

msxSaveMsxFile(msxFilePath: string): void;

Parameters

Parameter	Type	Description
msxFilePath	string	path of the file to create in the workspace.

---

msxGetCount MSX 2.2+

Returns the number of MSX objects of a given type currently registered with the project.

msxGetCount(type: number): number;

Parameters

Parameter	Type	Description
type	number	one of the MsxConstant codes.

Returns

Number the number of objects of that type.

---

msxGetIndex MSX 2.2+

Looks up the index of an MSX object by its ID name.

msxGetIndex(type: number, id: string): number;

Parameters

Parameter	Type	Description
type	number	one of the MsxConstant codes.
id	string	the object’s ID name.

---

msxGetId MSX 2.2+

Looks up the ID name of an MSX object by index.

msxGetId(type: number, index: number): string;

Parameters

Parameter	Type	Description
type	number	one of the MsxConstant codes.
index	number	the object’s index (starting from 1).

---

msxGetIdLen MSX 2.2+

Returns the length, in characters, of an MSX object’s ID name.

msxGetIdLen(type: number, id: number): number;

Parameters

Parameter	Type	Description
type	number	one of the MsxConstant codes.
id	number	the object’s index (starting from 1).

---

msxGetSpecies MSX 2.2+

Returns metadata about a chemical species.

msxGetSpecies(index: number): {
  type: MsxChemicalSpeciesType;
  units: string;
  aTol: number;
  rTol: number;
};

Parameters

Parameter	Type	Description
index	number	species index (starting from 1).

Returns

Object

Property	Type	Description
type	MsxChemicalSpeciesType	bulk or wall species (see MsxChemicalSpeciesType).
units	string	concentration units.
aTol	number	absolute concentration tolerance.
rTol	number	relative concentration tolerance.

---

msxGetConstant MSX 2.2+

Reads the value of an MSX reaction constant.

msxGetConstant(index: number): number;

Parameters

Parameter	Type	Description
index	number	constant index (starting from 1).

---

msxSetConstant MSX 2.2+

Writes the value of an MSX reaction constant.

msxSetConstant(index: number, value: number): void;

Parameters

Parameter	Type	Description
index	number	constant index (starting from 1).
value	number	new value for the constant.

---

msxGetParameter MSX 2.2+

Reads an MSX reaction parameter for a node or link.

msxGetParameter(type: number, index: number, param: number): number;

Parameters

Parameter	Type	Description
type	number	either MsxConstant.MSX_NODE or MsxConstant.MSX_LINK.
index	number	the node or link index.
param	number	the parameter index.

---

msxSetParameter MSX 2.2+

Writes an MSX reaction parameter for a node or link.

msxSetParameter(type: number, index: number, param: number, value: number): void;

Parameters

Parameter	Type	Description
type	number	either MsxConstant.MSX_NODE or MsxConstant.MSX_LINK.
index	number	the node or link index.
param	number	the parameter index.
value	number	new value for the parameter.

---

msxGetInitQual MSX 2.2+

Reads the initial concentration of a species at a node or link.

msxGetInitQual(type: number, index: number, species: number): number;

Parameters

Parameter	Type	Description
type	number	either MsxConstant.MSX_NODE or MsxConstant.MSX_LINK.
index	number	the node or link index.
species	number	the species index (starting from 1).

---

msxSetInitQual MSX 2.2+

Writes the initial concentration of a species at a node or link.

msxSetInitQual(type: number, index: number, species: number, value: number): void;

Parameters

Parameter	Type	Description
type	number	either MsxConstant.MSX_NODE or MsxConstant.MSX_LINK.
index	number	the node or link index.
species	number	the species index (starting from 1).
value	number	initial concentration.

---

msxGetQual MSX 2.2+

Reads the current computed concentration of a species at a node or link. Call after msxStep or once msxSolveQ has finished.

msxGetQual(type: number, index: number, species: number): number;

Parameters

Parameter	Type	Description
type	number	either MsxConstant.MSX_NODE or MsxConstant.MSX_LINK.
index	number	the node or link index.
species	number	the species index (starting from 1).

---

msxGetSource MSX 2.2+

Reads the current source definition of a species at a node.

msxGetSource(node: number, species: number): {
  type: MsxChemicalSpeciesSourceType;
  level: number;
  pat: number;
};

Parameters

Parameter	Type	Description
node	number	the node index (starting from 1).
species	number	the species index (starting from 1).

Returns

Object

Property	Type	Description
type	MsxChemicalSpeciesSourceType	the source’s kind (see MsxChemicalSpeciesSourceType).
level	number	source’s baseline concentration or mass-rate.
pat	number	index of the time pattern that scales the source (0 if none).

---

msxSetSource MSX 2.2+

Writes the source definition of a species at a node.

msxSetSource(
  node: number,
  species: number,
  type: MsxChemicalSpeciesSourceType,
  level: number,
  pat: number,
): void;

Parameters

Parameter	Type	Description
node	number	the node index (starting from 1).
species	number	the species index (starting from 1).
type	MsxChemicalSpeciesSourceType	the source kind (see MsxChemicalSpeciesSourceType).
level	number	source’s baseline concentration or mass-rate.
pat	number	index of the time pattern that scales the source (0 for none).

---

msxAddPattern MSX 2.2+

Adds a new (empty) MSX time pattern with the given ID.

msxAddPattern(id: string): void;

Parameters

Parameter	Type	Description
id	string	the ID name of the new pattern.

---

msxSetPattern MSX 2.2+

Replaces all multipliers of an existing MSX pattern in one call.

msxSetPattern(pat: number, mult: number[]): void;

Parameters

Parameter	Type	Description
pat	number	the pattern’s index (starting from 1).
mult	number[]	the new array of multipliers.

---

msxSetPatternValue MSX 2.2+

Updates a single period of an MSX time pattern.

msxSetPatternValue(pat: number, period: number, value: number): void;

Parameters

Parameter	Type	Description
pat	number	the pattern’s index (starting from 1).
period	number	the period within the pattern (starting from 1).
value	number	new multiplier for that period.

---

msxGetPatternLen MSX 2.2+

Returns the number of periods in an MSX time pattern.

msxGetPatternLen(pat: number): number;

Parameters

Parameter	Type	Description
pat	number	the pattern’s index (starting from 1).

---

msxGetPatternValue MSX 2.2+

Returns a single multiplier from an MSX time pattern.

msxGetPatternValue(pat: number, period: number): number;

Parameters

Parameter	Type	Description
pat	number	the pattern’s index (starting from 1).
period	number	the period within the pattern (starting from 1).