SWMM5 swmm5.c Summary

 The swmm5.c file is the core computational engine for the U.S. Environmental Protection Agency's Storm Water Management Model (SWMM). This file coordinates the flow of calculations throughout the simulation, calling other modules for tasks like runoff analysis, routing, and water quality computations. It handles input and output files, manages global state variables, processes each simulation step, and interacts with exception handling if errors arise.

Key Functions in swmm5.c

1. swmm_run:

   • This is the entry point for running the simulation. It takes input, report, and output file names as arguments, opens the project, and calls the necessary functions to execute the simulation and save the results.

2. swmm_open:

   • This function opens a project by reading the input data and initializing necessary structures. It processes the input file, performs initial validation, and prepares for simulation.

3. swmm_start:

   • Starts the simulation by initializing all components (e.g., rainfall, routing, statistics) and setting up the necessary conditions. It also handles simulation setup like writing options and warnings.

4. swmm_step:

   • Advances the simulation by one routing time step. It handles the calculation of runoff, routing, and water quality for the current time step and updates the elapsed time.

5. swmm_stride:

   • Advances the simulation by a fixed number of seconds. This function is useful for simulations where time steps need to be manually specified or adjusted.

6. execRouting:

   • This function is responsible for routing water and pollutants through the drainage system, which includes computing runoff and performing necessary flow routing.

7. saveResults:

   • Saves the results of the simulation to the output file, either as averages or raw values, depending on the user’s configuration.

8. swmm_end:

   • Ends the simulation by performing necessary cleanup tasks, including closing output files, reporting results, and releasing resources.

9. swmm_report:

   • Generates a report of the simulation results.

10. swmm_getMassBalErr:

    • Retrieves the mass balance errors (e.g., runoff, flow, and quality errors) of the simulation.

11. swmm_getVersion:

    • Returns the version number of the SWMM engine.

12. swmm_getError:

    • Retrieves the error message and code of the last exception that occurred during the simulation.

13. swmm_getWarnings:

    • Retrieves the number of warning messages that were issued during the simulation.

Exception Handling:

• The file also includes support for exception handling through the EXH macro. This handles errors like memory access violations, floating-point errors, and other exceptions that may occur during simulation.
• The xfilter function handles filtering and reporting of these exceptions, making sure the user is informed if any critical errors occur.

Simulation Flow:

1. Input Reading: The swmm_open function opens the input files and reads the project data.
2. Initialization: The swmm_start function initializes the simulation parameters and sets up the various computational models (e.g., rainfall, routing, quality).
3. Simulation Steps: The simulation progresses step-by-step, with each step handled by swmm_step, which computes the required water flow and quality for that step.
4. Reporting: The results are either written immediately or stored for later use, depending on the user's settings.
5. Simulation Termination: Once the simulation is complete, swmm_end cleans up the resources and generates the final reports.

API Functions:

• swmm_run: Runs the entire simulation based on input and output file paths.
• swmm_getVersion: Retrieves the version number of the SWMM engine.
• swmm_getError: Retrieves any error messages during the simulation.
• swmm_getWarnings: Retrieves warnings issued during the simulation.
• swmm_report: Writes the results to the report file.

Error Handling:

• SWMM uses a global ErrorCode variable to track errors. If an error occurs, the simulation stops, and the error message is written to the report.
• Warnings are tracked separately in the Warnings variable, and users can retrieve them using the swmm_getWarnings function.

File Management:

• swmm_open and swmm_close handle the opening and closing of project files. This includes input files (e.g., project definition, data files) and output files (e.g., report, result files).

Report Generation:

• swmm_report generates a summary of the simulation, including runoff statistics, flow routing, and water quality results. This is useful for reviewing simulation performance and results.

Summary:

The swmm5.c file plays a central role in controlling the simulation process for the EPA's SWMM model. It coordinates input reading, simulation execution, and output generation while handling exceptions and ensuring that the simulation runs smoothly. The modular design allows for flexible simulation of hydrological processes and easy integration of new features or updates.