Welcome to swmmout’s Documentation¶
swmmout is a simple Python module which reads a SWMM out file. It should work on any version of Python >= 2.7, and can be downloaded from PyPI. The source code and issue tracker are on Bitbucket.
Introduction¶
The main function in this module is open
, which opens the file
specified in its argument and returns a OutFile
object which
can be used to query the file. It is important to note that the file
is kept open while the OutFile
object is in use, and destroying
the object will result in the file being closed. It can also be closed
forcibly using OutFile.close
, but this will make all subsequent
queries fail.
The main function of the OutFile
class is get_values
. This
takes five arguments as listed below:
Argument | Optional | Description |
---|---|---|
group | Required | One of ‘subcatchments’, ‘nodes’, ‘links’, ‘system’. This parameter specified which type of objects are to be queried. |
names | Optional | An optional list of names to report. If this is omitted, all names found in the specified group will be used. Any unrecognised names are ignored. |
variables | Optional | An optional list of variables to report. If this is omitted, all variables found in the specified group will be used. Any unrecognised variables are ignored. |
start | Optional | The start time of reporting. This should be a
datetime object. If it is missing or
earlier than the start time of the simulation,
that time is used instead. |
timesteps | Optional | The number of timesteps to report. If missing, then entire simulation period is returned. |
The variable names recognised are as listed below for each group. In addition, any pollutants specified in the model are recognised by prefixing them with ‘conc’. For example, if there is a pollutant called ‘TSS’, an acceptable variables name (for any group) will be ‘conc TSS’.
- subcatchments:
- ‘rainfall’
- ‘snow depth’
- ‘losses’
- ‘runoff’
- ‘groundwater flow’
- ‘groundwater elevation’
- nodes:
- ‘depth’
- ‘head’
- ‘storage’
- ‘lateral inflow’
- ‘total inflow’
- ‘flooding’
- links:
- ‘flow’
- ‘depth’
- ‘velocity’
- ‘Froude’
- ‘capacity’
- system:
- ‘temperature’
- ‘rainfall’
- ‘snow depth’
- ‘losses’
- ‘runoff’
- ‘dry weather inflow’
- ‘groundwater inflow’
- ‘RDII inflow’
- ‘direct inflow’
- ‘total inflow’
- ‘flooding’
- ‘outflow’
- ‘storage’
- ‘evaporation’
The return value is a list of tuples in the format
[(dateA, nameA, variableA1, variableA2, ...), (dateB, nameB, ...), ...]
This could be seen as a table with columns
Date, Name, Variable1, Variable2, etc
Example¶
The following example script shows how to extract selected node information into a csv file:
import csv
import swmmout
# Open the file
outfile = swmmout.open('swmmrun.out')
# Extract some information
query_nodes = ['J1', 'J2', 'J3']
query_vars = ['depth', 'total inflow']
data = outfile.get_values('nodes', query_nodes, query_vars)
# Create a csv file
with csvfile = open('output.csv', 'w'):
csvwriter = csv.writer(csvfile)
csvwriter.writerows(data)
API¶
-
class
swmmout.
OutFile
(fh)¶ Provide and interface to a SWMM .out file.
The
OutFile
class has methods and properties to allow querying data in a binary SWMM .out file. A typical way of using this by specifying an open file in the constructor, and usingget_values
to query data. For example:>>> import io >>> swmmfile = io.BytesIO(_test_data) >>> outfile = OutFile(swmmfile) >>> outfile.names['nodes'] ('J13', 'J16', 'J12', 'J11', 'J15', 'J14', 'J10', 'J9', 'J7', 'J8', 'J4', 'J3', 'J2', 'J1', 'C8H036', 'Outfall', 'Saulspoort') >>> outfile.variables['nodes'][0] 'depth' >>> outfile.start datetime.datetime(2005, 1, 29, 0, 0) >>> outfile.get_values('nodes', ['J13', 'J15'], ['depth'], timesteps=3) [(datetime.datetime(2005, 1, 29, 3, 0), ('J13', 0.0), ('J15', 0.0)), (datetime.datetime(2005, 1, 29, 6, 0), ('J13', 0.0), ('J15', 0.0)), (datetime.datetime(2005, 1, 29, 9, 0), ('J13', 0.0), ('J15', 0.0))]
-
get_values
(group, names=None, variables=None, start=None, timesteps=None)¶ Return a list filtered list of values. Output is as a list of tuples in the following format: (datetime, name, variable1, variable2, ...) The list is filtered so that only dates between start and end (inclusive) are in the output.
group is one of ‘subcatchments’, ‘nodes’, ‘links’ or ‘system’
-
close
()¶ Close the file.
-