OWA-EPANET Toolkit  2.2
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 *currentTime)
 Computes a hydraulic solution for the current point in time. More...
 
int EN_nextH (EN_Project ph, long *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
phan EPANET project handle.
initFlaga 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 *  tStep 
)

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

Parameters
phan EPANET project handle.
[out]tStepthe 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;
do {
EN_runH(ph, &t);
// Retrieve hydraulic results for time t
EN_nextH(ph, &tstep);
} while (tstep > 0);

◆ EN_openH()

int EN_openH ( EN_Project  ph)

Opens a project's hydraulic solver.

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

Computes a hydraulic solution for the current point in time.

Parameters
phan EPANET project handle.
[out]currentTimethe 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
phan 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
phan EPANET project handle.
filenamethe 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
phan 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_open(ph, "net1.inp", "net1.rpt", "");

◆ 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
phan EPANET project handle.
filenamethe 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.

EN_closeH
int EN_closeH(EN_Project ph)
Closes the hydraulic solver freeing all of its allocated memory.
EN_open
int EN_open(EN_Project ph, const char *inpFile, const char *rptFile, const char *outFile)
Opens an EPANET input file & reads in network data.
EN_Project
struct Project * EN_Project
The EPANET Project wrapper object.
Definition: epanet2_2.h:49
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_nextH
int EN_nextH(EN_Project ph, long *tStep)
Determines the length of time until the next hydraulic event occurs in an extended period simulation.
EN_createproject
int EN_createproject(EN_Project *ph)
Creates an EPANET project.
EN_solveQ
int EN_solveQ(EN_Project ph)
Runs a complete water quality simulation with results at uniform reporting intervals written to the p...
EN_openH
int EN_openH(EN_Project ph)
Opens a project's hydraulic solver.
EN_report
int EN_report(EN_Project ph)
Writes simulation results in a tabular format to a project's report file.
EN_runH
int EN_runH(EN_Project ph, long *currentTime)
Computes a hydraulic solution for the current point in time.
EN_NOSAVE
Don't save hydraulics; don't re-initialize flows.
Definition: epanet2_enums.h:369
EN_deleteproject
int EN_deleteproject(EN_Project ph)
Deletes a currently opened EPANET project.
EN_initH
int EN_initH(EN_Project ph, int initFlag)
Initializes a network prior to running a hydraulic analysis.