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

The SWMM 5 computational engine consists of 49 C-code files plus several
header files. The engine can be compiled either as a Dynamic Link Library
(DLL) under Windows or as a stand-alone console application under both
Windows and Linux, depending on which of the #define DLL and #define CLE
declarations at the top of swmm5.c is commented out.

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.

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

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

swmm5.c       contains functions that provide supervisory control over the
              program.

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 a status report.

output.c      writes/reads runoff and routing results to/from a binary
              output file.

report.c      prepares a status report of simulation results and, for the
              command line version of SWMM 5, reports complete results for
	      selected subcatchments, nodes, and links.

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

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

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, pollutant buildup and 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 equations from the FHWA HEC-5 circular.

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

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.

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.
             