A detailed description of .out data
Before you start this tour, you should load up a .out file using one of the buttons above. I recommend using the 'Load Default' button if this is your first time here. That will load up the data necessary to run the displays. The data being used in this tour is manufactured using EPA-SWMM, a phenomenal program for environmental systems. If you are here on a cellphone or tablet, try out the landscape mode and enjoy using the pinch and finger-drag effects, but definitely check out the mouseover and super-zoom wheel effect on desktops.
The units used in each of the displays is called a byte, and this number is helpful if you wish to understand how to access those values for display and analysis. This tour will take you through the addresses in each of the 7 major sections of a swmm .out file. The sections are as follows:
Each section starts with a button that will zoom your display to the section at hand, then a localized display of the binary section, a short description of the section, and finally a clickable 'Documentation' that contains the EPA-SWMM documentation for the section.
I hope you enjoy this as much as I do.
The first section describes a lot about how the file should be parsed and treated. This section includes the EPA-SWMM version number, the count of each reportable object, the units that data is reported in, and a special code to help with the basic assumption that the file you are working with is indeed an EPA-SWMM .out file.
The following basic information is written at the beginning of the binary output file produced by a SWMM 5 simulation:
Each of these values is written to the file as a 4-byte integer.
The Object ID Names section is helpful when presenting data in a user-friendly format. This section contains literally all of the strings used to describe the major objects of a model. While each of these object types is far more complex than needs to be detailed here, I've included a simple description of each object type for those following along:
Following the Opening Records section of SWMM 5's binary output file comes a section containing the ID names of each subcatchment, node, link, and pollutant defined in the SWMM 5 input file whose results are being reported. Pollutant concentration codes are also contained in this section of the file.
Each ID name consists of two records written to the output file:
The names are written first for each reported subcatchment, then for each reported node, then for each reported link, and finally for each pollutant. Within each category of object the names are written in the same order in which the object appeared in the input file. This same order is maintained when computed results are written to the file in the Computed Results section.
Following the listing of pollutant names, the code numbers that represent the concentration units of each pollutant are written to the file as 4-byte integers. These codes are: 0 for mg/L, 1 for ug/L, and 2 for counts/L.
To summarize, the overall layout of this section of the file is:
In the Object Properties section, you'll find a lot of information that describes the input to the model. This section is really helpful for independent display systems and set analysis. The input and output can be easily associated within this file when using this section.
Input to a swmm model is very easy to understand, with the subcatchments (plots of land) receiving an area, nodes being given elevations and depths, and links are recorded using lengths, depths, and elevation changes (offsets).
The Object Properties section of the binary output file produced by the SWMM 5 engine contains a limited collection of input properties associated with each object (not the entire set of properties). The format of this section is as follows:
| Item | Type | Description |
|---|---|---|
| Number of subcatchment properties saved | INT4 | Currently equal to 1 |
| Code number of each subcatchment property saved | INT4 | Currently equal to 1 for subcatchment area |
| Value of each property for each subcatchment | REAL4 | Subcatchment area (ac or ha) for each subcatchment |
| Number of node properties saved | INT4 | Currently equal to 3 |
| Code number of each node property saved | INT4 | Currently equal to:
|
| Value of each property for each node | REAL4 | Node type code, invert elevation (ft or m), and max. depth (ft. or m) for each node |
| Number of link properties saved | INT4 | Currently equal to 5 |
| Code number of each link property saved | INT4 | Currently equal to:
|
| Value of each property for each link | REAL4 | Link type code, upstream invert offset (ft or m), downstream invert offset (ft or m), max. depth (ft or m), and length (ft or m) for each link. |
This section, Reporting Variables, assigns to each of the output values an integer for all of the reported output. This includes variables such as snow depth, total inflow, and flooding volume. This section is just ever so slightly more interesting to a parser than it is to a person, but if you take a look at the 'Documentation' section, you'll see all the types of useful output data you can read from a .out file.
The Reporting Variables section of the SWMM 5 binary output file contains the number and codes of each variable reported on. The items written to this section, all as 4-byte integers, are as follows:
This section is incredibly small, and just describes the start date of the model, and the amount of time between reporting intervals. You will notice day 0 is December 30. This is due to the fact that not every great idea makes sense.
The Reporting Interval portion of the SWMM 5 binary output file consists of only two records:
This is the real meat of the file. In the 'Computed Results' section, you'll find the data data. This section contains a repeating pattern that starts with an 8-byte DateTime of the current timestep, followed by the output for each major object in the model. Each model object is identified by its array position in the objectIDs section, and each reported value is associated with its array position in the 'Reporting Variables' section.
Zooming in and out on this section is probably something I'll never get tired of.
The Computed Results portion of the SWMM 5 binary output file is where the computed values for each subcatchment, node, link and system reporting variable are stored for each reporting period of the simulation. The number and type of each reporting variable was supplied in the Reporting Variables portion of the file. The following information is written to the binary file for each reporting period, starting from the first period (the initial conditions at time 0 of the simulation do not appear in the file):
Note that the layout of these data is as follows:
The order in which each variable is written for a specific object follows the order in which the variables were listed in the Reporting Variables section of the file. The order in which each subcatchment, node, and link appear follows the same order in which they appear in the Object ID Names section of the file, and is the same order they appear in the SWMM 5 input file. Again remember that only a subset of all subcatchments, nodes, and links may be reported on, depending on the options that were specified in the [REPORT] section of the project's input file.
This collection of data is repeated for each reporting period. The actual number of reporting periods can be read from the Closing Records portion of the file.
The end of the file, 'Closing Records', wraps up the file with a tidy index, error code, and file verification number.
The following records are written to the SWMM 5 binary results file following the data that appear in the Computed Results section of the file:
Note that byte positions are expressed as offsets from the beginning of the file, whose byte position is 0.
Thanks so much for taking this quick tour of swmm binary .out files. The visualizations are made using d3, Bootstrap, and swmmjs. This webpage is hosted on AWS and utilizes a lightweight instance. If you had trouble loading the page, please give me a heads up and I'll see what I can do to help. I hope you've learned something, or at least had a little fun. Definitely find your way back again or contact me for more info.
If you are looking for a text file of the contents of the .out file, you can click the button below. Be aware, this will translate the entire contents of the .out binary into text, and probably be too much for a smaller computer to handle.