OWA-EPANET Toolkit  2.2
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 *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 *tStep)
 Advances a water quality simulation over the time until the next hydraulic event. More...
 
int EN_stepQ (EN_Project ph, long *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
phan 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
phan EPANET project handle.
saveFlagset 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 *  tStep 
)

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

Parameters
phan EPANET project handle.
[out]tSteptime (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
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_openQ()

int EN_openQ ( EN_Project  ph)

Opens a project's water quality solver.

Parameters
phn 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 *  currentTime 
)

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

Parameters
phan EPANET project handle.
[out]currentTimecurrent 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
phan 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 *  timeLeft 
)

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

Parameters
phan EPANET project handle.
[out]timeLefttime 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).

EN_solveH
int EN_solveH(EN_Project ph)
Runs a complete hydraulic simulation with results for all time periods written to a temporary hydraul...
EN_closeQ
int EN_closeQ(EN_Project ph)
Closes the water quality solver, freeing all of its allocated memory.
EN_initQ
int EN_initQ(EN_Project ph, int saveFlag)
Initializes a network prior to running a water quality analysis.
EN_nextQ
int EN_nextQ(EN_Project ph, long *tStep)
Advances a water quality simulation over the time until the next hydraulic event.
EN_NOSAVE
Don't save hydraulics; don't re-initialize flows.
Definition: epanet2_enums.h:369
EN_runQ
int EN_runQ(EN_Project ph, long *currentTime)
Makes hydraulic and water quality results at the start of the current time period available to a proj...
EN_openQ
int EN_openQ(EN_Project ph)
Opens a project's water quality solver.