Hydraulic Analysis Functions

These functions are used to perform a hydraulic analysis. More...

Functions
int	EN_solveH (EN_Project ph)
	Runs a complete hydraulic simulation with results for all time periods written to a temporary hydraulics file. More...
int	EN_usehydfile (EN_Project ph, const char *filename)
	Uses a previously saved binary hydraulics file to supply a project's hydraulics. More...
int	EN_openH (EN_Project ph)
	Opens a project's hydraulic solver. More...
int	EN_initH (EN_Project ph, int initFlag)
	Initializes a network prior to running a hydraulic analysis. More...
int	EN_runH (EN_Project ph, long *out_currentTime)
	Computes a hydraulic solution for the current point in time. More...
int	EN_nextH (EN_Project ph, long *out_tStep)
	Determines the length of time until the next hydraulic event occurs in an extended period simulation. More...
int	EN_saveH (EN_Project ph)
	Transfers a project's hydraulics results from its temporary hydraulics file to its binary output file, where results are only reported at uniform reporting intervals. More...
int	EN_savehydfile (EN_Project ph, const char *filename)
	Saves a project's temporary hydraulics file to disk. More...
int	EN_closeH (EN_Project ph)
	Closes the hydraulic solver freeing all of its allocated memory. More...

Overview

These functions are used to perform a hydraulic analysis.

Function Documentation

EN_closeH()

int EN_closeH

(

EN_Project

ph

)

Closes the hydraulic solver freeing all of its allocated memory.

Returns

an error code.

Call EN_closeH after all hydraulics analyses have been made using EN_initH - EN_runH - EN_nextH. Do not call this function if EN_solveH is being used.

EN_initH()

int EN_initH	(	EN_Project	ph,
		int	initFlag
	)

Initializes a network prior to running a hydraulic analysis.

Parameters

ph	an EPANET project handle.
initFlag	a 2-digit initialization flag (see EN_InitHydOption).

Returns

an error code.

This function initializes storage tank levels, link status and settings, and the simulation time clock prior to running a hydraulic analysis.

The initialization flag is a two digit number where the 1st (left) digit indicates if link flows should be re-initialized (1) or not (0), and the 2nd digit indicates if hydraulic results should be saved to a temporary binary hydraulics file (1) or not (0).

Be sure to call EN_initH prior to running a hydraulic analysis using a EN_runH - EN_nextH loop.

Choose to save hydraulics results if you will be:

• making a subsequent water quality run,
• using EN_report to generate a report
• using EN_savehydfile to save the binary hydraulics file.

There is no need to save hydraulics if you will be writing custom code to process hydraulic results as they are generated using the functions EN_getnodevalue and EN_getlinkvalue.

EN_nextH()

int EN_nextH	(	EN_Project	ph,
		long *	out_tStep
	)

Determines the length of time until the next hydraulic event occurs in an extended period simulation.

Parameters

	ph	an EPANET project handle.
[out]	tStep	the 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_runH to run an extended period hydraulic simulation.

The value of tstep should be treated as a read-only variable. It is automatically computed as the smaller of:

• the time interval until the next hydraulic time step begins
• the time interval until the next reporting time step begins
• the time interval until the next change in demands occurs
• the time interval until a tank becomes full or empty
• the time interval until a control or rule fires.

Example:

long t, tstep;
EN_openH(ph);
EN_initH(ph, EN_NOSAVE);
do {
  EN_runH(ph, &t);
  // Retrieve hydraulic results for time t
  EN_nextH(ph, &tstep);
} while (tstep > 0);
EN_closeH(ph);

EN_openH()

int EN_openH

(

EN_Project

ph

)

Opens a project's hydraulic solver.

Parameters

ph	an EPANET project handle.

Returns

an error code.

Call EN_openH prior to running the first hydraulic analysis using the EN_initH - EN_runH - EN_nextH sequence. Multiple analyses can be made before calling EN_closeH to close the hydraulic solver.

Do not call this function if EN_solveH is being used to run a complete hydraulic analysis or if hydraulics are being supplied by a previously saved hydraulics file using EN_usehydfile.

EN_runH()

int EN_runH	(	EN_Project	ph,
		long *	out_currentTime
	)

Computes a hydraulic solution for the current point in time.

Parameters

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

Returns

an error or warning code.

This function is used in a loop with EN_nextH to run an extended period hydraulic simulation. This process automatically updates the simulation clock time so currentTime should be treated as a read-only variable.

EN_initH must have been called prior to running the EN_runH - EN_nextH loop.

See EN_nextH for an example of using this function.

EN_saveH()

int EN_saveH

(

EN_Project

ph

)

Transfers a project's hydraulics results from its temporary hydraulics file to its binary output file, where results are only reported at uniform reporting intervals.

Parameters

ph	an EPANET project handle.

Returns

an error code.

EN_saveH is used when only a hydraulic analysis is run and results at uniform reporting intervals need to be transferred to a project's binary output file. Such would be the case when results are to be written in formatted fashion to the project's report file using EN_report.

EN_savehydfile()

int EN_savehydfile	(	EN_Project	ph,
		const char *	filename
	)

Saves a project's temporary hydraulics file to disk.

Parameters

ph	an EPANET project handle.
filename	the name of the file to be created.

Returns

an error code.

Use this function to save the current set of hydraulics results to a file, either for post-processing or to be used at a later time by calling the EN_usehydfile function.

The hydraulics file contains nodal demands and heads and link flows, status, and settings for all hydraulic time steps, even intermediate ones.

Before calling this function hydraulic results must have been generated and saved by having called EN_solveH or the EN_initH - EN_runH - EN_nextH sequence with the initflag argument of EN_initH set to EN_SAVE or EN_SAVE_AND_INIT.

EN_solveH()

int EN_solveH

(

EN_Project

ph

)

Runs a complete hydraulic simulation with results for all time periods written to a temporary hydraulics file.

Parameters

ph	an EPANET project handle.

Returns

an error code.

Use EN_solveH to generate a complete hydraulic solution which can stand alone or be used as input to a water quality analysis. This function will not allow one to examine intermediate hydraulic results as they are generated. It can also be followed by calls to EN_saveH and EN_report to write hydraulic results to the report file.

The sequence EN_openH - EN_initH - EN_runH - EN_nextH - EN_closeH can be used instead to gain access to results at intermediate time periods and directly adjust link status and control settings as a simulation proceeds.

Example:

EN_Project ph;
EN_createproject(&ph);
EN_open(ph, "net1.inp", "net1.rpt", "");
EN_solveH(ph);
EN_solveQ(ph);
EN_report(ph);
EN_deleteproject(ph);

EN_usehydfile()

int EN_usehydfile	(	EN_Project	ph,
		const char *	filename
	)

Uses a previously saved binary hydraulics file to supply a project's hydraulics.

Parameters

ph	an EPANET project handle.
filename	the name of the binary file containing hydraulic results.

Returns

an error code.

Call this function to re-use a set of hydraulic analysis results saved previously. This can save computational time if water quality analyses are being made under the same set of hydraulic conditions.

Do not call this function while the hydraulics solver is open.