Skip to content

Commit

Permalink
Merge pull request #210 from LRossman/contributor-lr
Browse files Browse the repository at this point in the history
Pressure Dependent Demands added to address issue 163
  • Loading branch information
michaeltryby authored Aug 24, 2018
2 parents 761199b + 9306119 commit c4b7c90
Show file tree
Hide file tree
Showing 25 changed files with 1,518 additions and 1,022 deletions.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ The EPANET Library is a pressurized pipe network hydraulic and water quality ana

Please see the [`version 2.1` Release Notes](https://github.com/OpenWaterAnalytics/EPANET/blob/master/ReleaseNotes2_1.md) for information relevant to users of the previous official version (2.00.12). If you would like to contribute by addressing any of the outstanding [Issues](https://github.com/OpenWaterAnalytics/EPANET/issues), then please comment on the Issue, then Fork this repo to your own account and base your commits on the [`dev` branch](https://github.com/OpenWaterAnalytics/EPANET/tree/dev). Once you are finished, you can open a Pull Request to test the code and discuss merging your changes back into the community respository.

A step-by-step tutorial on how to contribute to EPANET using GitHub is also [available] (http://www.slideshare.net/demetriseliades/contributing-to-epanet-using-github-in-windows).
A step-by-step tutorial on how to contribute to EPANET using GitHub is also [available](http://www.slideshare.net/demetriseliades/contributing-to-epanet-using-github-in-windows).

__Note:__ This repository is not affiliated with, or endorsed by, the USEPA. For the last "official" release of EPANET (2.00.12 UI and Toolkit) please go to the [EPA's GitHub repo](https://github.com/USEPA/Water-Distribution-Network-Model) or [the USEPA website](http://www2.epa.gov/water-research/epanet). It is also not the graphical user interface version. This is the hydraulic and water quality solver engine.

However, if you are interested in extending EPANET for academic, personal, or commercial use, then you've come to the right place. For community discussion, FAQ, and roadmapping of the project, go to the [Community Forum](http://community.wateranalytics.org/category/epanet).

96 changes: 96 additions & 0 deletions ReleaseNotes2_2.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@



Release Notes for EPANET 2.2 (Draft)
============================

This document describes the changes and updates that have been made to version 2.2 of EPANET.

## Thread-Safe API Functions

A duplicate set of the version 2.1 API functions has been provided that allow multiple EPANET projects to be analyzed concurrently in a thread-safe manner. These functions maintain the same name as the original but use a `EN_` prefix instead of `EN`. In addition, the first argument to each of these functions is a pointer to an `EN_Project` structure that encapsulates the network data for the particular project being analyzed. For example, instead of writing:

`ENgetnodevalue(nodeIndex, EN_ELEVATION, &elev)`

one would use:

`EN_getnodevalue(pr, nodeIndex, EN_ELEVATION, &elev)`

where `pr` is the pointer to an `EN_Project`.

Two new functions have been added to the API to manage the creation and deletion of project pointers. `EN_createproject` creates a new project along with a pointer to it, while `EN_deleteproject` deletes a project. An example of using the thread-safe version of the API is shown below:
```
#include "epanet2.h"
int runEpanet(char *finp, char *frpt)
{
EN_Project *pr = NULL;
int err;
err = EN_createproject(&pr);
if (err) return err;
err = EN_open(pr, finp, frpt, "");
if (!err) err = EN_solveH(pr);
if (!err) err = EN_report(pr);
EN_close(pr);
EN_deleteproject(pr);
return err;
}
```

## Additional Convergence Parameters

Two new analysis options have been added to provide more rigorous convergence criteria for EPANET's hydraulic solver. In the API they are named `EN_HEADERROR` and `EN_FLOWCHANGE` while in the `[OPTIONS]` section of an EPANET input file they are named `HEADERROR` and `FLOWCHANGE`, respectively.

`EN_HEADERROR` is the maximum head loss error that any network link can have for hydraulic convergence to occur. A link's head loss error is the difference between the head loss found as a function of computed flow in the link (such as by the Hazen-Williams equation for a pipe) and the difference in computed heads for the link's end nodes. The units of this parameter are feet (or meters for SI units). The default value of 0 indicates that no head error limit applies.

`EN_FLOWCHANGE` is the largest change in flow that any network element (link, emitter, or pressure-dependent demand) can have for hydraulic convergence to occur. It is specified in whatever flow units the project is using. The default value of 0 indicates that no flow change limit applies.

These new parameters augment the current `EN_ACCURACY` option which always remains in effect. In addition, both `EN_HEADERROR` and `EN_FLOWCHANGE` can be used as parameters in the `ENgetstatistic` (or `EN_getstatistic`) function to retrieve their computed values (even when their option values are 0) after a hydraulic solution has been completed.

## Improved Linear Solver Routine
EPANET's hydraulic solver requires solving a system of linear equations over a series of iterations until a set of convergence criteria are met. The coefficient matrix of this linear system is square and symmetric. It has a row for each network node and a non-zero off-diagonal coefficient for each link. The numerical effort needed to solve the linear system can be reduced if the nodes are re-ordered so that the non-zero coefficients cluster more tightly around the diagonal.

EPANET's original node re-ordering scheme has been replaced by the more powerful **Multiple Minimum Degree (MMD)** algorithm. On a series of eight networks ranging in size from 7,700 to 100,000 nodes **MMD** reduced the solution time for a single period (steady state) hydraulic analysis by an average of more than 50%.

## Pressure Dependent Demands
EPANET has always employed a Demand Driven Analysis (**DDA**) when modeling network hydraulics. Under this approach nodal demands at a given point in time are fixed values that must be delivered no matter what nodal heads and link flows are produced by a hydraulic solution. This can result in situations where required demands are satisfied at nodes that have negative pressures - a physical impossibility.

To address this issue EPANET has been extended to use a Pressure Driven Analysis (**PDA**) if so desired. Under **PDA**, the demand *D* delivered at a node depends on the node's available pressure *P* according to:
$$D =D_f\left(\frac{P-P_{min}}{P_{req}-P_{min}}\right)^{P_{exp}} for P_{0}<=P<=P_{req}$$where *D<sub>f</sub>* is the full demand required, *P<sub>min</sub>* is the pressure below which demand is zero, *P<sub>req</sub>* is the pressure required to deliver the full required demand and *P<sub>exp</sub>* is an exponent. When *P < P<sub>min</sub>* demand is 0 and when *P > P<sub>req</sub>* demand equals *D<sub>f</sub>*.

To implement pressure dependent analysis four new parameters have been added to the [OPTIONS] section of the EPANET input file:


| Parameter | Description | Default |
|--|--|--|
| DEMAND MODEL | either DDA or PDA | DDA |
| MINIMUM PRESSURE | value for *P<sub>min</sub>* | 0
| REQUIRED PRESSURE | value for *P<sub>req</sub>* | 0
| PRESSURE EXPONENT | value for *P<sub>exp</sub>* | 0.5 |

These parameters can also be set and retrieved in code using the following API functions
```
int ENsetdemandmodel(int modelType, double pMin, double pReq, double pExp);
int ENgetdemandmodel(int *modelType, double *pMin, double *pReq, double *pExp);
```
for the legacy API and
```
int EN_setdemandmodel(EN_Project *pr, int modelType, double pMin, double pReq, double pExp);
int EN_getdemandmodel(EN_Project *pr, int *modelType, double *pMin, double *pReq, double *pExp);
```
for the thread-safe API. Some additional points regarding the new **PDA** option are:

- If no DEMAND MODEL and its parameters are specified then the analysis defaults to being demand driven (**DDA**).
- This implementation of **PDA** assumes that the same parameters apply to all nodes in the network. Extending the framework to allow different parameters for specific nodes is straightforward to do but is left as a future feature to implement.
- *P<sub>0</sub>* is allowed to equal to *P<sub>req</sub>*. This condition can be used to find a solution that results in the smallest amount of demand reductions needed to insure that no node delivers positive demand at a pressure below *P<sub>min</min>*.

## Code Changes

- The header file `vars.h` containing global variables has been eliminated. Instead a number of new structures incorporating these variables has been added to `types.h`. These structures have been incorporated into the new `EN_Project` structure, also defined in `types.h`, which gets passed into each of the thread-safe API functions as a pointer.
- Each of the legacy API functions now simply calls its thread-safe counterpart passing in a pointer to a default global`EN_Project` variable that is declared in `types.h`.
- Throughout all code modules, global variables that were previously accessed through `vars.h` are now accessed using the `EN_Project` pointer that is passed into the functions where the variables appear.
- The exceedingly long `hydraul.c` file has been split into four separate files:
- `hydraul.c` now contains just the code needed to initialize a hydraulic analysis, set demands and control actions at each time step, and determine the length of the next time step to take.
- `hydsolver.c` implements EPANET's hydraulic solver at a single point in time.
- `hydcoeffs.c` computes values of the matrix coefficients (derived from link head losses and their gradients) used by the hydraulic solver.
- `hydstatus.c` checks for status changes in valves and pumps as requested by the hydraulic solver.
- The Multiple Minimum Degree re-ordering algorithm appears in a new file named `genmmd.c`. This is 1990's legacy code that is readily available on the web and can be found in several linear equation solver libraries.
8 changes: 8 additions & 0 deletions include/epanet2.bas
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,8 @@ Public Const EN_NEXTEVENT = 14

Public Const EN_ITERATIONS = 0
Public Const EN_RELATIVEERROR = 1
Public Const EN_MAXHEADERROR = 2
Public Const EN_MAXFLOWCHANGE = 3

Public Const EN_NODECOUNT = 0 'Component counts
Public Const EN_TANKCOUNT = 1
Expand Down Expand Up @@ -126,6 +128,9 @@ Public Const EN_MLD = 7
Public Const EN_CMH = 8
Public Const EN_CMD = 9

Public Const EN_DDA = 0 ' Demand driven analysis
Public Const EN_PDA = 1 ' Pressure driven analysis

Public Const EN_TRIALS = 0 ' Misc. options
Public Const EN_ACCURACY = 1
Public Const EN_TOLERANCE = 2
Expand Down Expand Up @@ -233,6 +238,9 @@ Public Const EN_G_CURVE = 4 ' General\default curve

Declare Function ENgetversion Lib "epanet2.dll" (value As Long) As Long

Declare Function ENgetdemandmodel Lib "epanet2.dll" (type as long, pmin as Single, preq as Single, pexp as Single) As Long
Declare Function ENsetdemandmodel Lib "epanet2.dll" (ByVal type as long, ByVal pmin as Single, ByVal preq as Single, ByVal pexp as Single) As Long

Declare Function ENsetflowunits Lib "epanet2.dll" (ByVal code As Long) As Long
Declare Function ENsetcontrol Lib "epanet2.dll" (ByVal Cindex As Long, ByVal Ctype As Long, ByVal Lindex As Long, ByVal setting As Single, ByVal Nindex As Long, ByVal Level As Single) As Long
Declare Function ENsetnodevalue Lib "epanet2.dll" (ByVal index As Long, ByVal code As Long, ByVal value As Single) As Long
Expand Down
55 changes: 39 additions & 16 deletions include/epanet2.h
Original file line number Diff line number Diff line change
Expand Up @@ -141,10 +141,11 @@ typedef enum {
EN_NEXTEVENTIDX = 15
} EN_TimeProperty;


typedef enum {
EN_ITERATIONS = 0,
EN_RELATIVEERROR = 1
EN_RELATIVEERROR = 1,
EN_MAXHEADERROR = 2,
EN_MAXFLOWCHANGE = 3
} EN_AnalysisStatistic;

typedef enum {
Expand All @@ -153,7 +154,7 @@ typedef enum {
EN_LINKCOUNT = 2, /**< Number of Links (Pipes + Pumps + Valves) */
EN_PATCOUNT = 3, /**< Number of Time Patterns */
EN_CURVECOUNT = 4, /**< Number of Curves */
EN_CONTROLCOUNT = 5, /**< Number of Control Statements */
EN_CONTROLCOUNT = 5, /**< Number of Control Statements */
EN_RULECOUNT = 6 /**< Number of Rule-based Control Statements */
} EN_CountType;

Expand Down Expand Up @@ -208,6 +209,10 @@ typedef enum {
EN_CMD = 9
} EN_FlowUnits;

typedef enum { /* Demand model types. */
EN_DDA = 0, /**< Demand driven analysis */
EN_PDA = 1 /**< Pressure driven analysis */
} EN_DemandModel;

/// Simulation Option codes
typedef enum {
Expand Down Expand Up @@ -272,8 +277,6 @@ extern "C" {
@brief The EPANET Project wrapper object
*/
typedef struct EN_Project EN_Project;
typedef struct EN_Pattern EN_Pattern;
typedef struct EN_Curve EN_Curve;

/**
@brief runs a complete EPANET simulation
Expand Down Expand Up @@ -524,7 +527,29 @@ extern "C" {
@return Error code
*/
int DLLEXPORT ENsetflowunits(int code);


/**
@brief Retrieves the type of demand model in use and its parameters
@param[out] type Type of demand model (EN_DDA or EN_PDA)
@param[out] pmin Pressure below which there is no demand
@param[out] preq Pressure required to deliver full demand
@param[out] pexp Pressure exponent in demand function
@return Error code
*/
int DLLEXPORT ENgetdemandmodel(int *type, EN_API_FLOAT_TYPE *pmin,
EN_API_FLOAT_TYPE *preq, EN_API_FLOAT_TYPE *pexp);

/**
@brief Sets the type of demand model to use and its parameters
@param type Type of demand model (EN_DDA or EN_PDA)
@param pmin Pressure below which there is no demand
@param preq Pressure required to deliver full demand
@param pexp Pressure exponent in demand function
@return Error code
*/
int DLLEXPORT ENsetdemandmodel(int type, EN_API_FLOAT_TYPE pmin,
EN_API_FLOAT_TYPE preq, EN_API_FLOAT_TYPE pexp);

/**
@brief Retrieves the index of the time pattern with specified ID
@param id String ID of the time pattern
Expand Down Expand Up @@ -806,7 +831,7 @@ extern "C" {
int DLLEXPORT ENsetnodevalue(int index, int code, EN_API_FLOAT_TYPE v);

/**
@brief Set a proprty value for a link.
@brief Set a property value for a link.
@param index The index of a link. First link is index 1.
@param code The code for the property to set.
@param v The value to set for this link and property.
Expand Down Expand Up @@ -1131,15 +1156,14 @@ extern "C" {
int DLLEXPORT ENdeletelink(int linkIndex);




/***************************************************
Threadsafe versions of all epanet functions
***************************************************/
int DLLEXPORT EN_alloc(EN_Project **p);
int DLLEXPORT EN_free(EN_Project *p);
int DLLEXPORT EN_createproject(EN_Project **p);
int DLLEXPORT EN_deleteproject(EN_Project *p);

int DLLEXPORT EN_epanet(char *inpFile, char *rptFile, char *binOutFile, void (*callback) (char *));
int DLLEXPORT EN_init(EN_Project *p, char *rptFile, char *binOutFile, EN_FlowUnits UnitsType, EN_FormType HeadlossFormula);
int DLLEXPORT EN_open(EN_Project *p, char *inpFile, char *rptFile, char *binOutFile);
Expand Down Expand Up @@ -1171,6 +1195,10 @@ extern "C" {
int DLLEXPORT EN_gettimeparam(EN_Project *p, int code, long *value);
int DLLEXPORT EN_getflowunits(EN_Project *p, int *code);
int DLLEXPORT EN_setflowunits(EN_Project *p, int code);
int DLLEXPORT EN_getdemandmodel(EN_Project *p, int *type, EN_API_FLOAT_TYPE *pmin, EN_API_FLOAT_TYPE *preq,
EN_API_FLOAT_TYPE *pexp);
int DLLEXPORT EN_setdemandmodel(EN_Project *p, int type, EN_API_FLOAT_TYPE pmin, EN_API_FLOAT_TYPE preq,
EN_API_FLOAT_TYPE pexp);
int DLLEXPORT EN_getpatternindex(EN_Project *p, char *id, int *index);
int DLLEXPORT EN_getpatternid(EN_Project *p, int index, char *id);
int DLLEXPORT EN_getpatternlen(EN_Project *p, int index, int *len);
Expand Down Expand Up @@ -1236,11 +1264,6 @@ extern "C" {
int DLLEXPORT EN_deletenode(EN_Project *p, int nodeIndex);
int DLLEXPORT EN_deletelink(EN_Project *p, int linkIndex);






#if defined(__cplusplus)
}
#endif
Expand Down
4 changes: 4 additions & 0 deletions src/enumstxt.h
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,10 @@ char *PressUnitsTxt[] = {w_PSI,
w_KPA,
w_METERS};

char *DemandModelTxt[] = { w_DDA,
w_PDA,
NULL };

char *QualTxt[] = {w_NONE,
w_CHEM,
w_AGE,
Expand Down
Loading

0 comments on commit c4b7c90

Please sign in to comment.