Water Modeling Hub: Expert Insights on SWMM5, ICM SWMM, InfoSewer, InfoSWMM: SWMM5 funcs.h Summary

Saturday, December 28, 2024

SWMM5 funcs.h Summary

Below is a step-by-step explanation of funcs.h, a header file for EPA SWMM 5.2 that collects all global function prototypes used across the SWMM source code. It is primarily a forward declaration file: each group of functions deals with a specific module (e.g., project setup, input reading, reporting, climate, runoff, routing, etc.). By centralizing these prototypes, SWMM ensures that different source files can call each other's routines consistently.

1. Guard Macros

#ifndef FUNCS_H
#define FUNCS_H

#ifndef FUNCS_H / #define FUNCS_H: a typical include guard that prevents multiple redefinitions if funcs.h is included in multiple source files.

2. File Organization

The file is divided into sections by comment blocks, each grouping function prototypes by subsystem or module. For example:

Project Methods
Input Reader Methods
Report Writer Methods
Temperature/Evaporation
Rainfall Processing
Snowmelt Processing
Runoff Analyzer
Conveyance System Routing
Output Filer
Groundwater
RDII (Rainfall‐Derived Infiltration/Inflow)
Landuse
Flow/Quality Routing
Treatment
Mass Balance
Simulation Statistics
Raingage
Subcatchment
Surface Pollutant
Node
Inflow
Routing Interface File
Hot Start File
Link
Link Cross‐Section
Culvert/Roadway
Force Main
Transect
Street
Custom Shape
Control Rule
Table & Time Series
Utility

Each grouping matches a piece of SWMM’s domain logic.

3. Project Methods

void project_open(const char *f1, const char *f2, const char *f3);
void project_close(void);

void project_readInput(void);
...

Functions for opening or closing an SWMM “project,” reading input data, validating the project’s consistency, creating/finding objects, allocating or freeing memory matrices, etc.

4. Input Reader Methods

int input_countObjects(void);
int input_readData(void);

input_countObjects(): scans the input file to count how many objects (nodes, links, etc.) are present.
input_readData(): actually reads the data from the input file (like .inp file lines) and populates SWMM data structures.

5. Report Writer Methods

void report_writeLine(const char* line);
void report_writeSysTime(void);
void report_writeLogo(void);
...
void report_writeErrorMsg(int code, char* msg);
...

Functions to generate or format textual output for SWMM’s report file (the .rpt file). They might write lines of text, system times, warnings/errors, or final summary tables (rain stats, RDII stats, flow error, etc.).

6. Temperature/Evaporation Methods

int climate_readParams(char* tok[], int ntoks);
...
DateTime climate_getNextEvapDate(void);

Used to handle climate data (temps, evaporation) from user input.
Might open an external climate file, parse monthly or time-series data, store and retrieve daily evaporation rates, or track next date/time evaporation changes.

7. Rainfall Processing Methods

void rain_open(void);
void rain_close(void);

Opens/closes or sets up SWMM’s internal rainfall processing system. Could handle interface files or time-series for each gage.

8. Snowmelt Processing Methods

int snow_readMeltParams(char* tok[], int ntoks);
...
double snow_getSnowMelt(int subcatch, double rainfall, double snowfall,
    double tStep, double netPrecip[]);

SWMM can model snow accumulation and melt. These functions read snowmelt parameters, track and update snowpack states, and compute daily melt rates or infiltration from snow cover.

9. Runoff Analyzer Methods

int runoff_open(void);
void runoff_execute(void);
void runoff_close(void);

These handle the runoff portion of SWMM, including subcatchment runoff simulation.
runoff_execute() typically runs an iteration or loop over all subcatchments, computing runoff flows.

10. Conveyance System Routing Methods

int routing_open(void);
double routing_getRoutingStep(int routingModel, double fixedStep);
void routing_execute(int routingModel, double routingStep);
void routing_close(int routingModel);

For the hydraulic part of SWMM (i.e., flow routing).
If the model chooses a certain routing method (steady flow, kinematic wave, dynamic wave), these calls handle the next time step’s flow updates.

11. Output Filer Methods

int  output_open(void);
void output_end(void);
void output_close(void);
void output_saveResults(double reportTime);

Manage the binary output file that SWMM can produce, storing results at each reporting time step.
Reading/writing times, subcatch/node/link results, etc.

12. Groundwater Methods

int  gwater_readAquiferParams(int aquifer, char* tok[], int ntoks);
...
double gwater_getVolume(int subcatch);

SWMM can model groundwater infiltration from aquifers.
Functions for reading aquifer and groundwater parameters, computing infiltration at each step, etc.

13. RDII Methods

int  rdii_readRdiiInflow(char* tok[], int ntoks);
...
void rdii_getRdiiFlow(int index, int* node, double* q);

Rainfall‐Derived Infiltration/Inflow (RDII) computations.
Reading parameters, storing them, then retrieving infiltration flows for a node.

14. Landuse Methods

int landuse_readParams(int landuse, char* tok[], int ntoks);
...
double landuse_getWashoffLoad(int landuse, int p, double area,
    TLandFactor landFactor[], double runoff, double vOutflow);

SWMM’s built‐in pollutant buildup and washoff logic.
Tracks pollutant accumulation on land surfaces and their removal in runoff events.

15. Flow/Quality Routing Methods

void flowrout_init(int routingModel);
void flowrout_close(int routingModel);
double flowrout_getRoutingStep(int routingModel, double fixedStep);
int flowrout_execute(int links[], int routingModel, double tStep);
...

More detailed hydraulic and quality routing.
Possibly references submodules for dynamic wave, kin. wave, etc.

16. Treatment Methods

int  treatmnt_open(void);
...
void treatmnt_treat(int node, double q, double v, double tStep);

Allows user-specified treatment functions at nodes.
For instance, a node might have a formula describing how pollutants are removed from inflow.

17. Mass Balance Methods

int  massbal_open(void);
void massbal_close(void);
void massbal_report(void);
...
double massbal_getFlowError(void);

SWMM tracks water volume and pollutant mass to ensure there’s no large “missing” or “created” mass.
These methods update mass balance each time step, final error reporting, etc.

18. Simulation Statistics Methods

int  stats_open(void);
void stats_close(void);
void stats_report(void);
...
void stats_updateFlowStats(double tStep, DateTime aDate);

Summaries of flow, depth, infiltration, flooding, etc., plus tracking maximum node depths or maximum flows.
Writes out final stats in the .rpt file.

19. Raingage Methods

int      gage_readParams(int gage, char* tok[], int ntoks);
...
void     gage_updatePastRain(int j, int tStep);
double   gage_getPastRain(int gage, int hrs);

Each rain gage object can store time‐series or interface file rainfall data.
gage_updatePastRain(...) helps track past rainfall totals for certain hours (like 24‐hr accumulations).

20. Subcatchment Methods

int   subcatch_readParams(int subcatch, char* tok[], int ntoks);
...
void  subcatch_getRunon(int subcatch);
double subcatch_getRunoff(int subcatch, double tStep);

Subcatchment infiltration, runoff generation.
subcatch_getRunoff(...) is where the subcatch’s infiltration and runoff are computed each time step.

21. Surface Pollutant Buildup/Washoff Methods

void surfqual_initState(int subcatch);
...
void surfqual_getWashoff(int subcatch, double runoff, double tStep);

Ties into the landuse module.
Tracks how pollutants accumulate on the surface and are removed by runoff.

22. Conveyance System Node Methods

int   node_readParams(int node, int type, int subIndex, char* tok[], int ntoks);
...
double node_getSurfArea(int node, double depth);

For SWMM’s network nodes.
node_* routines handle node geometry, inflows, computing overflow, surface area for ponding, etc.

23. Conveyance System Inflow Methods

int  inflow_readExtInflow(char* tok[], int ntoks);
...
double inflow_getExtInflow(TExtInflow* inflow, DateTime aDate);

Deals with external inflows or dry-weather flows assigned to nodes.
E.g., reading from user input or time series.

24. Routing Interface File Methods

int iface_readFileParams(char* tok[], int ntoks);
...
double iface_getIfaceQual(int index, int pollut);

If SWMM uses routing interface files to pass flows/quality between sub-systems, these handle that data.

25. Hot Start File Methods

int hotstart_open(void);
...
void hotstart_close(void);

SWMM can save or read a hotstart (internal state file) to skip spin‐up on re‐runs.

26. Conveyance System Link Methods

int link_readParams(int link, int type, int subIndex, char* tok[], int ntoks);
...
double link_getLossRate(int link, int routeModel, double q, double tstep);

For pipes, pumps, weirs, or outlets.
Reading link geometry, computing flows, infiltration or evaporation loss from pipes, etc.

27. Link Cross-Section Methods

int   xsect_isOpen(int type);
...
double xsect_getAofY(TXsect* xsect, double y);

For specialized cross‐section geometry calculations: area, radius, top width, etc., given a water depth y.

28. Culvert/Roadway Methods

double culvert_getInflow(int link, double q, double h);
double roadway_getInflow(int link, double dir, double hcrest, double h1, double h2);

SWMM can model culverts or roadway overflows.
These functions compute how much flow can pass given heads and crest geometry.

29. Force Main Methods

double forcemain_getEquivN(int j, int k);
double forcemain_getFricSlope(int j, double v, double hrad);

For pressurized pipes using Hazen-Williams or Darcy-Weisbach equations.

30. Cross-Section Transect Methods

int    transect_create(int n);
void   transect_delete(void);
int    transect_readParams(int* count, char* tok[], int ntoks);

For irregular channel cross-sections described by transect data.

31. Street Cross-Section Methods

int street_create(int nStreets);
int street_readParams(char* tok[], int ntoks);

SWMM 5.2 can model streets as separate cross-sections, used with inlet node logic.

32. Custom Shape Cross-Section Methods

int shape_validate(TShape *shape, TTable *curve);

For user-defined cross‐section shapes (like a parametric shape plus a curve describing geometry).

33. Control Rule Methods

int controls_create(int n);
...
int controls_evaluate(DateTime currentTime, DateTime elapsedTime, double tStep);

SWMM’s rule-based controls to adjust link settings (like orifices or pumps) based on conditions.
E.g., “IF Node depth > 5 THEN Pump = ON.”

34. Table & Time Series Methods

int  table_readCurve(char* tok[], int ntoks);
...
double table_tseriesLookup(TTable* table, double t, char extend);

For look‐up tables (like rating curves) or time series that SWMM uses in many contexts.
Insert, validate, search by interpolation, etc.

35. Utility Methods

double UCF(int quantity);
...
int findmatch(char *s, char *keyword[]);
int match(char *str, char *substr);
...
DateTime getDateTime(double elapsedMsec);
...
char* addAbsolutePath(char *fname);

Various helper routines:
- UCF(...): unit conversion factors for different quantities.
- getInt/getFloat/getDouble(...): parse numeric from strings.
- findmatch(...), match(...): compare strings to a list of keywords.
- addAbsolutePath(...): prefix a filename with the application’s directory.

36. Summary

In short, funcs.h is a master header:

Declares function prototypes from various SWMM modules (subcatchment, node, routing, infiltration, etc.).
Ensures consistent linkage across multiple .c files.
Allows large pieces of code to remain in separate C source modules, referencing each other via a single header of forward declarations.

It covers all major processes: project reading/validation, runoff & routing computations, pollutant buildup/washoff, mass balance tracking, reporting, time‐series/table lookups, and so forth—the entire scope of SWMM’s architecture.