A Roadmap to the SWMM 5 Engine Source Code
==========================================

The SWMM 5 computational engine consists of 51 C-code files plus several
header files that are compiled into a Dynamic Link Library (DLL) under Windows.

The following header files contain definitions that are used throughout the
code and should be consulted if the meaning of a variable, a data structure,
or a constant is unclear:

enums.h       defines various enumerated (symbolic) constants.

objects.h     defines the major classes of data objects used by SWMM 5.

consts.h      defines useful numerical constants.

text.h        defines various text strings used throughout the code.

macros.h      defines several macros used throughout the code.

globals.h     declares global variables that are referenced in many
              SWMM 5 code modules.

funcs.h       contains prototypes of functions that can be called from any
              module of SWMM 5 that #includes funcs.h.

swmm5.h       contains protoypes of SWMM's API functions that can be called
              by external programs to run simulations.

--------------------------------------------------------------------------

The following modules form the main core of the SWMM 5 engine:

swmm5.c       contains functions that comprise SWMM's API used to run the
              engine from other programs.

project.c     contains functions that create and destroy all project data,
              establish default values, and look up objects by ID name.

input.c       reads a project's data from an input file.

runoff.c      computes runoff quantity and quality from the project's
              subcatchments.

routing.c     routes runoff and external inflows through the project's
              drainage system network of nodes and links.

massbal.c     performs mass balance calculations for runoff and routing.

stats.c       collects summary statistics on flow rates, water depths,
              solution iterations, and variable time steps for a
	      simulation.

statsrpt.c    writes summary simulation results to the status report file.

output.c      writes/reads runoff and routing results at fixed reporting
              intervals to/from a binary output file.

report.c      writes mass balance results and tables of complete time series
              results for specific project elements to the status report file.

inputrpt.c    writes a summary of a project's input data to the status report
              file.

-------------------------------------------------------------------------------

The following collection of modules are used to perform runoff calculations:

rain.c        places data from external rainfall files into a single rainfall
              interface file.

gage.c        provides rainfall data, either from an interface file or from an
              internal time series, for runoff calculations.

climate.c     provides temperature, evaporation, and wind speed data to the
              simulation.

snow.c        computes snow fall accumulation, snow removal operations, and
              snow melt for a project's subcatchments.

infil.c       performs infiltration calculations on a project's subcatchments.

gwater.c      computes groundwater fluxes and updates groundwater depths over
              the project's study area.

subcatch.c    computes rainfall runoff from individual subcatchments.

surfqual.c    computes pollutant buildup, washoff, and street sweeping over
              individual subcatchments.

landuse.c     evaluates pollutant buildup and washoff functions for a project's
              various types of land uses.

lid.c         evaluates the hydrologic performance of Low Impact Development
              practices utilized within subcatchment areas.              

lidproc.c     computes the hydrologic performance of individual LID units.

-------------------------------------------------------------------------------

These modules are used for flow and water quality routing:

flowrout.c     implements top-level control of flow routing through a project's
               drainage network.

inflow.c       provides direct time series inflows and recurring dry weather
               inflows to the drainage system's nodes at each step of the
	       simulation.

rdii.c         computes rainfall dependent infiltration/inflow at selected nodes
               of the drainage network.

kinwave.c      performs kinematic wave flow routing calculations at each time
               step of the simulation.

dynwave.c      performs dynamic wave flow routing calculations at each time
               step of the simulation

dwflow.c       solves the dynamic wave flow continuity and momentum equations in
               a single conduit over a single time step.

controls.c     implements rule-based control actions on pumps and regulators
               as the simulation unfolds.

qualrout.c     performs routing of water quality constituents through the
               study area's drainage system.

treatmnt.c     computes pollutant removal at specific nodes of the drainage
               system where user-defined treatment functions have been
	       assigned.

node.c         contains functions used to compute the properties and behavior
               of the drainage system's nodes which include junctions, flow
               dividers, storage units, and outfalls.

link.c         contains functions used to compute the properties and behavior
               of the drainage system's links which include conduits, pumps,
               orifices, weirs, and outlets.

forcmain.c     computes friction losses in force mains that use either the
               Hazen-Williams or Darcy-Weisbach equations in place of the
               Manning equation for pressurized flow.

culvert.c      computes flow reduction in culvert-type conduits due to
               inlet control using the FHWA HDS-5 methodology.

roadway.c      computes flow overtopping a roadway using the FWHA HDS-5
               methodology.

exfil.c        computes exfiltration from beneath storage units.

-------------------------------------------------------------------------------

The following modules provide various support functions for SWMM 5:

datetime.c     functions for manipulating dates and times.

error.c        error reporting functions.

findroot.c     equation root finding functions.

hash.c         functions that implement hash tables for fast object retrieval.

hotstart.c     saves or reads the state of the drainage system to or from a
               hot start file.

iface.c        functions for reading from and writing to routing interface
               files.

keywords.c     defines lists of keywords that appear as part of a SWMM 5
               input file.

mathexpr.c     functions that parse and evaluate user-supplied mathematical
               expressions for pollutant removal at treatment nodes and for
               groundwater outflow from subcatchments.

mempool.c      functions that provide a memory pool used to store object
               ID names.

odesolve.c     implementation of a fifth-order Runge-Kutta ordinary
               differential equation solver.

shape.c        functions that compute the geometric cross-section properties
               of closed conduits with user-defined shapes.

table.c        functions used for accessing lookup tables that contain
               SWMM 5's curve data and time series data.

toposort.c     functions used to topologically sort the links of a drainage
               network and detect any closed cyclic loops.

transect.c     functions that create geometric tables for irregular shaped
               cross section transects.

xsect.c        functions that compute geometric properties of conduit cross
               sections.
             