Water Quality Analysis Functions

These functions are used to perform a water quality analysis. More...

Functions
int	EN_solveQ (EN_Project ph)
	Runs a complete water quality simulation with results at uniform reporting intervals written to the project's binary output file. More...
int	EN_openQ (EN_Project ph)
	Opens a project's water quality solver. More...
int	EN_initQ (EN_Project ph, int saveFlag)
	Initializes a network prior to running a water quality analysis. More...
int	EN_runQ (EN_Project ph, long *out_currentTime)
	Makes hydraulic and water quality results at the start of the current time period available to a project's water quality solver. More...
int	EN_nextQ (EN_Project ph, long *out_tStep)
	Advances a water quality simulation over the time until the next hydraulic event. More...
int	EN_stepQ (EN_Project ph, long *out_timeLeft)
	Advances a water quality simulation by a single water quality time step. More...
int	EN_closeQ (EN_Project ph)
	Closes the water quality solver, freeing all of its allocated memory. More...

Overview

These functions are used to perform a water quality analysis.

Function Documentation

EN_closeQ()

int EN_closeQ

(

EN_Project

ph

)

Closes the water quality solver, freeing all of its allocated memory.

Parameters

ph	an EPANET project handle.

Returns

an error code.

Call EN_closeQ after all water quality analyses have been made using the EN_initQ - EN_runQ - EN_nextQ (or EN_stepQ) sequence of function calls.

Do not call this function if EN_solveQ is being used.

EN_initQ()

int EN_initQ	(	EN_Project	ph,
		int	saveFlag
	)

Initializes a network prior to running a water quality analysis.

Parameters

ph	an EPANET project handle.
saveFlag	set to EN_SAVE (1) if results are to be saved to the project's binary output file, or to EN_NOSAVE (0) if not.

Returns

an error code.

Call EN_initQ prior to running a water quality analysis using EN_runQ in conjunction with either EN_nextQ or EN_stepQ.

EN_openQ must have been called prior to calling EN_initQ.

Do not call EN_initQ if a complete water quality analysis will be made using EN_solveQ.

EN_nextQ()

int EN_nextQ	(	EN_Project	ph,
		long *	out_tStep
	)

Advances a water quality simulation over the time until the next hydraulic event.

Parameters

	ph	an EPANET project handle.
[out]	tStep	time (in seconds) until the next hydraulic event or 0 if at the end of the full simulation duration.

Returns

an error code.

This function is used in a loop with EN_runQ to perform an extended period water quality analysis. It reacts and routes a project's water quality constituent over a time step determined by when the next hydraulic event occurs. Use EN_stepQ instead if you wish to generate results over each water quality time step.

The value of tStep is determined from information produced by the hydraulic analysis that preceded the water quality analysis. Treat it as a read-only variable.

Example:

long t, tStep;
EN_solveH(ph);  // Generate & save hydraulics
EN_openQ(ph);
EN_initQ(ph, EN_NOSAVE);
do {
  EN_runQ(ph, &t);
  // Monitor results at time t, which
  // begins a new hydraulic time period
  EN_nextQ(ph, &tStep);
} while (tStep > 0);
EN_closeQ(ph);

EN_openQ()

int EN_openQ

(

EN_Project

ph

)

Opens a project's water quality solver.

Parameters

ph	n EPANET project handle.

Returns

an error code.

Call EN_openQ prior to running the first water quality analysis using an EN_initQ - EN_runQ - EN_nextQ (or EN_stepQ) sequence. Multiple water quality analyses can be made before calling EN_closeQ to close the water quality solver.

Do not call this function if a complete water quality analysis will be made using EN_solveQ.

EN_runQ()

int EN_runQ	(	EN_Project	ph,
		long *	out_currentTime
	)

Makes hydraulic and water quality results at the start of the current time period available to a project's water quality solver.

Parameters

	ph	an EPANET project handle.
[out]	currentTime	current simulation time in seconds.

Returns

an error code.

Use EN_runQ along with EN_nextQ in a loop to access water quality results at the start of each hydraulic period in an extended period simulation. Or use it in a loop with EN_stepQ to access results at the start of each water quality time step. See each of these functions for examples of how to code such loops.

EN_initQ must have been called prior to running an EN_runQ - EN_nextQ (or EN_stepQ) loop.

The current time of the simulation is determined from information saved with the hydraulic analysis that preceded the water quality analysis. Treat it as a read-only variable.

EN_solveQ()

int EN_solveQ

(

EN_Project

ph

)

Runs a complete water quality simulation with results at uniform reporting intervals written to the project's binary output file.

Parameters

ph	an EPANET project handle.

Returns

an error code.

A hydraulic analysis must have been run and saved to a hydraulics file before calling EN_solveQ. This function will not allow one to examine intermediate water quality results as they are generated. It can be followed by a call to EN_report to write all hydraulic and water quality results to a formatted report file.

One can instead use the EN_openQ - EN_initQ - EN_runQ - EN_nextQ - EN_closeQ sequence to gain access to gain access to water quality results at intermediate time periods.

Example: see EN_solveH.

EN_stepQ()

int EN_stepQ	(	EN_Project	ph,
		long *	out_timeLeft
	)

Advances a water quality simulation by a single water quality time step.

Parameters

	ph	an EPANET project handle.
[out]	timeLeft	time left (in seconds) to the overall simulation duration.

Returns

an error code.

This function is used in a loop with EN_runQ to perform an extended period water quality simulation. It allows one to generate water quality results at each water quality time step of the simulation, rather than over each hydraulic event period as with EN_nextQ.

Use the argument timeLeft to determine when no more calls to EN_runQ are needed because the end of the simulation period has been reached (i.e., when timeLeft = 0).