API Reference#

This page is generated from the Cython type-stub files (.pyi) so signatures and docstrings are always in sync with the compiled extensions. Each entry below lists the public class for the module; private helpers prefixed with _ are intentionally hidden.

For task-oriented documentation see the User Guide.

openswmm#

The top-level package. Importing openswmm configures the platform-specific shared-library search path and re-exports the legacy SWMM 5 symbols for backward compatibility.

openswmm – Python bindings for the OpenSWMM stormwater modelling engine.

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Subpackages#

legacy.engine

Legacy EPA SWMM 5.x solver bindings (Cython).

legacy.output

Legacy EPA SWMM 5.x binary output reader (Cython).

engine

New data-oriented engine 6.x bindings (Cython).

This top-level package additionally:

  • Configures the platform-specific shared-library search path so the bundled C/C++ shared libraries can be located by the dynamic linker.

  • Resolves the package version string into __version__.

  • Re-exports the legacy engine and legacy output public symbols when their compiled Cython extensions are available, for backward compatibility with pre-6.x callers.

OpenSWMM 6 — refactored engine#

The openswmm.engine subpackage exposes the new, refactored OpenSWMM 6 engine — the recommended API for all new work.

All domain access is class-based: each class takes an active Solver in its constructor and may only be called when the solver is in an appropriate EngineState.

See also

OpenSWMM 6 User Guide (refactored engine) — task-oriented user guide for this engine.

openswmm.engine#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Cython bindings for the OpenSWMM Engine 6.0 C API.

The package is split by domain to mirror the C header organisation:

Table 1 Module Map#

Python class

C header

Contents

Solver

openswmm_engine.h

Engine lifecycle, timing, error reporting

ModelBuilder

openswmm_model.h

Programmatic model construction

ModelEditor

openswmm_edit.h

In-place model editing (delete + type conversion)

Nodes

openswmm_nodes.h

Node get/set, lateral inflow, bulk arrays

Links

openswmm_links.h

Link get/set, control settings, bulk arrays

Subcatchments

openswmm_subcatchments.h

Subcatchment runoff, rainfall override

Gages

openswmm_gages.h

Rain gage rainfall get/set

HotStart

openswmm_hotstart.h

Hot start save/open/apply/close

MassBalance

openswmm_massbalance.h

Continuity error queries

Statistics

openswmm_statistics.h

Cumulative simulation statistics

OutputReader

openswmm_output.h

Binary output file reader

Pollutants

openswmm_pollutants.h

Pollutant management and quality injection

Quality

openswmm_quality.h

Landuse, buildup, washoff, treatment

Tables

openswmm_tables.h

Time series, curves, patterns

Inflows

openswmm_inflows.h

External inflows, DWF, RDII

Controls

openswmm_controls.h

Control rules and direct actions

Forcing

openswmm_forcing.h

Advanced runtime forcing (mode + persistence)

Infrastructure

openswmm_infrastructure.h

Transects, streets, inlets, LIDs

Spatial

openswmm_spatial.h

Coordinates, CRS, vertices, polygons

Surface2D

openswmm_2d.h

2D surface mesh / coupled overland flow

GeoPackage (Optional)

openswmm_geopackage.h

GeoPackage import/export (requires OPENSWMM_WITH_GEOPACKAGE build)

Quick start#

from openswmm.engine import Solver, Nodes, Links

with Solver("model.inp", "model.rpt", "model.out") as s:
    nodes = Nodes(s)
    links = Links(s)
    while s.state == EngineState.RUNNING:
        if s.step() != 0:
            break
        depths = nodes.get_depths_bulk()  # numpy array
        flows  = links.get_flows_bulk()   # numpy array

Programmatic model building#

from openswmm.engine import ModelBuilder, NodeType, LinkType, XSectShape

m = ModelBuilder()
m.add_node("J1", NodeType.JUNCTION)
m.add_node("OUT1", NodeType.OUTFALL)
m.add_link("C1", LinkType.CONDUIT)
m.set_link_nodes(0, 0, 1)
m.set_link_length(0, 300.0)
m.set_link_roughness(0, 0.013)
m.set_link_xsect(0, XSectShape.CIRCULAR, 1.0)
m.validate()
m.finalize()

solver = m.to_solver()
solver.start()
while solver.state == EngineState.RUNNING:
    if solver.step() != 0:
        break
    pass
solver.end()
solver.destroy()

Advanced forcing#

from openswmm.engine import Solver, Nodes, Forcing, ForcingMode

with Solver("model.inp", "model.rpt", "model.out") as s:
    nodes   = Nodes(s)
    forcing = Forcing(s)

    j1 = nodes.get_index("J1")
    forcing.node_lat_inflow(j1, 1.5, ForcingMode.REPLACE, persist=True)

    while s.state == EngineState.RUNNING:
        if s.step() != 0:
            break
        pass

    forcing.clear_all()

Solver lifecycle#

Engine Lifecycle (Pythonic v1 surface)#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._solver.

class Event(start, end)#

Bases: NamedTuple

Create new instance of Event(start, end)

Parameters:
end: datetime#

Alias for field number 1

start: datetime#

Alias for field number 0

class EventsView(solver)#

Bases: MutableSequence[Event]

[EVENTS] block as a MutableSequence. See Solver.events.

Parameters:

solver (Solver)

append(value)#

S.append(value) – append value to the end of the sequence

Parameters:

value (Any)

Return type:

None

clear() → None -- remove all items from S#
Return type:

None

insert(idx, value)#

S.insert(index, value) – insert value before index

Parameters:
Return type:

None

class SimulationOptions(solver)#

Bases: MutableMapping[str, str]

View over the [OPTIONS] block. See Solver.options.

Parameters:

solver (Solver)

property crs: str#
property end_datetime: datetime#
property report_start_datetime: datetime#
property routing_step: timedelta#
property start_datetime: datetime#
ext: _OptionsExtView#
class Solver(inp='', rpt=None, out=None, *, plugin_lib=None)#

Bases: object

SWMM engine lifecycle manager.

Accepts str or pathlib.Path for every file argument.

from datetime import timedelta
from openswmm.engine import Solver

with Solver("model.inp", "model.rpt", "model.out") as s:
    for elapsed in s.steps():
        if elapsed >= timedelta(hours=24):
            break
Parameters:

  • inp (_PathLike)

  • rpt (Optional[_PathLike])

  • out (Optional[_PathLike])

  • plugin_lib (Optional[_PathLike])

close()#
Return type:

None

close_runoff_interface()#
Return type:

None

property controls: Controls#
create()#
Return type:

None

property crs: str#
property current_datetime: datetime#
destroy()#
Return type:

None

property editor: ModelEditor#
property elapsed: timedelta#
end()#
Return type:

None

property end_datetime: datetime#
property events: EventsView#
property forcing: Forcing#
property gages: Gages#
property generation: int#
property handle: int#
property inflows: Inflows#
property infrastructure: Infrastructure#
initialize()#
Return type:

None

property is_between_events: bool#
property mass_balance: MassBalance#
property nodes: Nodes#
open(plugin_lib=None)#
Parameters:

plugin_lib (str | PathLike[str] | None)

Return type:

None

open_runoff_interface_read(path)#
Parameters:

path (str | PathLike[str])

Return type:

None

open_runoff_interface_write(path)#
Parameters:

path (str | PathLike[str])

Return type:

None

property options: SimulationOptions#
property patterns: Patterns#
property pollutants: Pollutants#
property quality: Quality#
read_runoff_step()#
Return type:

bool

report()#
Return type:

None

property report_start_datetime: datetime#
property routing_step: timedelta#
run()#
Return type:

None

save_runoff_step(dt)#
Parameters:

dt (timedelta | float)

Return type:

None

property save_schedule: SaveSchedule#
set_step_begin_callback(callback)#
Parameters:

callback (Callable[[float, float], None] | None)

Return type:

None

set_step_end_callback(callback)#
Parameters:

callback (Callable[[float, float], None] | None)

Return type:

None

set_warning_callback(callback)#
Parameters:

callback (Callable[[int, str], None] | None)

Return type:

None

property spatial: Spatial#
start(save_results=True)#
Parameters:

save_results (bool)

Return type:

None

property start_datetime: datetime#
property state: EngineState#
property statistics: Statistics#
property steady_state_skip: bool#
step()#
Return type:

timedelta

steps()#
Return type:

Iterator[timedelta]

stride(n_steps)#
Parameters:

n_steps (int)

Return type:

timedelta

property subcatchments: Subcatchments#
property tables: Tables#
until(target)#
Parameters:

target (datetime | timedelta)

Return type:

timedelta

property userflags: UserFlags#
write(path)#
Parameters:

path (str | PathLike[str])

Return type:

None

class UserFlags(solver)#

Bases: MutableMapping[str, bool | int | float]

Typed user-flag mapping. See Solver.userflags.

Parameters:

solver (Solver)

run(inp, rpt=None, out=None, *, plugin_lib=None)#

Run a SWMM simulation start-to-finish. Raises EngineError on failure.

Parameters:
Return type:

None

run_with_callback(inp, rpt=None, out=None, callback=None, *, plugin_lib=None)#

Run a SWMM simulation with an optional progress callback. Raises EngineError on failure.

Parameters:
Return type:

None

Exceptions#

The EngineError hierarchy and the dispatch helper used by _check(). Each subclass also inherits from a standard-library exception so idiomatic except IndexError: / except ValueError: handlers do the right thing.

Type stubs for openswmm.engine._exceptions.

exception BadHandleError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception BadIndexError(code, message=Ellipsis)#

Bases: EngineError, IndexError

Parameters:
Return type:

None

exception BadParamError(code, message=Ellipsis)#

Bases: EngineError, ValueError

Parameters:
Return type:

None

exception CRSError(code, message=Ellipsis)#

Bases: EngineError, ValueError

Parameters:
Return type:

None

exception DependencyError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception EngineError(code, message=Ellipsis)#

Bases: Exception

Parameters:
Return type:

None

code: int#
code_enum: ErrorCode#
message: str#
exception FileError(code, message=Ellipsis)#

Bases: EngineError, OSError

Parameters:
Return type:

None

exception HotStartError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception LifecycleError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception NumericalError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception ParseError(code, message=Ellipsis)#

Bases: EngineError, ValueError

Parameters:
Return type:

None

exception PluginError(code, message=Ellipsis)#

Bases: EngineError, RuntimeError

Parameters:
Return type:

None

exception StaleObjectError(message=Ellipsis)#

Bases: LifecycleError

Parameters:

message (str)

Return type:

None

raise_for_code(code, message=Ellipsis)#
Parameters:

  • code (int)

  • message (str | None)

Return type:

None

DateTime conversion#

The low-level C API encode/decode primitives plus the high-level oadate_to_datetime / datetime_to_oadate helpers used throughout the bindings.

Type stubs for openswmm.engine._datetime.

Low-level Python bindings around the SWMM DateTime conversion C API declared in openswmm_datetime.h. SWMM’s native DateTime is a double whose integer part is days since 1899-12-30 and fractional part is the time-of-day fraction.

add_seconds(value, seconds)#
Parameters:
Return type:

float

decode_date(value)#
Parameters:

value (float)

Return type:

tuple[int, int, int]

decode_time(value)#
Parameters:

value (float)

Return type:

tuple[int, int, int]

encode_date(year, month, day)#
Parameters:
Return type:

float

encode_time(hour, minute, second)#
Parameters:
Return type:

float

time_diff(value1, value2)#
Parameters:
Return type:

int

Type stubs for openswmm.engine._dates.

High-level helpers that convert between SWMM’s native DateTime double (decimal days since 1899-12-30) and datetime.datetime. The calendar arithmetic is delegated to the C API in openswmm_datetime.h.

datetime_to_oadate(dt)#
Parameters:

dt (datetime)

Return type:

float

oadate_to_datetime(value)#
Parameters:

value (float)

Return type:

datetime

Model construction#

Programmatic Model Building#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._model.

The ModelBuilder class creates a SWMM model entirely through the API without requiring a .inp file.

class ModelBuilder#

Bases: object

Build a SWMM model programmatically (no .inp file).

The engine starts in BUILDING state. Use add_node, add_link, etc. to populate the model, then call finalize to transition to INITIALIZED.

Note

The ModelBuilder owns its engine handle until to_solver is called; the resulting Solver then takes ownership.

Example:

m = ModelBuilder()
m.add_node("J1", 0)       # JUNCTION
m.add_node("OUT1", 1)     # OUTFALL
m.add_link("C1", 0)       # CONDUIT
m.set_link_nodes(0, 0, 1)
m.set_link_length(0, 300.0)
m.set_link_roughness(0, 0.013)
m.validate()
m.finalize()
solver = m.to_solver()
add_gage(gage_id)#

Add a rain gage to the model.

Parameters:

gage_id (str) – Unique gage identifier.

Returns:

Error code (0 on success).

Return type:

int

Add a link to the model.

Valid in BUILDING or OPENED state.

Parameters:

  • link_id (str) – Unique link identifier.

  • link_type (int) – Link type code (0=CONDUIT, 1=PUMP, 2=ORIFICE, 3=WEIR, 4=OUTLET).

Returns:

Error code (0 on success).

Return type:

int

@see: L{openswmm.engine.LinkType}

add_node(node_id, node_type)#

Add a node to the model.

Valid in BUILDING or OPENED state.

Parameters:

  • node_id (str) – Unique node identifier.

  • node_type (int) – Node type code (0=JUNCTION, 1=OUTFALL, 2=STORAGE, 3=DIVIDER).

Returns:

Error code (0 on success).

Return type:

int

@see: L{openswmm.engine.NodeType}

add_subcatch(sc_id)#

Backward-compatible alias for add_subcatchment.

Parameters:

sc_id (str) – Unique subcatchment identifier.

Returns:

Error code (0 on success).

Return type:

int

add_subcatchment(sc_id)#

Add a subcatchment to the model.

Parameters:

sc_id (str) – Unique subcatchment identifier.

Returns:

Error code (0 on success).

Return type:

int

add_title_line(line)#

Append a new line to the [TITLE] section.

Raises:

EngineError – On C API failure.

Parameters:

line (str)

Return type:

None

clear_title()#

Remove all lines from the [TITLE] section.

Raises:

EngineError – On C API failure.

Return type:

None

files_get(key)#

Read one [FILES] field by key.

Parameters:

key (str) – Field key (e.g. "RAINFALL_PATH", "HOTSTART_USE_PATH").

Returns:

Field value string.

Return type:

str

files_set(key, value)#

Write one [FILES] field by key.

Parameters:

  • key (str) – Field key.

  • value (str) – New value; "" to clear.

Return type:

None

finalize()#

Finalize the model – build connectivity and allocate arrays.

Transitions to INITIALIZED state.

Returns:

None

Return type:

None

Raises:

EngineError – If finalization fails.

get_crs()#

Return the model’s coordinate reference system string.

Returns:

CRS string (EPSG identifier, PROJ string, or WKT).

Raises:

EngineError – On C API failure.

Return type:

str

get_option(key)#

Return a SWMM option value as a string.

Raises:

EngineError – On unknown key.

Parameters:

key (str)

Return type:

str

get_option_ext(key)#

Return the value of an extension option (unknown to base SWMM).

Raises:

EngineError – On unknown key.

Parameters:

key (str)

Return type:

str

get_title_count()#

Number of lines in the [TITLE] section.

Raises:

EngineError – On C API failure.

Return type:

int

get_title_line(index)#

Return a title line by zero-based index.

Raises:

EngineError – On bad index.

Parameters:

index (int)

Return type:

str

get_userflag_bool(name)#

Return a boolean user flag value.

Raises:

EngineError – On unknown flag.

Parameters:

name (str)

Return type:

bool

get_userflag_int(name)#

Return an integer user flag value.

Raises:

EngineError – On unknown flag.

Parameters:

name (str)

Return type:

int

get_userflag_real(name)#

Return a real-valued user flag.

Raises:

EngineError – On unknown flag.

Parameters:

name (str)

Return type:

float

property handle: int#

Raw engine handle as an integer (for use by ModelEditor).

Returns:

The underlying C engine pointer cast to an integer.

Return type:

int

plugin_get(idx)#

Read one [PLUGINS] row by index.

Parameters:

idx (int) – Plugin index in [0, plugins_count()).

Returns:

Tuple (path, args).

Return type:

tuple[str, str]

plugin_remove(path_or_id)#

Remove the [PLUGINS] row matching path_or_id.

Parameters:

path_or_id (str) – Library path, plugin id, or id:version string.

Return type:

None

plugin_set(path_or_id, args='')#

Add or replace a [PLUGINS] row keyed by path/id.

Parameters:

  • path_or_id (str) – Library path, plugin id, or id:version string.

  • args (str) – Space-separated argument tokens.

Return type:

None

plugins_count()#

Return the number of [PLUGINS] entries on the engine.

Returns:

Plugin count.

Return type:

int

Remove the most recently added link (undo-of-add).

Valid in BUILDING or OPENED state. The link_id must match the current tail; otherwise SWMM_ERR_BADINDEX is returned.

Parameters:

link_id (str) – Expected tail link identifier.

Returns:

Error code (0 on success).

Return type:

int

pop_last_node(node_id)#

Remove the most recently added node (undo-of-add).

Valid in BUILDING or OPENED state. The node_id must match the current tail; otherwise SWMM_ERR_BADINDEX is returned. Returns SWMM_ERR_BADPARAM if any link still references the tail node – pop those links first via pop_last_link.

Parameters:

node_id (str) – Expected tail node identifier.

Returns:

Error code (0 on success).

Return type:

int

Set the length of a conduit link.

Parameters:

  • idx (int) – Link index.

  • length (float) – Conduit length (project length units).

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

Set the upstream and downstream nodes for a link.

Parameters:

  • idx (int) – Link index.

  • from_node (int) – Upstream node index.

  • to_node (int) – Downstream node index.

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

Set Manning’s roughness coefficient for a conduit.

Parameters:

  • idx (int) – Link index.

  • n (float) – Manning’s n (dimensionless).

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

Set the cross-section geometry of a conduit.

Parameters:

  • idx (int) – Link index.

  • shape (int) – Cross-section shape code.

  • g1 (float) – Primary geometry parameter (e.g. diameter for circular).

  • g2 (float) – Secondary geometry parameter.

  • g3 (float) – Tertiary geometry parameter.

  • g4 (float) – Quaternary geometry parameter.

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

@see: L{openswmm.engine.XSectShape}

set_node_invert(idx, elev)#

Set the invert elevation of a node.

Parameters:

  • idx (int) – Node index.

  • elev (float) – Invert elevation (project length units).

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

set_node_max_depth(idx, depth)#

Set the maximum depth of a node.

Parameters:

  • idx (int) – Node index.

  • depth (float) – Maximum depth (project length units).

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

set_option(key, value)#

Set a SWMM option.

Raises:

EngineError – On unknown key or invalid value.

Parameters:
Return type:

None

set_option_ext(key, value)#

Set the value of an extension option.

Raises:

EngineError – On C API failure.

Parameters:
Return type:

None

set_title(text)#

Replace all title lines with new text. Newlines split lines.

Raises:

EngineError – On C API failure.

Parameters:

text (str)

Return type:

None

set_userflag_bool(name, value)#

Set a boolean user flag.

Raises:

EngineError – On C API failure.

Parameters:
Return type:

None

set_userflag_int(name, value)#

Set an integer user flag.

Raises:

EngineError – On C API failure.

Parameters:
Return type:

None

set_userflag_real(name, value)#

Set a real-valued user flag.

Raises:

EngineError – On C API failure.

Parameters:
Return type:

None

to_solver()#

Transfer ownership of the engine handle to a Solver.

After this call, the ModelBuilder is invalidated and must not be used. The returned Solver owns the engine handle.

Returns:

A new Solver wrapping this model’s engine.

Return type:

L{Solver}

validate()#

Validate model topology.

Checks for orphaned links and ensures at least one outfall is present. Does not change state. Safe to call multiple times.

Returns:

None

Return type:

None

Raises:

EngineError – If topology validation fails.

write(path)#

Write the model to a SWMM .inp file.

Parameters:

path (str) – Output file path.

Returns:

None

Return type:

None

Raises:

EngineError – On C API failure.

write_with_plugin(path, output_plugin_id='')#

Write the current model to disk using an output plugin.

Parameters:

  • path (str) – Destination file path.

  • output_plugin_id (str) – Plugin id, or "" for the built-in writer.

Return type:

None

start_datetime: datetime#
end_datetime: datetime#
report_start_datetime: datetime#

Model editing (deletion + type conversion)#

Model Editing — Object Deletion and Type Conversion#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._edit.

class ConversionResult(new_type, cleared_fields, warnings)#

Bases: object

Result of an in-place node or link type conversion.

Variables:

  • new_type – The new C-API type enum value.

  • cleared_fields – List of field names cleared during conversion.

  • warnings – Non-fatal topology warnings.

Parameters:

  • new_type (int) – The new C-API type enum value.

  • cleared_fields (list[str]) – List of field names that were cleared (reset to defaults) during the conversion.

  • warnings (list[str]) – Non-fatal topology warnings (e.g. “model has no outfall after this conversion”). Conversion still proceeds even when warnings are present.

new_type: int#
cleared_fields: list[str]#
warnings: list[str]#
class ImpactEntry(obj_type, obj_idx, field, cascaded)#

Bases: object

One cross-reference that would be affected by a deletion.

Variables:

  • obj_type – Integer code for the referencing object type (0=node, 1=link, 2=subcatchment, 3=gage, 4=table, 5=transect, 6=inlet_usage).

  • obj_type_name – Human-readable name for obj_type.

  • obj_idx – Zero-based index of the referencing object.

  • field – Name of the specific cross-reference field (e.g. "node1", "outlet_node").

  • cascaded – True if the referencing object will be deleted; False if only the reference will be nullified.

Parameters:

  • obj_type (int) – Integer code for the referencing object type.

  • obj_idx (int) – Zero-based index of the referencing object.

  • field (str) – Name of the specific cross-reference field.

  • cascaded (bool) – True for cascade-delete, False for nullify.

obj_type: int#
obj_type_name: str#
obj_idx: int#
field: str#
cascaded: bool#
class ModelEditor(engine)#

Bases: object

Edit an existing SWMM model – delete objects and convert types.

Accepts any object that exposes a handle property returning the raw engine pointer as an integer. Both ModelBuilder (BUILDING state) and Solver (OPENED state) satisfy this contract.

Parameters:

engine (object) – A ModelBuilder or Solver instance.

Example:

from openswmm.engine import ModelBuilder, ModelEditor, NodeType, LinkType

m = ModelBuilder()
m.add_node("J1", NodeType.JUNCTION)
m.add_node("J2", NodeType.JUNCTION)
m.add_node("OUT1", NodeType.OUTFALL)
m.add_link("C1", LinkType.CONDUIT)
m.add_link("C2", LinkType.CONDUIT)
m.set_link_nodes(0, 0, 1)
m.set_link_nodes(1, 1, 2)

ed = ModelEditor(m)

# Non-destructive preview
impacts = ed.analyze_node_impact("J1")

# Delete J1 -- C1 cascade-deleted automatically
cascade = ed.delete_node("J1")

# Convert C2 conduit -> weir
result = ed.convert_link("C2", LinkType.WEIR)
analyze_gage_impact(id_or_idx)#

Preview which objects reference a rain gage.

Parameters:

id_or_idx (int or str) – Gage name or zero-based index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

  • KeyError – If id_or_idx is a name and the gage is not found.

  • EngineError – On C API failure.

Preview which objects reference a link, without deleting it.

Parameters:

id_or_idx (int or str) – Link name or zero-based index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

  • KeyError – If id_or_idx is a name and the link is not found.

  • EngineError – On C API failure.

analyze_node_impact(id_or_idx)#

Preview which objects reference a node, without deleting it.

Parameters:

id_or_idx (int or str) – Node name or zero-based index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

  • KeyError – If id_or_idx is a name and the node is not found.

  • EngineError – On C API failure.

analyze_subcatch_impact(id_or_idx)#

Preview which objects reference a subcatchment.

Parameters:

id_or_idx (int or str) – Subcatchment name or zero-based index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

  • KeyError – If id_or_idx is a name and the subcatchment is not found.

  • EngineError – On C API failure.

analyze_table_impact(id_or_idx)#

Preview which objects reference a time series or curve.

Parameters:

id_or_idx (int or str) – Table name or zero-based index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

  • KeyError – If id_or_idx is a name and the table is not found.

  • EngineError – On C API failure.

analyze_transect_impact(idx)#

Preview which links reference a transect.

Parameters:

idx (int) – Zero-based transect index.

Returns:

List of ImpactEntry describing what would be affected.

Return type:

list[ImpactEntry]

Raises:

EngineError – On C API failure.

Convert a link to a different type in place.

Parameters:

  • id_or_idx (int or str) – Link name or zero-based index.

  • new_type (int) – Target link type code.

Returns:

ConversionResult with cleared fields and warnings.

Return type:

L{ConversionResult}

Raises:

  • RuntimeError – If not in BUILDING or OPENED state, the type is invalid, or new_type equals the current type.

  • KeyError – If id_or_idx is a name and the link is not found.

  • EngineError – On C API failure.

@see: L{openswmm.engine.LinkType}

convert_node(id_or_idx, new_type)#

Convert a node to a different type in place.

Parameters:

  • id_or_idx (int or str) – Node name or zero-based index.

  • new_type (int) – Target node type code.

Returns:

ConversionResult with cleared fields and warnings.

Return type:

L{ConversionResult}

Raises:

  • RuntimeError – If not in BUILDING or OPENED state, the type is invalid, or new_type equals the current type.

  • KeyError – If id_or_idx is a name and the node is not found.

  • EngineError – On C API failure.

@see: L{openswmm.engine.NodeType}

delete_gage(id_or_idx)#

Delete a rain gage and nullify subcatchment gage references.

Parameters:

id_or_idx (int or str) – Gage name or zero-based index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:

Delete a link and cascade-delete or nullify referencing objects.

Parameters:

id_or_idx (int or str) – Link name or zero-based index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:
delete_node(id_or_idx)#

Delete a node and cascade-delete or nullify all referencing objects.

Parameters:

id_or_idx (int or str) – Node name or zero-based index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:
delete_subcatch(id_or_idx)#

Delete a subcatchment and nullify referencing objects.

Parameters:

id_or_idx (int or str) – Subcatchment name or zero-based index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:

  • RuntimeError – If not in BUILDING or OPENED state.

  • KeyError – If id_or_idx is a name and the subcatchment is not found.

  • EngineError – On C API failure.

delete_table(id_or_idx)#

Delete a time series or curve and nullify all referencing objects.

Parameters:

id_or_idx (int or str) – Table name or zero-based index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:
delete_transect(idx)#

Delete a transect and reset referencing conduit cross-sections.

Parameters:

idx (int) – Zero-based transect index.

Returns:

List of ImpactEntry describing what was affected.

Return type:

list[ImpactEntry]

Raises:
property gage_count: int#

Current number of rain gages in the model.

Returns:

Gage count.

Return type:

int

Current number of links in the model.

Returns:

Link count.

Return type:

int

property node_count: int#

Current number of nodes in the model.

Returns:

Node count.

Return type:

int

property subcatch_count: int#

Current number of subcatchments in the model.

Returns:

Subcatchment count.

Return type:

int

property table_count: int#

Current number of tables (time series + curves) in the model.

Returns:

Table count.

Return type:

int

start_datetime: datetime#
end_datetime: datetime#
report_start_datetime: datetime#

Nodes#

Node access (Pythonic v1 surface)#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._nodes.

class DividerView#

Bases: object

type: int#
class Node(solver, index)#

Bases: object

Single-node wrapper. See Nodes for the collection.

Parameters:
depth_from_volume(volume)#
Parameters:

volume (float)

Return type:

float

quality(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

set_head_boundary(head)#
Parameters:

head (float)

Return type:

None

set_quality_mass_flux(pollutant, mass_rate)#
Parameters:
Return type:

None

id: str#
index: int#
type: NodeType#
solver: Solver#
invert_elev: float#
max_depth: float#
surcharge_depth: float#
ponded_area: float#
initial_depth: float#
crown_elev: float#
full_volume: float#
degree: int#
depth: float#
head: float#
volume: float#
lateral_inflow: float#
overflow: float#
inflow: float#
losses: float#
outflow: float#
stats: NodeStatsView#
storage: StorageView#
outfall: OutfallView#
divider: DividerView#
class NodeStatsView#

Bases: object

max_depth: float#
max_overflow: float#
vol_flooded: float#
time_flooded: float#
class Nodes(solver)#

Bases: object

Indexable, iterable collection of Node wrappers.

Parameters:

solver (Solver)

add(node_id, node_type)#
Parameters:

  • node_id (str)

  • node_type (NodeType)

Return type:

Node

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(node_id)#
Parameters:

node_id (str)

Return type:

int

pop_last(node_id)#
Parameters:

node_id (str)

Return type:

None

qualities(pollutant)#
Parameters:

pollutant (int | str)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

rename(key, new_id)#
Parameters:
Return type:

None

set_lateral_inflows(values)#
Parameters:

values (ndarray[tuple[Any, ...], dtype[Any]])

Return type:

None

depths: ndarray[tuple[Any, ...], dtype[Any]]#
heads: ndarray[tuple[Any, ...], dtype[Any]]#
inflows: ndarray[tuple[Any, ...], dtype[Any]]#
overflows: ndarray[tuple[Any, ...], dtype[Any]]#
volumes: ndarray[tuple[Any, ...], dtype[Any]]#
outflows: ndarray[tuple[Any, ...], dtype[Any]]#
losses: ndarray[tuple[Any, ...], dtype[Any]]#
lateral_inflows: ndarray[tuple[Any, ...], dtype[Any]]#
ids: ndarray[tuple[Any, ...], dtype[Any]]#
class OutfallView#

Bases: object

set_stage(stage)#
Parameters:

stage (float)

Return type:

None

set_tidal_curve(curve_idx)#
Parameters:

curve_idx (int)

Return type:

None

set_timeseries(ts_idx)#
Parameters:

ts_idx (int)

Return type:

None

type: OutfallType#
param: float#
flap_gate: bool#
route_to: int#
class StorageView#

Bases: object

curve: int#
functional: Tuple[float, float, float]#
seep_rate: float#
exfil_params: Tuple[float, float, float]#

Subcatchments#

Subcatchment access (Pythonic v1 surface)#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._subcatchments.

class CoverageView(sub)#

Bases: MutableMapping[str, float]

Parameters:

sub (Subcatchment)

class InfiltrationView#

Bases: object

set_curve_number(cn)#
Parameters:

cn (float)

Return type:

None

set_green_ampt(suction, conductivity, initial_deficit)#
Parameters:
Return type:

None

set_horton(f0, fmin, decay, dry_time)#
Parameters:
Return type:

None

model: InfilModel#
horton: Tuple[float, float, float, float]#
green_ampt: Tuple[float, float, float]#
curve_number: float#
class Subcatchment(solver, index)#

Bases: object

Single-subcatchment wrapper. See Subcatchments.

Parameters:
ponded_quality(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

quality(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

set_outlet_node(node)#
Parameters:

node (Node | int | str)

Return type:

None

set_outlet_subcatchment(sub)#
Parameters:

sub (Subcatchment | int | str)

Return type:

None

set_ponded_quality(pollutant, mass)#
Parameters:
Return type:

None

id: str#
index: int#
solver: Solver#
area: float#
width: float#
slope: float#
imperv_pct: float#
n_imperv: float#
n_perv: float#
ds_imperv: float#
ds_perv: float#
gage: Gage#
outlet: Node | Subcatchment | None#
runoff: float#
groundwater: float#
rainfall: float#
snow_depth: float#
evap: float#
infil: float#
stats: SubcatchmentStatsView#
infiltration: InfiltrationView#
coverage: CoverageView#
class SubcatchmentStatsView#

Bases: object

precip: float#
runoff_vol: float#
max_runoff: float#
class Subcatchments(solver)#

Bases: object

Indexable, iterable collection of Subcatchment wrappers.

Parameters:

solver (Solver)

add(sub_id)#
Parameters:

sub_id (str)

Return type:

Subcatchment

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(sub_id)#
Parameters:

sub_id (str)

Return type:

int

qualities(pollutant)#
Parameters:

pollutant (int | str)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

rename(key, new_id)#
Parameters:
Return type:

None

runoffs: ndarray[tuple[Any, ...], dtype[Any]]#
rainfalls: ndarray[tuple[Any, ...], dtype[Any]]#
evaps: ndarray[tuple[Any, ...], dtype[Any]]#
infils: ndarray[tuple[Any, ...], dtype[Any]]#
snow_depths: ndarray[tuple[Any, ...], dtype[Any]]#
ids: ndarray[tuple[Any, ...], dtype[Any]]#

Rain gages#

Rain gage access (Pythonic v1 surface)#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._gages.

class Gage(solver, index)#

Bases: object

Parameters:
set_file(path, station_id)#
Parameters:
Return type:

None

set_rain_interval(seconds)#
Parameters:

seconds (float | timedelta)

Return type:

None

set_timeseries(ts_id)#
Parameters:

ts_id (str)

Return type:

None

id: str#
index: int#
solver: Solver#
rain_type: GageRainType#
data_source: GageDataSource#
rainfall: float#
class Gages(solver)#

Bases: object

Parameters:

solver (Solver)

add(gage_id)#
Parameters:

gage_id (str)

Return type:

Gage

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(gage_id)#
Parameters:

gage_id (str)

Return type:

int

rename(key, new_id)#
Parameters:
Return type:

None

rainfalls: ndarray[tuple[Any, ...], dtype[Any]]#
ids: ndarray[tuple[Any, ...], dtype[Any]]#

External inflows (DWF, RDII, time-series)#

Type stubs for openswmm.engine._inflows.

class HydrographEntry(uh_name, month, response, r, t, k, dmax, drecov, dinit)#

Bases: NamedTuple

Create new instance of HydrographEntry(uh_name, month, response, r, t, k, dmax, drecov, dinit)

Parameters:
dinit: float#

Alias for field number 8

dmax: float#

Alias for field number 6

drecov: float#

Alias for field number 7

k: float#

Alias for field number 5

month: int#

Alias for field number 1

r: float#

Alias for field number 3

response: int#

Alias for field number 2

t: float#

Alias for field number 4

uh_name: str#

Alias for field number 0

class HydrographGageEntry(uh_name, gage_name)#

Bases: NamedTuple

Create new instance of HydrographGageEntry(uh_name, gage_name)

Parameters:

  • uh_name (str)

  • gage_name (str)

gage_name: str#

Alias for field number 1

uh_name: str#

Alias for field number 0

class Inflows(solver)#

Bases: object

Parameters:

solver (Solver)

add_dwf(node, constituent, *, avg_value=Ellipsis, monthly_pattern=Ellipsis, daily_pattern=Ellipsis, hourly_pattern=Ellipsis, weekend_pattern=Ellipsis)#
Parameters:

  • node (int | str)

  • constituent (str)

  • avg_value (float)

  • monthly_pattern (str)

  • daily_pattern (str)

  • hourly_pattern (str)

  • weekend_pattern (str)

Return type:

None

add_external(node, constituent, *, ts_name=Ellipsis, type=Ellipsis, m_factor=Ellipsis, s_factor=Ellipsis, baseline=Ellipsis, pattern=Ellipsis)#
Parameters:
Return type:

None

add_hydrograph(uh_name, month, response, r, t, k, *, dmax=Ellipsis, drecov=Ellipsis, dinit=Ellipsis)#
Parameters:
Return type:

None

add_hydrograph_gage(uh_name, gage_name)#
Parameters:

  • uh_name (str)

  • gage_name (str)

Return type:

None

add_rdii(node, uh_name, area)#
Parameters:
Return type:

None

add_rdii_decay(uh_name, response, k_dep, k_0, k_T, T_ref, theta_rec, T_freeze)#
Parameters:
Return type:

None

get_hydrograph(idx)#
Parameters:

idx (int)

Return type:

HydrographEntry

get_hydrograph_gage(idx)#
Parameters:

idx (int)

Return type:

HydrographGageEntry

get_hydrograph_group_id(idx)#
Parameters:

idx (int)

Return type:

str

get_rdii(idx)#
Parameters:

idx (int)

Return type:

RDIIEntry

get_rdii_decay(idx)#
Parameters:

idx (int)

Return type:

RDIIDecayEntry

external_count: int#
dwf_count: int#
rdii_count: int#
hydrograph_count: int#
hydrograph_gage_count: int#
hydrograph_group_count: int#
rdii_decay_count: int#
class RDIIDecayEntry(uh_name, response, k_dep, k_0, k_T, T_ref, theta_rec, T_freeze)#

Bases: NamedTuple

Create new instance of RDIIDecayEntry(uh_name, response, k_dep, k_0, k_T, T_ref, theta_rec, T_freeze)

Parameters:
T_freeze: float#

Alias for field number 7

T_ref: float#

Alias for field number 5

k_0: float#

Alias for field number 3

k_T: float#

Alias for field number 4

k_dep: float#

Alias for field number 2

response: int#

Alias for field number 1

theta_rec: float#

Alias for field number 6

uh_name: str#

Alias for field number 0

class RDIIEntry(node_index, uh_name, area)#

Bases: NamedTuple

Create new instance of RDIIEntry(node_index, uh_name, area)

Parameters:
area: float#

Alias for field number 2

node_index: int#

Alias for field number 0

uh_name: str#

Alias for field number 1

Advanced forcing (mode + persistence)#

Type stubs for openswmm.engine._forcing.

class Forcing(solver)#

Bases: object

Parameters:

solver (Solver)

clear(target, key)#
Parameters:

  • target (ForcingTarget)

  • key (int | str)

Return type:

None

clear_all()#
Return type:

None

gage_rainfall(gage, value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

Parameters:
Return type:

None

Parameters:
Return type:

None

node_head_boundary(node, value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

node_lat_inflow(node, value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

node_quality(node, pollutant, mass_rate, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

subcatchment_evap(sub, value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

subcatchment_rainfall(sub, value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:
Return type:

None

Control rules#

Type stubs for openswmm.engine._controls.

class ControlRule(id, text)#

Bases: NamedTuple

Create new instance of ControlRule(id, text)

Parameters:
id: str#

Alias for field number 0

text: str#

Alias for field number 1

class Controls(solver)#

Bases: MutableSequence[ControlRule]

Parameters:

solver (Solver)

append(value)#

S.append(value) – append value to the end of the sequence

Parameters:

value (Any)

Return type:

None

clear() → None -- remove all items from S#
Return type:

None

insert(idx, value)#

S.insert(index, value) – insert value before index

Parameters:
Return type:

None

Parameters:
Return type:

None

Parameters:
Return type:

None

Pollutants#

Type stubs for openswmm.engine._pollutants.

class Pollutant(solver, index)#

Bases: object

Parameters:
set_co_pollutant(co, fraction)#
Parameters:
Return type:

None

id: str#
index: int#
solver: Solver#
units: ConcentrationUnits#
kdecay: float#
mwt: float#
rain_conc: float#
gw_conc: float#
init_conc: float#
rdii_conc: float#
snow_only: bool#
co_pollutant: Tuple[Pollutant, float] | None#
class Pollutants(solver)#

Bases: object

Parameters:

solver (Solver)

add(pollut_id, units=Ellipsis)#
Parameters:

  • pollut_id (str)

  • units (ConcentrationUnits)

Return type:

Pollutant

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(pollut_id)#
Parameters:

pollut_id (str)

Return type:

int

Parameters:
Return type:

None

set_node_quality(node, pollutant, conc)#
Parameters:
Return type:

None

Water quality (landuse, buildup, washoff, treatment)#

Type stubs for openswmm.engine._quality.

class Landuse(solver, index)#

Bases: object

Parameters:
id: str#
index: int#
sweep_interval: float#
sweep_removal: float#
class Landuses(solver)#

Bases: object

Parameters:

solver (Solver)

add(landuse_id)#
Parameters:

landuse_id (str)

Return type:

Landuse

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(landuse_id)#
Parameters:

landuse_id (str)

Return type:

int

class Quality(solver)#

Bases: object

Parameters:

solver (Solver)

clear_treatment(node, pollutant)#
Parameters:
Return type:

None

get_buildup(landuse, pollutant)#
Parameters:
Return type:

Dict[str, object]

get_treatment(node, pollutant)#
Parameters:
Return type:

str

get_washoff(landuse, pollutant)#
Parameters:
Return type:

Dict[str, object]

set_buildup(landuse, pollutant, *, func, c1, c2, c3, normalizer=Ellipsis)#
Parameters:
Return type:

None

set_treatment(node, pollutant, expression)#
Parameters:
Return type:

None

set_washoff(landuse, pollutant, *, func, coeff, expon, sweep_effic=Ellipsis, bmp_effic=Ellipsis)#
Parameters:
Return type:

None

landuses: Landuses#

Tables (time series, curves, patterns)#

Type stubs for openswmm.engine._tables.

class Curve(solver, index)#

Bases: _PointTable

Parameters:
points: ndarray[tuple[Any, ...], dtype[Any]]#
class Pattern(solver, index)#

Bases: object

Parameters:
set_factors(values, type=Ellipsis)#
Parameters:
Return type:

None

index: int#
solver: Solver#
class Patterns(solver)#

Bases: object

Parameters:

solver (Solver)

add(pattern_id, type=Ellipsis)#
Parameters:

  • pattern_id (str)

  • type (PatternType)

Return type:

Pattern

class Tables(solver)#

Bases: object

Parameters:

solver (Solver)

add_curve(curve_id, curve_type=Ellipsis)#
Parameters:

  • curve_id (str)

  • curve_type (int)

Return type:

Curve

add_timeseries(ts_id)#
Parameters:

ts_id (str)

Return type:

TimeSeries

as_curve(key)#
Parameters:

key (int | str)

Return type:

Curve

as_timeseries(key)#
Parameters:

key (int | str)

Return type:

TimeSeries

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(table_id)#
Parameters:

table_id (str)

Return type:

int

class TimeSeries(solver, index)#

Bases: _PointTable

Parameters:
add(when, value)#
Parameters:
Return type:

None

points: ndarray[tuple[Any, ...], dtype[Any]]#

Infrastructure (transects, streets, inlets, LIDs)#

Type stubs for openswmm.engine._infrastructure.

class Infrastructure(solver)#

Bases: object

Parameters:

solver (Solver)

transects: Transects#
streets: Streets#
inlets: Inlets#
lids: LIDs#
class Inlets(solver)#

Bases: object

Parameters:

solver (Solver)

add(inlet_id, inlet_type)#
Parameters:

  • inlet_id (str)

  • inlet_type (str)

Return type:

int

set_params(idx, *, length=Ellipsis, width=Ellipsis, grate_type=Ellipsis, open_area=Ellipsis, splash_veloc=Ellipsis)#
Parameters:
Return type:

None

class LIDs(solver)#

Bases: object

Parameters:

solver (Solver)

add(lid_id, lid_type)#
Parameters:

  • lid_id (str)

  • lid_type (LidType)

Return type:

int

set_drain(idx, *, coeff, expon, offset)#
Parameters:
Return type:

None

set_soil(idx, *, thick, porosity, fc, wp, ksat, kslope)#
Parameters:
Return type:

None

set_storage(idx, *, thick, void_frac, ksat)#
Parameters:
Return type:

None

set_surface(idx, *, storage, roughness, slope)#
Parameters:
Return type:

None

usage_add(subcatchment, lid, *, number, area, width, init_sat=Ellipsis, from_imperv=Ellipsis)#
Parameters:
Return type:

None

class Streets(solver)#

Bases: object

Parameters:

solver (Solver)

add(street_id)#
Parameters:

street_id (str)

Return type:

int

set_params(idx, *, t_crown, h_curb, sx, n_road, gutter_depres=Ellipsis, gutter_width=Ellipsis, sides=Ellipsis, back_width=Ellipsis, back_slope=Ellipsis, back_n=Ellipsis)#
Parameters:
Return type:

None

class Transects(solver)#

Bases: object

Parameters:

solver (Solver)

add(transect_id)#
Parameters:

transect_id (str)

Return type:

int

add_station(idx, station, elevation)#
Parameters:
Return type:

None

set_roughness(idx, n_left, n_right, n_channel)#
Parameters:
Return type:

None

Hot start#

Hot start files (Pythonic v1 surface)#

Type stubs for openswmm.engine._hotstart.

class HotStart#

Bases: object

apply(solver)#
Parameters:

solver (Solver)

Return type:

None

close()#
Return type:

None

classmethod open(path)#
Parameters:

path (str | PathLike[str])

Return type:

HotStart

static save_from(solver, path)#
Parameters:
Return type:

None

Parameters:
Return type:

None

Parameters:
Return type:

None

set_node_depth(node_id, depth)#
Parameters:
Return type:

None

set_node_head(node_id, head)#
Parameters:
Return type:

None

set_subcatchment_runoff(sub_id, runoff)#
Parameters:
Return type:

None

sim_datetime: datetime#
crs: str | None#
node_count: int#
warnings: List[str]#
class SaveSchedule(solver)#

Bases: MutableSequence[SaveScheduleEntry]

Parameters:

solver (Solver)

append(value)#

S.append(value) – append value to the end of the sequence

Parameters:

value (Any)

Return type:

None

clear() → None -- remove all items from S#
Return type:

None

insert(idx, value)#

S.insert(index, value) – insert value before index

Parameters:
Return type:

None

class SaveScheduleEntry(when, path)#

Bases: NamedTuple

Create new instance of SaveScheduleEntry(when, path)

Parameters:
path: str#

Alias for field number 1

when: datetime#

Alias for field number 0

Mass balance#

Mass balance & continuity (Pythonic v1 surface)#

Type stubs for openswmm.engine._massbalance.

class MassBalance(solver)#

Bases: object

Parameters:

solver (Solver)

quality_continuity_error(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

quality_evap_loss(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

quality_seep_loss(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

routing_total(component)#
Parameters:

component (RoutingTotal)

Return type:

float

runoff_total(component)#
Parameters:

component (RunoffTotal)

Return type:

float

runoff_continuity_error: float#
routing_continuity_error: float#
routing_diagnostics: RoutingDiagnostics#
max_courant: float#

Statistics#

Simulation statistics (Pythonic v1 surface)#

Type stubs for openswmm.engine._statistics.

class Statistics(solver)#

Bases: object

Parameters:

solver (Solver)

node_max_depth: ndarray[tuple[Any, ...], dtype[Any]]#
node_max_overflow: ndarray[tuple[Any, ...], dtype[Any]]#
node_vol_flooded: ndarray[tuple[Any, ...], dtype[Any]]#
node_time_flooded: ndarray[tuple[Any, ...], dtype[Any]]#
subcatchment_runoff_vol: ndarray[tuple[Any, ...], dtype[Any]]#
subcatchment_max_runoff: ndarray[tuple[Any, ...], dtype[Any]]#

Output reader (binary .out file)#

Binary output file reader (Pythonic v1 surface)#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._output_reader.

class OutputReader(path)#

Bases: object

Read a SWMM binary .out file.

Parameters:

path (_PathLike)

close()#
Return type:

None

Parameters:
Return type:

Dict[OutLinkVar | int, float]

Parameters:

  • period (int)

  • var (OutLinkVar)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

Parameters:

  • link (int | str)

  • var (OutLinkVar)

  • start (int | None)

  • end (int | None)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

node_attributes(node, period)#
Parameters:
Return type:

Dict[OutNodeVar | int, float]

node_result(period, var)#
Parameters:

  • period (int)

  • var (OutNodeVar)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

node_series(node, var, *, start=Ellipsis, end=Ellipsis)#
Parameters:

  • node (int | str)

  • var (OutNodeVar)

  • start (int | None)

  • end (int | None)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

node_stats(node)#
Parameters:

node (int | str)

Return type:

_OutputNodeStats

subcatchment_attributes(sub, period)#
Parameters:
Return type:

Dict[OutSubcatchVar | int, float]

subcatchment_result(period, var)#
Parameters:

  • period (int)

  • var (OutSubcatchVar)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

subcatchment_series(sub, var, *, start=Ellipsis, end=Ellipsis)#
Parameters:

  • sub (int | str)

  • var (OutSubcatchVar)

  • start (int | None)

  • end (int | None)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

system_result(period, var)#
Parameters:

  • period (int)

  • var (OutSystemVar)

Return type:

float

system_series(var, *, start=Ellipsis, end=Ellipsis)#
Parameters:

  • var (OutSystemVar)

  • start (int | None)

  • end (int | None)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

version: int#
flow_units: FlowUnits#
period_count: int#
report_step: timedelta#
start_datetime: datetime#
pollutant_count: int#
node_count: int#
subcatchment_count: int#
error_code: int#
node_ids: List[str]#
subcatchment_ids: List[str]#
period_times: ndarray[tuple[Any, ...], dtype[Any]]#

Spatial (CRS, coordinates, vertices, polygons)#

Type stubs for openswmm.engine._spatial.

class Spatial(solver)#

Bases: object

Parameters:

solver (Solver)

gage_coord(gage)#
Parameters:

gage (int | str)

Return type:

Tuple[float, float]

Parameters:

link (int | str)

Return type:

Tuple[float, float]

Parameters:

link (int | str)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

node_coord(node)#
Parameters:

node (int | str)

Return type:

Tuple[float, float]

node_coords()#
Return type:

ndarray[tuple[Any, …], dtype[Any]]

set_gage_coord(gage, x, y)#
Parameters:
Return type:

None

Parameters:
Return type:

None

Parameters:
Return type:

None

set_node_coord(node, x, y)#
Parameters:
Return type:

None

set_node_coords(coords)#
Parameters:

coords (ndarray[tuple[Any, ...], dtype[Any]])

Return type:

None

set_subcatchment_coord(sub, x, y)#
Parameters:
Return type:

None

set_subcatchment_polygon(sub, polygon)#
Parameters:
Return type:

None

subcatchment_coord(sub)#
Parameters:

sub (int | str)

Return type:

Tuple[float, float]

subcatchment_polygon(sub)#
Parameters:

sub (int | str)

Return type:

ndarray[tuple[Any, …], dtype[Any]]

crs: str#

Enumerations#

Enumerations#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._enums.

Integer-backed enums mirroring the C API enum definitions in openswmm_engine.h. All enums inherit from enum.IntEnum and can be compared directly with integer return values from C API functions.

class BuildupFunc(*values)

Bases: IntEnum

Pollutant buildup function type.

Variables:

  • NONE – No buildup.

  • POW – Power function.

  • EXP – Exponential function.

  • SAT – Saturation function.

  • EXT – External time series.

NONE = 0
POW = 1
EXP = 2
SAT = 3
EXT = 4
class ConcentrationUnits(*values)

Bases: IntEnum

Pollutant concentration units.

Variables:

  • MG_PER_L – Milligrams per liter.

  • UG_PER_L – Micrograms per liter.

  • COUNT_PER_L – Counts per liter.

MG_PER_L = 0
UG_PER_L = 1
COUNT_PER_L = 2
class EngineState(*values)

Bases: IntEnum

Engine lifecycle states.

Mirrors SWMM_EngineState in openswmm_engine.h.

CREATED = 1
OPENED = 2
INITIALIZED = 3
STARTED = 4
RUNNING = 5
ENDED = 6
CLOSED = 7
BUILDING = 8
class ErrorCode(*values)

Bases: IntEnum

SWMM C API return codes.

Mirrors the integer error codes returned by every C API entry point in openswmm_engine.h.

Variables:

  • OK – Success (0).

  • NOMEM – Out of memory.

  • INPFILE – Cannot open input file.

  • RPTFILE – Cannot open report file.

  • OUTFILE – Cannot open output file.

  • PARSE – Input file parse error.

  • LIFECYCLE – Function called in wrong lifecycle state.

  • BADHANDLE – NULL or invalid engine handle.

  • BADINDEX – Object index out of range.

  • BADPARAM – Invalid parameter value.

  • PLUGIN – Plugin error.

  • IO – I/O error.

  • HOTSTART – Hot start file error.

  • CRS – Coordinate reference system error.

  • NUMERICAL – Numerical error.

  • INTERNAL – Internal error.

OK = 0
NOMEM = 1
INPFILE = 2
RPTFILE = 3
OUTFILE = 4
PARSE = 5
LIFECYCLE = 6
BADHANDLE = 7
BADINDEX = 8
BADPARAM = 9
PLUGIN = 10
IO = 11
HOTSTART = 12
CRS = 13
NUMERICAL = 14
DEPENDENCY = 15
INTERNAL = 99
class FlowUnits(*values)

Bases: IntEnum

Flow unit systems.

Variables:

  • CFS – Cubic feet per second (US customary).

  • GPM – Gallons per minute (US customary).

  • MGD – Million gallons per day (US customary).

  • CMS – Cubic meters per second (SI).

  • LPS – Liters per second (SI).

  • MLD – Million liters per day (SI).

CFS = 0
GPM = 1
MGD = 2
CMS = 3
LPS = 4
MLD = 5
class ForcingMode(*values)

Bases: IntEnum

Forcing application mode.

Determines how a forced value is combined with the model-computed value.

Variables:

  • REPLACE – Replace the computed value entirely.

  • ADD – Add the forced value to the computed value.

REPLACE = 0
ADD = 1
class ForcingTarget(*values)

Bases: IntEnum

Object type codes used with openswmm.engine.Forcing.clear.

Variables:

  • NODE – Node forcing target.

  • LINK – Link forcing target.

  • SUBCATCH – Subcatchment forcing target.

  • GAGE – Rain gage forcing target.

NODE = 0
LINK = 1
SUBCATCH = 2
GAGE = 3
class GageDataSource(*values)

Bases: IntEnum

Rain gage data source type.

Variables:

  • TIMESERIES – Data comes from a time series object.

  • FILE – Data comes from an external rainfall file.

TIMESERIES = 0
FILE = 1
class GageRainType(*values)

Bases: IntEnum

Rain gage rainfall data format.

Variables:

  • INTENSITY – Rainfall intensity (depth/time).

  • VOLUME – Rainfall volume (depth per interval).

  • CUMULATIVE – Cumulative rainfall depth.

INTENSITY = 0
VOLUME = 1
CUMULATIVE = 2
class InfilModel(*values)

Bases: IntEnum

Infiltration model type.

Variables:

  • HORTON – Original Horton model.

  • MOD_HORTON – Modified Horton model.

  • GREEN_AMPT – Green-Ampt model.

  • MOD_GREEN_AMPT – Modified Green-Ampt model.

  • CURVE_NUMBER – SCS Curve Number model.

HORTON = 0
MOD_HORTON = 1
GREEN_AMPT = 2
MOD_GREEN_AMPT = 3
CURVE_NUMBER = 4
class LidType(*values)

Bases: IntEnum

Low Impact Development (LID) control type.

Variables:

  • BIO_CELL – Bioretention cell.

  • RAIN_GARDEN – Rain garden.

  • GREEN_ROOF – Green roof.

  • INFIL_TRENCH – Infiltration trench.

  • PERM_PAVEMENT – Permeable pavement.

  • RAIN_BARREL – Rain barrel.

  • ROOFTOP_DISCONN – Rooftop disconnection.

  • VEGETATIVE_SWALE – Vegetative swale.

BIO_CELL = 0
RAIN_GARDEN = 1
GREEN_ROOF = 2
INFIL_TRENCH = 3
PERM_PAVEMENT = 4
RAIN_BARREL = 5
ROOFTOP_DISCONN = 6
VEGETATIVE_SWALE = 7
class LinkType(*values)

Bases: IntEnum

Link type codes for openswmm.engine.ModelBuilder.add_link.

Variables:

  • CONDUIT – Conduit (pipe or channel).

  • PUMP – Pump.

  • ORIFICE – Orifice.

  • WEIR – Weir.

  • OUTLET – Outlet.

CONDUIT = 0
PUMP = 1
ORIFICE = 2
WEIR = 3
OUTLET = 4
class NodeType(*values)

Bases: IntEnum

Node type codes for openswmm.engine.ModelBuilder.add_node.

Variables:

  • JUNCTION – Junction node.

  • OUTFALL – Outfall node.

  • STORAGE – Storage unit.

  • DIVIDER – Flow divider.

JUNCTION = 0
OUTFALL = 1
STORAGE = 2
DIVIDER = 3
class ObjectType(*values)

Bases: IntEnum

SWMM object type codes.

Variables:

  • GAGE – Rain gage.

  • SUBCATCH – Subcatchment.

  • NODE – Node (junction, outfall, storage, divider).

  • LINK – Link (conduit, pump, orifice, weir, outlet).

  • POLLUT – Pollutant.

  • LANDUSE – Land use category.

  • TIMESER – Time series.

  • TABLE – Curve / table.

  • RDII – RDII unit hydrograph group.

  • UNITHYD – Unit hydrograph.

  • SNOWMELT – Snowmelt parameter set.

  • SHAPE – Custom cross-section shape.

  • LID – LID control.

GAGE = 0
SUBCATCH = 1
NODE = 2
LINK = 3
POLLUT = 4
LANDUSE = 5
TIMESER = 6
TABLE = 7
RDII = 8
UNITHYD = 9
SNOWMELT = 10
SHAPE = 11
LID = 12
class OrificeType(*values)

Bases: IntEnum

Orifice flow-attack classification.

Mirrors SWMM_OrificeType in openswmm_links.h.

SIDE = 0
BOTTOM = 1
class OutLinkVar(*values)

Bases: IntEnum

Link output result variable indices.

Variables:

  • FLOW – Flow rate.

  • DEPTH – Water depth.

  • VELOCITY – Flow velocity.

  • VOLUME – Stored volume.

  • CAPACITY – Capacity fraction (flow / full flow).

  • POLLUT_BASE – Base index for pollutant concentrations.

FLOW = 0
DEPTH = 1
VELOCITY = 2
VOLUME = 3
CAPACITY = 4
POLLUT_BASE = 5
class OutNodeVar(*values)

Bases: IntEnum

Node output result variable indices.

Variables:

  • DEPTH – Water depth.

  • HEAD – Hydraulic head.

  • VOLUME – Stored volume.

  • LATERAL_INFLOW – Lateral inflow rate.

  • TOTAL_INFLOW – Total inflow rate.

  • OVERFLOW – Overflow / flooding rate.

  • POLLUT_BASE – Base index for pollutant concentrations.

DEPTH = 0
HEAD = 1
VOLUME = 2
LATERAL_INFLOW = 3
TOTAL_INFLOW = 4
OVERFLOW = 5
POLLUT_BASE = 6
class OutSubcatchVar(*values)

Bases: IntEnum

Subcatchment output result variable indices.

Variables:

  • RAINFALL – Rainfall rate.

  • SNOW_DEPTH – Snow depth.

  • EVAP – Evaporation rate.

  • INFIL – Infiltration rate.

  • RUNOFF – Runoff rate.

  • GW_FLOW – Groundwater outflow rate.

  • GW_ELEV – Groundwater table elevation.

  • SOIL_MOIST – Soil moisture fraction.

  • POLLUT_BASE – Base index for pollutant concentrations.

RAINFALL = 0
SNOW_DEPTH = 1
EVAP = 2
INFIL = 3
RUNOFF = 4
GW_FLOW = 5
GW_ELEV = 6
SOIL_MOIST = 7
POLLUT_BASE = 8
class OutSystemVar(*values)

Bases: IntEnum

System-wide output result variable indices.

Variables:

  • TEMPERATURE – Air temperature.

  • RAINFALL – System-wide rainfall rate.

  • SNOW_DEPTH – Average snow depth.

  • EVAP – System-wide evaporation rate.

  • INFIL – System-wide infiltration rate.

  • RUNOFF – System-wide runoff rate.

  • DW_INFLOW – Dry-weather inflow rate.

  • GW_INFLOW – Groundwater inflow rate.

  • LAT_INFLOW – Total lateral inflow rate.

  • FLOODING – Total flooding rate.

  • OUTFLOW – Total outfall outflow rate.

  • STORAGE – Total network storage volume.

  • EVAP_TOTAL – Actual evaporation rate.

  • PET – Potential evapotranspiration rate.

TEMPERATURE = 0
RAINFALL = 1
SNOW_DEPTH = 2
EVAP = 3
INFIL = 4
RUNOFF = 5
DW_INFLOW = 6
GW_INFLOW = 7
LAT_INFLOW = 8
FLOODING = 9
OUTFLOW = 10
STORAGE = 11
EVAP_TOTAL = 12
PET = 13
class OutfallType(*values)

Bases: IntEnum

Outfall boundary condition type.

FREE = 0
NORMAL = 1
FIXED = 2
TIDAL = 3
TIMESERIES = 4
class OutletRatingType(*values)

Bases: IntEnum

Outlet rating-curve classification.

Mirrors SWMM_OutletRatingType in openswmm_links.h.

FUNCTIONAL_HEAD = 0
FUNCTIONAL_DEPTH = 1
TABULAR_HEAD = 2
TABULAR_DEPTH = 3
class PatternType(*values)

Bases: IntEnum

Time pattern type.

Variables:

  • MONTHLY – Monthly variation pattern.

  • DAILY – Daily variation pattern.

  • HOURLY – Hourly variation pattern.

  • WEEKEND – Weekend hourly variation pattern.

MONTHLY = 0
DAILY = 1
HOURLY = 2
WEEKEND = 3
class RouteModel(*values)

Bases: IntEnum

Hydraulic routing models.

Variables:

  • STEADY – Steady-state routing.

  • KINWAVE – Kinematic wave routing.

  • DYNWAVE – Dynamic wave (full Saint-Venant) routing.

STEADY = 0
KINWAVE = 1
DYNWAVE = 2
class RoutingTotal(*values)

Bases: IntEnum

Routing mass balance component codes.

Variables:

  • DRY_WEATHER – Dry-weather inflow.

  • WET_WEATHER – Wet-weather (runoff) inflow.

  • GW_INFLOW – Groundwater inflow.

  • RDII – RDII inflow.

  • EXTERNAL – External inflow.

  • FLOODING – Flooding loss.

  • OUTFLOW – Outfall outflow.

  • EVAP_LOSS – Evaporation loss.

  • SEEP_LOSS – Seepage loss.

  • INIT_STORAGE – Initial network storage.

  • FINAL_STORAGE – Final network storage.

DRY_WEATHER = 0
WET_WEATHER = 1
GW_INFLOW = 2
RDII = 3
EXTERNAL = 4
FLOODING = 5
OUTFLOW = 6
EVAP_LOSS = 7
SEEP_LOSS = 8
INIT_STORAGE = 9
FINAL_STORAGE = 10
class RunoffTotal(*values)

Bases: IntEnum

Runoff mass balance component codes.

Variables:

  • RAINFALL – Total rainfall.

  • EVAP – Evaporation loss.

  • INFIL – Infiltration loss.

  • RUNOFF – Surface runoff.

  • SNOWREMOV – Snow removal.

  • INITSTORE – Initial surface storage.

  • FINALSTORE – Final surface storage.

RAINFALL = 0
EVAP = 1
INFIL = 2
RUNOFF = 3
SNOWREMOV = 4
INITSTORE = 5
FINALSTORE = 6
class WarnCode(*values)

Bases: IntEnum

Engine warning codes emitted via the warning callback.

Variables:

  • NONE – No warning.

  • HOTSTART_MISSING – Object missing during hot start application.

  • UNKNOWN_SECTION – Unrecognised input section encountered.

  • UNKNOWN_OPTION – Unrecognised option keyword.

  • DEPRECATED_KW – Deprecated keyword used.

  • PLUGIN_INIT – Plugin initialisation issue.

  • NUMERICAL – Numerical instability handled gracefully.

  • STABILITY_LIMIT – Timestep limited by stability criterion.

NONE = 0
HOTSTART_MISSING = 1
UNKNOWN_SECTION = 2
UNKNOWN_OPTION = 3
DEPRECATED_KW = 4
PLUGIN_INIT = 5
NUMERICAL = 6
STABILITY_LIMIT = 7
class WashoffFunc(*values)

Bases: IntEnum

Pollutant washoff function type.

Variables:

  • NONE – No washoff.

  • EXP – Exponential washoff.

  • RC – Rating curve washoff.

  • EMC – Event mean concentration.

NONE = 0
EXP = 1
RC = 2
EMC = 3
class WeirType(*values)

Bases: IntEnum

Weir flow classification.

Mirrors SWMM_WeirType in openswmm_links.h.

TRANSVERSE = 0
SIDEFLOW = 1
VNOTCH = 2
TRAPEZOIDAL = 3
ROADWAY = 4
class XSectShape(*values)

Bases: IntEnum

Cross-section shape codes.

Variables:

  • CIRCULAR – Circular pipe.

  • FILLED_CIRCULAR – Filled circular pipe.

  • RECT_CLOSED – Closed rectangular.

  • RECT_OPEN – Open rectangular.

  • TRAPEZOIDAL – Trapezoidal channel.

  • TRIANGULAR – Triangular channel.

  • PARABOLIC – Parabolic channel.

  • POWER – Power-law shaped channel.

  • MODBASKETHANDLE – Modified baskethandle.

  • EGGSHAPED – Egg-shaped pipe.

  • HORSESHOE – Horseshoe-shaped pipe.

  • GOTHIC – Gothic arch pipe.

  • CATENARY – Catenary-shaped pipe.

  • SEMIELLIPTICAL – Semi-elliptical pipe.

  • BASKETHANDLE – Baskethandle-shaped pipe.

  • SEMICIRCULAR – Semi-circular pipe.

  • IRREGULAR – Irregular (from transect data).

  • CUSTOM – Custom shape (from shape curve).

  • FORCE_MAIN – Force main (pressurized).

CIRCULAR = 0
FILLED_CIRCULAR = 1
RECT_CLOSED = 2
RECT_OPEN = 3
TRAPEZOIDAL = 4
TRIANGULAR = 5
PARABOLIC = 6
POWER = 7
MODBASKETHANDLE = 8
EGGSHAPED = 9
HORSESHOE = 10
GOTHIC = 11
CATENARY = 12
SEMIELLIPTICAL = 13
BASKETHANDLE = 14
SEMICIRCULAR = 15
IRREGULAR = 16
CUSTOM = 17
FORCE_MAIN = 18

Optional modules#

These extensions are only built when the matching CMake flag is enabled on the parent C/C++ engine. They expose HAS_* flags at runtime so client code can degrade gracefully.

GeoPackage I/O (OPENSWMM_WITH_GEOPACKAGE=ON)#

GeoPackage Access#
author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._geopackage.

The GeoPackage class provides read/write access to SWMM GeoPackage databases for querying multi-run simulation results, importing observed data, and performing spatial analysis.

This module is optional - it is only available when the package is built with OPENSWMM_WITH_GEOPACKAGE=ON.

class GeoPackage(path)#

Bases: object

GeoPackage database access for SWMM models, results, and observed data.

Wraps the swmm_gpkg_* entry points of the OpenSWMM GeoPackage plugin. Supports the context-manager protocol for automatic resource cleanup.

Example:

from openswmm.engine import GeoPackage

with GeoPackage("model.gpkg") as gpkg:
    sims = gpkg.simulation_ids()
    times, depths = gpkg.read_result_ts(
        sims[0], "NODE", "J1", "depth")
Variables:

last_error – The most recent error message reported by the underlying GeoPackage library.

Parameters:

path (str)

Open a GeoPackage file.

Parameters:

path (str) – Path to the .gpkg file.

Raises:

RuntimeError – If the file cannot be opened.

__init__(path)#

Open a GeoPackage file.

Parameters:

path (str) – Path to the .gpkg file.

Raises:

RuntimeError – If the file cannot be opened.

Return type:

None

begin()#

Begin a transaction for bulk operations.

Raises:

RuntimeError – If the transaction cannot be started.

Return type:

None

close()#

Close the database connection.

Calling close more than once is harmless.

Return type:

None

commit()#

Commit the current transaction.

Raises:

RuntimeError – If the commit fails.

Return type:

None

create_observed_series(name, variable, obj_type='', obj_id='', source='', units='')#

Create an observed-data series.

Parameters:

  • name (str) – Unique series name.

  • variable (str) – Variable being measured.

  • obj_type (str) – Model object type for linking, or "" for none.

  • obj_id (str) – Model object ID for linking, or "" for none.

  • source (str) – Data source description, or "" for none.

  • units (str) – Measurement units, or "" for none.

Returns:

Series ID (M{>= 0}).

Return type:

int

Raises:

RuntimeError – If the series cannot be created.

property last_error: str#

The last error message from the GeoPackage library.

Returns:

Error message string, or "" if no error has been reported.

Return type:

str

object_counts(sim_id)#

Return model object counts for a simulation.

Parameters:

sim_id (str) – Simulation identifier.

Returns:

Dict with keys "nodes", "links", "subcatchments", and "gages".

Return type:

dict

observed_series_count()#

Return the number of observed-data series.

Returns:

Observed-series count.

Return type:

int

observed_value_count(series_id)#

Return the number of values in an observed series.

Parameters:

series_id (int) – Series ID.

Returns:

Value count.

Return type:

int

query_double(sql)#

Execute a read-only SQL query and return the first double result.

Parameters:

sql (str) – SELECT query string.

Returns:

Double-precision result of the query.

Return type:

float

Raises:

RuntimeError – If the query fails.

query_int(sql)#

Execute a read-only SQL query and return the first integer result.

Parameters:

sql (str) – SELECT query string.

Returns:

Integer result of the query.

Return type:

int

read_observed_values(series_id)#

Read observed-timeseries values. GIL is released for the duration of the SQL read.

Parameters:

series_id (int) – Series ID.

Returns:

Tuple (timestamps, values) where timestamps is a list of ISO 8601 strings and values is a NumPy float64 array.

Return type:

Tuple[List[str], np.ndarray]

read_result_ts(sim_id, obj_type, obj_id, variable)#

Read a result timeseries as NumPy arrays. GIL is released for the duration of the SQL execution.

Parameters:

  • sim_id (str) – Simulation identifier.

  • obj_type (str) – One of "NODE", "LINK", "SUBCATCH", or "SYSTEM".

  • obj_id (str) – Object identifier.

  • variable (str) – Variable name.

Returns:

Tuple (times, values) as NumPy float64 arrays.

Return type:

Tuple[np.ndarray, np.ndarray]

@see: L{result_ts_count}

read_summary(sim_id, obj_type, obj_id, variable)#

Read a single summary statistic value.

Parameters:

  • sim_id (str) – Simulation identifier.

  • obj_type (str) – One of "NODE", "LINK", or "SUBCATCH".

  • obj_id (str) – Object identifier.

  • variable (str) – Variable name (e.g. "max_depth").

Returns:

Statistic value.

Return type:

float

Raises:

KeyError – If the summary record is not found.

result_ts_count(sim_id, obj_type, obj_id, variable)#

Return the number of result timeseries records for a query.

Parameters:

  • sim_id (str) – Simulation identifier.

  • obj_type (str) – One of "NODE", "LINK", "SUBCATCH", or "SYSTEM".

  • obj_id (str) – Object identifier (e.g. "J1").

  • variable (str) – Variable name (e.g. "depth", "flow").

Returns:

Record count.

Return type:

int

rollback()#

Roll back the current transaction.

Raises:

RuntimeError – If the rollback fails.

Return type:

None

simulation_count()#

Return the number of simulation runs in the file.

Returns:

Simulation count.

Return type:

int

simulation_ids()#

Return all simulation IDs as a list of strings.

Returns:

List of simulation identifier strings.

Return type:

List[str]

topology_edge_count(sim_id)#

Return the number of topology edges for a simulation.

Parameters:

sim_id (str) – Simulation identifier.

Returns:

Topology edge count.

Return type:

int

variable_count()#

Return the number of output variables defined.

Returns:

Variable count.

Return type:

int

write_observed_value(series_id, timestamp, value, flag='')#

Write a single observed data point.

Parameters:

  • series_id (int) – Series ID returned by create_observed_series.

  • timestamp (str) – ISO 8601 timestamp string.

  • value (float) – Measured value.

  • flag (str) – Quality flag (e.g. "A", "P"), or "" for none.

Raises:

RuntimeError – If the write fails.

Return type:

None

write_observed_values(series_id, timestamps, values, flags=None)#

Bulk-write observed data points. GIL is released for the duration of the bulk SQL insert.

For best performance wrap the call in a transaction:

gpkg.begin()
gpkg.write_observed_values(sid, timestamps, values)
gpkg.commit()
Parameters:

  • series_id (int) – Series ID.

  • timestamps (List[str]) – List of ISO 8601 timestamp strings.

  • values (npt.ArrayLike) – List or NumPy array of values.

  • flags (Optional[List[str]]) – Optional list of quality-flag strings, one per timestamp.

Raises:
Return type:

None

is_registered()#

Check whether the GeoPackage plugin is registered.

Returns:

True if registered.

Return type:

bool

register(key='', org='', email='', deploy='')#

Register the GeoPackage plugin.

Parameters:

  • key (str) – License key, or "" if not required.

  • org (str) – Organisation name, or "".

  • email (str) – Contact e-mail, or "".

  • deploy (str) – Deployment identifier, or "".

Returns:

True if registration succeeded.

Return type:

bool

2-D surface routing (OPENSWMM_BUILD_2D=ON)#

2D Surface Routing#
author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Type stubs for openswmm.engine._2d.

The Surface2D class provides read/write access to the optional 2D surface routing module (requires OPENSWMM_BUILD_2D=ON and SUNDIALS).

class Surface2D(engine_ptr)#

Bases: object

Read/write interface to the optional 2D surface routing module.

The module solves the depth-averaged shallow-water equations on an unstructured triangular mesh and is integrated in time with CVODE from SUNDIALS. Two-way coupling with the 1D drainage network is supported per-vertex and per-triangle.

Example:

from openswmm.engine import Solver
from openswmm.engine._2d import Surface2D

with Solver("model.inp", "model.rpt", "model.out") as s:
    mesh = Surface2D(s.handle)
    if mesh.is_active:
        depths = mesh.get_depths()
Variables:

_engine – Internal pointer to the underlying C{SWMM_Engine} handle (managed by the Cython extension).

Parameters:

engine_ptr (int)

Construct a Surface2D accessor from a raw engine handle.

Parameters:

engine_ptr (int) – The raw engine handle (SWMM_Engine cast to an integer via solver.handle).

__init__(engine_ptr)#

Construct a Surface2D accessor from a raw engine handle.

Parameters:

engine_ptr (int) – The raw engine handle (SWMM_Engine cast to an integer via solver.handle).

Return type:

None

property abs_tolerance: float#

CVODE absolute tolerance.

Returns:

Absolute tolerance.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property boundary_edge_count: int#

Number of boundary edges in the 2D mesh.

Returns:

Boundary edge count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

property cvode_last_step: float#

Last CVODE internal step size.

Returns:

Step size.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property cvode_steps: int#

Number of CVODE internal steps in the last advance.

Returns:

Step count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

property dry_depth: float#

Dry-depth threshold (m); triangles below this are treated as dry.

Returns:

Threshold depth.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

force_clear_all()#

Clear all 2D forcings.

Raises:

RuntimeError – If the C API call fails.

Return type:

None

force_coupling_flux(idx, value, mode=1, persist=0)#

Force a coupling flux on a specific triangle.

Parameters:

  • idx (int) – Triangle index.

  • value (float) – Coupling flux value.

  • mode (int) – Forcing mode (1 = ADD, 0 = REPLACE).

  • persist (int) – 1 to hold until cleared; 0 for single-step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_rainfall(idx, value, mode=1, persist=0)#

Force rainfall on a specific triangle.

Parameters:

  • idx (int) – Triangle index.

  • value (float) – Rainfall rate.

  • mode (int) – Forcing mode (1 = ADD, 0 = REPLACE).

  • persist (int) – 1 to hold until cleared; 0 for single-step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_rainfall_uniform(value, mode=1, persist=0)#

Force uniform rainfall on all triangles.

Parameters:

  • value (float) – Rainfall rate.

  • mode (int) – Forcing mode (1 = ADD, 0 = REPLACE).

  • persist (int) – 1 to hold until cleared; 0 for single-step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

get_coupling_flux(idx)#

Return the coupling flux at a specific triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Coupling flux value (positive = into 2D surface).

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_coupling_fluxes()#

Return coupling fluxes for all triangles as a NumPy array. GIL is released during the C call.

Returns:

Array of shape (n_triangles,) with dtype float64. Positive values denote flux into the 2D surface.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_depth(idx)#

Return the water depth at a specific triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Water depth.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_depths()#

Return depths for all triangles as a NumPy array. GIL is released during the C call.

Returns:

Array of shape (n_triangles,) with dtype float64.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_edge_bc_cum_flux(tri_idx, edge)#

Return the cumulative boundary flux for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

Returns:

Cumulative boundary flux through the edge.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_edge_bc_head(tri_idx, edge)#

Return the boundary head for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

Returns:

Boundary head value.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_edge_bc_slope(tri_idx, edge)#

Return the boundary slope for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

Returns:

Boundary slope.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_edge_bc_type(tri_idx, edge)#

Return the boundary condition type for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

Returns:

Boundary condition type code.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

get_edge_flux_bulk()#

Return normal edge fluxes for all triangle edges. GIL is released during the C call.

Indexed as [tri*3 + localEdge].

Returns:

Array of shape (n_triangles*3,) with dtype float64.

Return type:

ndarray[tuple[Any, …], dtype[float64]]

get_edge_geometry_bulk()#

Return time-invariant edge lengths and outward unit normal components. GIL is released during the C call.

Returns (length, nx, ny), each indexed as [tri*3 + localEdge].

Returns:

Tuple (length, nx, ny), each of shape (n_triangles*3,).

Return type:

tuple[ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]], ndarray[tuple[Any, …], dtype[float64]]]

get_head(idx)#

Return the total head at a specific triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Total head.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_heads()#

Return total heads for all triangles as a NumPy array. GIL is released during the C call.

Returns:

Array of shape (n_triangles,) with dtype float64.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_net_source(idx)#

Return the net source term at a specific triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Net source term.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_rainfall(idx)#

Return the current rainfall at a specific triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Rainfall rate.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_stat_max_depths()#

Return cumulative maximum-depth statistics for all triangles.

Returns:

Array of shape (n_triangles,) with dtype float64.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_triangle_area(idx)#

Return the area of a triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Triangle area in project units squared.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_triangle_centroid(idx)#

Return the (cx, cy, cz) centroid coordinates for a triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Tuple (cx, cy, cz) centroid coordinates.

Return type:

tuple[float, float, float]

Raises:

RuntimeError – If the C API call fails.

get_triangle_coupled_node(tri_idx)#

Return the SWMM node index coupled to a triangle.

Parameters:

tri_idx (int) – Triangle index.

Returns:

Node index, or -1 if no coupling exists.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

get_triangle_mannings(idx)#

Return Manning’s M{n} for a triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Manning’s M{n} roughness.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_triangle_neighbours(idx)#

Return the (n0, n1, n2) neighbour triangle indices.

Parameters:

idx (int) – Triangle index.

Returns:

Tuple of three neighbour triangle indices; C{-1} indicates a boundary edge.

Return type:

tuple[int, int, int]

Raises:

RuntimeError – If the C API call fails.

get_triangle_vertices(idx)#

Return the (v0, v1, v2) vertex indices for a triangle.

Parameters:

idx (int) – Triangle index.

Returns:

Tuple of three vertex indices.

Return type:

tuple[int, int, int]

Raises:

RuntimeError – If the C API call fails.

get_vertex_coords()#

Return (x, y, z) NumPy arrays for all vertices. GIL is released during the C call.

Returns:

Tuple (x, y, z), each of shape (n_vertices,) with dtype float64.

Return type:

tuple[np.ndarray, np.ndarray, np.ndarray]

Raises:

RuntimeError – If the C API call fails.

get_vertex_coupled_node(vertex_idx)#

Return the SWMM node index coupled to a vertex.

Parameters:

vertex_idx (int) – Vertex index.

Returns:

Node index, or -1 if no coupling exists.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

get_vertex_heads()#

Return reconstructed heads at all vertices as a NumPy array. GIL is released during the C call.

Returns:

Array of shape (n_vertices,) with dtype float64.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

property is_active: bool#

True if the 2D module is active for this simulation.

Returns:

Activation flag.

Return type:

bool

Raises:

RuntimeError – If the C API call fails.

property max_depth: float#

Maximum depth across all triangles.

Returns:

Maximum depth.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property n_triangles: int#

Number of mesh triangles.

Returns:

Triangle count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

property n_vertices: int#

Number of mesh vertices.

Returns:

Vertex count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

property rel_tolerance: float#

CVODE relative tolerance.

Returns:

Relative tolerance.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

set_edge_bc_head(tri_idx, edge, head)#

Set the boundary head for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

  • head (float) – Boundary head value.

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_edge_bc_slope(tri_idx, edge, slope)#

Set the boundary slope for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

  • slope (float) – Boundary slope.

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_edge_bc_type(tri_idx, edge, bc_type)#

Set the boundary condition type for a triangle edge.

Parameters:

  • tri_idx (int) – Triangle index.

  • edge (int) – Edge index in 0-2.

  • bc_type (int) – Boundary condition type code.

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_vertex_z(idx, z)#

Set the ground elevation of a mesh vertex.

Updates derived geometry for every triangle incident to this vertex (centroid Z, per-edge midpoint Z). XY-derived fields are unaffected. When called during a running simulation, solver state (head, depth) is intentionally not rewritten — the implied depth = head - bed therefore changes by the same amount as bed.

Parameters:

  • idx (int) – Vertex index (0-based).

  • z (float) – New ground elevation (project vertical units).

Raises:

RuntimeError – If the C API call fails.

Return type:

None

property total_exchange_flow: float#

Total exchange flow rate.

Returns:

Exchange flow rate in m^3/s (positive = into 1D network).

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property total_volume: float#

Total 2D surface volume (sum of M{depth x area}).

Returns:

Total volume.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property triangle_coupling_count: int#

Number of triangle-to-node coupling points.

Returns:

Coupling count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

property vertex_coupling_count: int#

Number of vertex-to-node coupling points.

Returns:

Coupling count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

Legacy SWMM 5 — compatibility layer#

The openswmm.legacy.engine and openswmm.legacy.output subpackages preserve the original EPA SWMM 5.x C solver and binary-output reader verbatim for backward compatibility with existing scripts. No new development happens here; new projects should prefer openswmm.engine (above).

See also

Legacy SWMM 5 — Compatibility Layer — task-oriented guide for the legacy layer.

Migrating from SWMM 5 to v6 — translating legacy patterns to the OpenSWMM 6 API.

openswmm.legacy.engine — SWMM 5.x solver#

openswmm.legacy.engine#

Legacy EPA SWMM 5.x solver bindings (Cython).

This subpackage provides the Solver class for running SWMM simulations, enumeration types for object/property access, and utility functions for date encoding and version queries.

class SWMMObjects(*values)#

Bases: Enum

Enumeration of SWMM objects.

Variables:

  • RAIN_GAGE – Raingage object

  • SUBCATCHMENT – Subcatchment object

  • NODE – Node object

  • LINK – Link object

  • AQUIFER – Aquifer object

  • SNOWPACK – Snowpack object

  • UNIT_HYDROGRAPH – Unit hydrograph object

  • LID – LID object

  • STREET – Street object

  • INLET – Inlet object

  • TRANSECT – Transect object

  • XSECTION_SHAPE – Cross-section shape object

  • CONTROL_RULE – Control rule object

  • POLLUTANT – Pollutant object

  • LANDUSE – Land use object

  • CURVE – Curve object

  • TIMESERIES – Time series object

  • TIME_PATTERN – Time pattern object

  • SYSTEM – System object

RAIN_GAGE = Ellipsis#
SUBCATCHMENT = Ellipsis#
NODE = Ellipsis#
AQUIFER = Ellipsis#
SNOWPACK = Ellipsis#
UNIT_HYDROGRAPH = Ellipsis#
LID = Ellipsis#
STREET = Ellipsis#
INLET = Ellipsis#
TRANSECT = Ellipsis#
XSECTION_SHAPE = Ellipsis#
CONTROL_RULE = Ellipsis#
POLLUTANT = Ellipsis#
LANDUSE = Ellipsis#
CURVE = Ellipsis#
TIMESERIES = Ellipsis#
TIME_PATTERN = Ellipsis#
SYSTEM = Ellipsis#
class SWMMNodeTypes(*values)#

Bases: Enum

Enumeration of SWMM node types.

Variables:

  • JUNCTION – Junction node

  • OUTFALL – Outfall node

  • STORAGE – Storage node

  • DIVIDER – Divider node

JUNCTION = Ellipsis#
OUTFALL = Ellipsis#
STORAGE = Ellipsis#
DIVIDER = Ellipsis#
class SWMMLinkTypes(*values)#

Bases: Enum

Enumeration of SWMM link types.

Variables:

  • CONDUIT – Conduit link

  • PUMP – Pump link

  • ORIFICE – Orifice link

  • WEIR – Weir link

  • OUTLET – Outlet link

CONDUIT = Ellipsis#
PUMP = Ellipsis#
ORIFICE = Ellipsis#
WEIR = Ellipsis#
OUTLET = Ellipsis#
class SWMMRainGageProperties(*values)#

Bases: Enum

Enumeration of SWMM raingage properties.

Variables:

  • GAGE_TOTAL_PRECIPITATION – Total precipitation

  • GAGE_RAINFALL – Rainfall

  • GAGE_SNOWFALL – Snowfall

GAGE_TOTAL_PRECIPITATION = Ellipsis#
GAGE_RAINFALL = Ellipsis#
GAGE_SNOWFALL = Ellipsis#
class SWMMSubcatchmentProperties(*values)#

Bases: Enum

Enumeration of SWMM subcatchment properties.

Variables:

  • AREA – Area

  • RAINGAGE – Raingage

  • RAINFALL – Rainfall

  • EVAPORATION – Evaporation

  • INFILTRATION – Infiltration

  • RUNOFF – Runoff

  • REPORT_FLAG – Report flag

  • WIDTH – Width

  • SLOPE – Slope

  • CURB_LENGTH – Curb length

  • API_RAINFALL – API Rainfall

  • API_SNOWFALL – API Snowfall

  • POLLUTANT_BUILDUP – Pollutant buildup

  • EXTERNAL_POLLUTANT_BUILDUP – External pollutant buildup

  • POLLUTANT_RUNOFF_CONCENTRATION – Pollutant runoff concentration

  • POLLUTANT_PONDED_CONCENTRATION – Pollutant ponded concentration

  • POLLUTANT_TOTAL_LOAD – Pollutant total load

AREA = Ellipsis#
RAINGAGE = Ellipsis#
RAINFALL = Ellipsis#
EVAPORATION = Ellipsis#
INFILTRATION = Ellipsis#
RUNOFF = Ellipsis#
REPORT_FLAG = Ellipsis#
WIDTH = Ellipsis#
SLOPE = Ellipsis#
OUTLET_TYPE = Ellipsis#
OUTLET_INDEX = Ellipsis#
INFILTRATION_MODEL = Ellipsis#
FRACTION_IMPERVIOUS = Ellipsis#
SUB_AREA_ROUTE_TO = Ellipsis#
SUB_AREA_FRACTION_OUTLET = Ellipsis#
SUB_AREA_MANNINGS_N = Ellipsis#
SUB_AREA_FRACTION_AREA = Ellipsis#
SUB_AREA_DEPRESSION_STORAGE = Ellipsis#
SUB_AREA_INFLOW = Ellipsis#
SUB_AREA_RUNOFF = Ellipsis#
SUB_AREA_DEPTH = Ellipsis#
LID_UNITS_COUNT = Ellipsis#
LID_UNITS_PERV_AREA = Ellipsis#
LID_UNITS_FLOW_TO_PERV_AREA = Ellipsis#
LID_UNITS_DRAIN_FLOW = Ellipsis#
LID_UNIT_REPLICATES = Ellipsis#
LID_UNIT_AREA = Ellipsis#
LID_UNIT_FULL_WIDTH = Ellipsis#
LID_UNIT_BOTTOM_WIDTH = Ellipsis#
LID_UNIT_INIT_SATURATION = Ellipsis#
LID_UNIT_FROM_IMPERVIOUS = Ellipsis#
LID_UNIT_FROM_PERVIOUS = Ellipsis#
LID_UNIT_TO_PERVIOUS = Ellipsis#
LID_UNIT_RECEIVING_OUTLET_TYPE = Ellipsis#
LID_UNIT_RECEIVING_OUTLET_INDEX = Ellipsis#
LID_UNIT_SURFACE_DEPTH = Ellipsis#
LID_UNIT_SOIL_MOISTURE = Ellipsis#
LID_UNIT_GREEN_AMPT_CAPILLARY_SUCTION = Ellipsis#
LID_UNIT_GREEN_AMPT_SATURATED_CONDUCTIVITY = Ellipsis#
LID_UNIT_GREEN_AMPT_MAX_SOIL_MOISTURE_DEFICIT = Ellipsis#
CURB_LENGTH = Ellipsis#
API_RAINFALL = Ellipsis#
API_SNOWFALL = Ellipsis#
POLLUTANT_BUILDUP = Ellipsis#
EXTERNAL_POLLUTANT_BUILDUP = Ellipsis#
POLLUTANT_RUNOFF_CONCENTRATION = Ellipsis#
POLLUTANT_PONDED_CONCENTRATION = Ellipsis#
POLLUTANT_TOTAL_LOAD = Ellipsis#
class SWMMNodeProperties(*values)#

Bases: Enum

Enumeration of SWMM node properties.

Variables:

  • TYPE – Node type

  • INVERT_ELEVATION – Invert elevation

  • MAX_DEPTH – Maximum depth

  • DEPTH – Depth

  • HYDRAULIC_HEAD – Hydraulic head

  • VOLUME – Volume

  • LATERAL_INFLOW – Lateral inflow

  • TOTAL_INFLOW – Total inflow

  • FLOODING – Flooding

  • REPORT_FLAG – Report flag

  • SURCHARGE_DEPTH – Surcharge depth

  • PONDING_AREA – Ponding area

  • INITIAL_DEPTH – Initial depth

  • POLLUTANT_CONCENTRATION – Pollutant concentration

  • POLLUTANT_LATERAL_MASS_FLUX – Pollutant lateral mass flux

  • OUTFLOW – Total outflow through downstream links

TYPE = Ellipsis#
INVERT_ELEVATION = Ellipsis#
MAX_DEPTH = Ellipsis#
DEPTH = Ellipsis#
HYDRAULIC_HEAD = Ellipsis#
VOLUME = Ellipsis#
LATERAL_INFLOW = Ellipsis#
TOTAL_INFLOW = Ellipsis#
FLOODING = Ellipsis#
REPORT_FLAG = Ellipsis#
SURCHARGE_DEPTH = Ellipsis#
PONDING_AREA = Ellipsis#
INITIAL_DEPTH = Ellipsis#
POLLUTANT_CONCENTRATION = Ellipsis#
POLLUTANT_LATERAL_MASS_FLUX = Ellipsis#
OUTFLOW = Ellipsis#
class SWMMLinkProperties(*values)#

Bases: Enum

Enumeration of SWMM link properties.

Variables:

  • TYPE – Link type

  • START_NODE – Start node

  • END_NODE – End node

  • LENGTH – Length

  • SLOPE – Slope

  • FULL_DEPTH – Full depth

  • FULL_FLOW – Full flow

  • SETTING – Setting

  • TIME_OPEN – Time open

  • TIME_CLOSED – Time closed

  • FLOW – Flow

  • DEPTH – Depth

  • VELOCITY – Velocity

  • TOP_WIDTH – Top width

  • REPORT_FLAG – Report flag

  • START_NODE_OFFSET – Start node offset

  • END_NODE_OFFSET – End node offset

  • INITIAL_FLOW – Initial flow

  • FLOW_LIMIT – Flow limit

  • INLET_LOSS – Inlet loss

  • OUTLET_LOSS – Outlet loss

  • AVERAGE_LOSS – Average loss

  • SEEPAGE_RATE – Seepage rate

  • HAS_FLAPGATE – Has flapgate

  • POLLUTANT_CONCENTRATION – Pollutant concentration

  • POLLUTANT_LOAD – Pollutant load

  • POLLUTANT_LATERAL_MASS_FLUX – Pollutant lateral mass flux

TYPE = Ellipsis#
START_NODE = Ellipsis#
END_NODE = Ellipsis#
LENGTH = Ellipsis#
SLOPE = Ellipsis#
FULL_DEPTH = Ellipsis#
FULL_FLOW = Ellipsis#
SETTING = Ellipsis#
TIME_OPEN = Ellipsis#
TIME_CLOSED = Ellipsis#
FLOW = Ellipsis#
DEPTH = Ellipsis#
VELOCITY = Ellipsis#
TOP_WIDTH = Ellipsis#
VOLUME = Ellipsis#
CAPACITY = Ellipsis#
REPORT_FLAG = Ellipsis#
START_NODE_OFFSET = Ellipsis#
END_NODE_OFFSET = Ellipsis#
INITIAL_FLOW = Ellipsis#
FLOW_LIMIT = Ellipsis#
INLET_LOSS = Ellipsis#
OUTLET_LOSS = Ellipsis#
AVERAGE_LOSS = Ellipsis#
SEEPAGE_RATE = Ellipsis#
HAS_FLAPGATE = Ellipsis#
POLLUTANT_CONCENTRATION = Ellipsis#
POLLUTANT_LOAD = Ellipsis#
POLLUTANT_LATERAL_MASS_FLUX = Ellipsis#
class SWMMSystemProperties(*values)#

Bases: Enum

Enumeration of SWMM system properties.

Variables:

  • START_DATE – Start date for the simulation

  • CURRENT_DATE – Current date for the simulation

  • ELAPSED_TIME – Elapsed time for the simulation

  • ROUTING_STEP – Routing time step

  • MAX_ROUTING_STEP – Maximum routing time step

  • REPORT_STEP – Report time step

  • TOTAL_STEPS – Total number of steps

  • NO_REPORT_FLAG – No report flag

  • FLOW_UNITS – Flow units

  • END_DATE – End date for the simulation

  • REPORT_START_DATE – Report start date

  • UNIT_SYSTEM – Unit system

  • SURCHARGE_METHOD – Surcharge method

  • ALLOW_PONDING – Allow ponding

  • INTERTIAL_DAMPING – Inertial damping

  • NORMAL_FLOW_LIMITED – Normal flow limited

  • SKIP_STEADY_STATE – Skip steady state

  • IGNORE_RAINFALL – Ignore rainfall

  • IGNORE_RDII – Ignore RDII

  • IGNORE_SNOWMELT – Ignore snowmelt

  • IGNORE_GROUNDWATER – Ignore groundwater

  • IGNORE_ROUTING – Ignore routing

  • IGNORE_QUALITY – Ignore quality

  • RULE_STEP – Rule step

  • SWEEP_START – Sweep start

  • SWEEP_END – Sweep end

  • MAX_TRIALS – Maximum trials

  • NUM_THREADS – Number of threads

  • MIN_ROUTE_STEP – Minimum routing step

  • LENGTHENING_STEP – Lengthening step

  • START_DRY_DAYS – Start dry days

  • COURANT_FACTOR – Courant factor

  • MIN_SURF_AREA – Minimum surface area

  • MIN_SLOPE – Minimum slope

  • RUNOFF_ERROR – Runoff error

  • FLOW_ERROR – Flow error

  • QUAL_ERROR – Quality error

  • HEAD_TOL – Head tolerance

  • SYS_FLOW_TOL – System flow tolerance

  • LAT_FLOW_TOL – Lateral flow tolerance

START_DATE = Ellipsis#
CURRENT_DATE = Ellipsis#
ELAPSED_TIME = Ellipsis#
ROUTING_STEP = Ellipsis#
MAX_ROUTING_STEP = Ellipsis#
REPORT_STEP = Ellipsis#
TOTAL_STEPS = Ellipsis#
NO_REPORT_FLAG = Ellipsis#
FLOW_UNITS = Ellipsis#
END_DATE = Ellipsis#
REPORT_START_DATE = Ellipsis#
UNIT_SYSTEM = Ellipsis#
SURCHARGE_METHOD = Ellipsis#
ALLOW_PONDING = Ellipsis#
INTERTIAL_DAMPING = Ellipsis#
NORMAL_FLOW_LIMITED = Ellipsis#
SKIP_STEADY_STATE = Ellipsis#
IGNORE_RAINFALL = Ellipsis#
IGNORE_RDII = Ellipsis#
IGNORE_SNOWMELT = Ellipsis#
IGNORE_GROUNDWATER = Ellipsis#
IGNORE_ROUTING = Ellipsis#
IGNORE_QUALITY = Ellipsis#
ERROR_CODE = Ellipsis#
RULE_STEP = Ellipsis#
SWEEP_START = Ellipsis#
SWEEP_END = Ellipsis#
MAX_TRIALS = Ellipsis#
NUM_THREADS = Ellipsis#
MIN_ROUTE_STEP = Ellipsis#
LENGTHENING_STEP = Ellipsis#
START_DRY_DAYS = Ellipsis#
COURANT_FACTOR = Ellipsis#
MIN_SURF_AREA = Ellipsis#
MIN_SLOPE = Ellipsis#
RUNOFF_ERROR = Ellipsis#
FLOW_ERROR = Ellipsis#
QUAL_ERROR = Ellipsis#
HEAD_TOL = Ellipsis#
SYS_FLOW_TOL = Ellipsis#
LAT_FLOW_TOL = Ellipsis#
class SWMMFlowUnits(*values)#

Bases: Enum

Enumeration of SWMM flow units.

Variables:

  • CFS – Cubic feet per second

  • GPM – Gallons per minute

  • MGD – Million gallons per day

  • CMS – Cubic meters per second

  • LPS – Liters per second

  • MLD – Million liters per day

CFS = Ellipsis#
GPM = Ellipsis#
MGD = Ellipsis#
CMS = Ellipsis#
LPS = Ellipsis#
MLD = Ellipsis#
class SWMMAPIErrors(*values)#

Bases: Enum

Enumeration of SWMM API errors.

Variables:

  • PROJECT_NOT_OPENED – Project not opened

  • SIMULATION_NOT_STARTED – Simulation not started

  • SIMULATION_NOT_ENDED – Simulation not ended

PROJECT_NOT_OPENED = Ellipsis#
SIMULATION_NOT_STARTED = Ellipsis#
SIMULATION_NOT_ENDED = Ellipsis#
OBJECT_TYPE = Ellipsis#
OBJECT_INDEX = Ellipsis#
OBJECT_NAME = Ellipsis#
PROPERTY_TYPE = Ellipsis#
PROPERTY_VALUE = Ellipsis#
TIME_PERIOD = Ellipsis#
HOTSTART_FILE_OPEN = Ellipsis#
HOTSTART_FILE_FORMAT = Ellipsis#
SIMULATION_IS_RUNNING = Ellipsis#
run_solver(inp_file, rpt_file=None, out_file=None, swmm_progress_callback=Ellipsis)#

Run a SWMM simulation with a progress callback.

Parameters:

  • inp_file (str) – Input file name

  • rpt_file (str | None) – Report file name

  • out_file (str | None) – Output file name

  • swmm_progress_callback (callable) – Progress callback function

Rtype inp_file:

str

Rtype rpt_file:

str

Rtype out_file:

str

Returns:

Error code from the underlying SWMM C API (0 on success, non-zero on failure). Callers should check the return value rather than relying on an exception.

Return type:

int

decode_swmm_datetime(swmm_datetime)#

Decode a SWMM datetime into a datetime object.

Parameters:

swmm_datetime (float) – SWMM datetime float value

Returns:

datetime object

Return type:

datetime

encode_swmm_datetime(dt)#

Encode a datetime object into a SWMM datetime float value.

Parameters:

dt (datetime) – datetime object

Returns:

SWMM datetime float value

Return type:

float

version()#

Get the SWMM version.

Returns:

SWMM version

Return type:

str

get_error_message(error_code)#

Get the error message for a SWMM error code.

Parameters:

error_code (int) – Error code

Returns:

Error message

Return type:

str

class SolverState(*values)#

Bases: Enum

An enumeration to represent the state of the solver.

CREATED = Ellipsis#
OPEN = Ellipsis#
STARTED = Ellipsis#
FINISHED = Ellipsis#
ENDED = Ellipsis#
REPORTED = Ellipsis#
CLOSED = Ellipsis#
class CallbackType(*values)#

Bases: Enum

An enumeration to represent the type of callback.

BEFORE_INITIALIZE = Ellipsis#
BEFORE_OPEN = Ellipsis#
AFTER_OPEN = Ellipsis#
BEFORE_START = Ellipsis#
AFTER_START = Ellipsis#
BEFORE_STEP = Ellipsis#
AFTER_STEP = Ellipsis#
BEFORE_END = Ellipsis#
AFTER_END = Ellipsis#
BEFORE_REPORT = Ellipsis#
AFTER_REPORT = Ellipsis#
BEFORE_CLOSE = Ellipsis#
AFTER_CLOSE = Ellipsis#
exception SWMMSolverException(message)#

Bases: Exception

Exception class for SWMM output file processing errors.

Constructor to initialize the exception message.

Parameters:

message (str) – Error message.

Return type:

None

__init__(message)#

Constructor to initialize the exception message.

Parameters:

message (str) – Error message.

Return type:

None

class Solver(inp_file, rpt_file=None, out_file=None, stride_step=300, save_results=True)#

Bases: object

Constructor to create a new SWMM solver.

Parameters:

  • inp_file (str) – Input file name

  • rpt_file (Optional[str]) – Report file name

  • out_file (Optional[str]) – Output file name

  • stride_step (int)

  • save_results (bool)

__init__(inp_file, rpt_file=None, out_file=None, stride_step=300, save_results=True)#

Constructor to create a new SWMM solver.

Parameters:

  • inp_file (str) – Input file name

  • rpt_file (str | None) – Report file name

  • out_file (str | None) – Output file name

  • stride_step (int)

  • save_results (bool)

Return type:

None

add_callback(callback_type, callback)#

Add a callback to the solver.

Parameters:

  • callback_type (CallbackType) – Type of callback

  • callback (callable) – Callback function

Return type:

None

add_progress_callback(callback)#

Add a progress callback to the solver.

Parameters:

callback (callable) – Progress callback function

Return type:

None

close()#

Close the solver.

Returns:

Error code (0 on success or no-op, non-zero on failure; -1 if not in REPORTED state).

Return type:

int

property current_datetime: datetime#

Get the current date of the simulation.

Returns:

Current date

Return type:

datetime

end()#

End the SWMM simulation.

Returns:

Error code (0 on success or no-op, non-zero on failure; -1 if called from an invalid solver state).

Return type:

int

property end_datetime: datetime#

Get the end date of the simulation.

Returns:

End date

Return type:

datetime

execute()#

Run the solver to completion.

Returns:

Error code (0 if successful)

Return type:

Any

finalize()#

Finalize the solver. Ends simulation, reports the results, and dispose objects.

Return type:

Any

Per-link post-simulation statistics.

Parameters:

index (int | str)

Return type:

dict[str, Any]

get_mass_balance_error()#

Get the mass balance error.

Returns:

Mass balance error

Return type:

Tuple[float, float, float]

get_node_statistics(index)#

Per-node post-simulation statistics.

Parameters:

index (int | str)

Return type:

dict[str, Any]

get_object_count(object_type)#

Get the count of a SWMM object type.

Parameters:

object_type (SWMMObjects) – SWMM object type

Returns:

Object count

Return type:

int

get_object_index(object_type, object_name)#

Get the index of a SWMM object.

Parameters:

  • object_type (SWMMObjects) – SWMM object type

  • object_name (str) – Object name

Returns:

Object index

Return type:

int

get_object_name(object_type, index)#

Get the name of a SWMM object.

Parameters:

  • object_type (SWMMObjects) – SWMM object type

  • index (int) – Object index

Returns:

Object name

Return type:

str

get_object_names(object_type)#

Get the names of all SWMM objects of a given type.

Parameters:

object_type (SWMMObjects) – SWMM object type

Returns:

Object names

Return type:

List[str]

get_pump_statistics(index)#

Per-pump post-simulation statistics.

Parameters:

index (int | str)

Return type:

dict[str, Any]

get_routing_totals()#

Get system-level flow routing mass balance totals.

Returns:

Dictionary with keys dw_inflow, ww_inflow, gw_inflow, ii_inflow, ex_inflow, flooding, outflow, evap_loss, seep_loss, reacted, init_storage, final_storage, pct_error.

Return type:

dict[str, float]

get_runoff_totals()#

Get system-level surface runoff mass balance totals.

Returns:

Dictionary with keys rainfall, evap, infil, runoff, drains, runon, init_storage, final_storage, init_snow_cover, final_snow_cover, snow_removed, pct_error.

Return type:

dict[str, float]

get_subcatchment_statistics(index)#

Per-subcatchment post-simulation statistics.

Parameters:

index (int | str)

Return type:

dict[str, Any]

get_value(object_type, property_type, index, sub_index=Ellipsis)#

Get a SWMM system property value.

Parameters:
Returns:

Property value

Return type:

double

initialize()#

Initialize the solver and start the simulation. Calls the open and start methods in the SWMM API.

Returns:

Error code (0 on success, non-zero from the first failing sub-call).

Return type:

int

open()#

Open the SWMM solver by calling the open method in the SWMM API.

Returns:

Error code (0 on success or no-op, non-zero on failure; -1 if called from an invalid solver state).

Return type:

int

property progress_callbacks_per_second: int#

Get the number of progress callbacks per second.

Returns:

Progress callbacks per second

Return type:

int

report()#

Report the results of the SWMM simulation.

Returns:

Error code (0 on success or no-op, non-zero on failure; -1 if not in ENDED state).

Return type:

int

property report_start_datetime: datetime#

Get the report start date of the simulation.

Returns:

Report start date

Return type:

datetime

property reporting_step: float#

Get the reporting time step of the simulation in seconds.

Returns:

Reporting time step

Return type:

double

property routing_step: float#

Get the routing time step of the simulation in seconds.

Returns:

Routing time step

Return type:

double

save_hotstart(hotstart_file)#

Save a hotstart file.

Parameters:

hotstart_file (str) – Hotstart file name

Return type:

Any

set_value(object_type, property_type, index, value, sub_index=Ellipsis)#

Set a SWMM system property value.

Parameters:
Return type:

None

property solver_state: SolverState#

Get the state of the solver.

Returns:

Solver state

Return type:

SolverState

start()#

Start the SWMM solver.

Returns:

Error code (0 on success or no-op, non-zero on failure; -1 if not in OPEN state).

Return type:

int

property start_datetime: datetime#

Get the start date of the simulation.

Returns:

Start date

Return type:

datetime

step(steps=Ellipsis)#

Step a SWMM simulation forward.

Parameters:

steps (int) – Number of steps to run. Overrides internal stride step if greater than 0.

Returns:

Error code (0 on success, non-zero on failure). The simulation transitions to the FINISHED state when complete; poll solver_state or read current_datetime for per-step data.

Return type:

int

property stride_step: int#

Get the stride step of the simulation.

Returns:

Stride step

Return type:

int

use_hotstart(hotstart_file)#

Use a hotstart file.

Parameters:

hotstart_file (str) – Hotstart file name

Return type:

Any

class LegacyNodes(solver)[source]#

Bases: object

Iterable collection of all SWMM nodes in the model.

Parameters:

solver (Solver)

class LegacyNode(solver, index, name='')[source]#

Bases: object

Property-based access to a single SWMM node.

Parameters:
property index: int#
property name: str#
property node_type: SWMMNodeTypes#
property invert_elevation: float#

Node invert elevation (project length units).

property max_depth: float#

Maximum water depth above invert (length units).

property surcharge_depth: float#

Additional depth allowed before flooding (length units).

property ponded_area: float#

Surface area used to compute ponded volume (area units).

property initial_depth: float#

Initial water depth at start of simulation.

property depth: float#

Current water depth above invert.

property head: float#

Current hydraulic head (invert + depth).

property volume: float#

Current stored volume.

property lateral_inflow: float#

Current lateral inflow rate.

property total_inflow: float#

Current total inflow rate (lateral + upstream).

property flooding: float#

Current flooding (overflow) rate.

property outflow: float#

Current total outflow through downstream links.

get_pollutant_concentration(pollutant_index=0)[source]#

Get pollutant concentration at this node.

Parameters:

pollutant_index (int) – 0-based pollutant index.

Return type:

float

set_lateral_inflow(flow, log=None)[source]#

Prescribe an external lateral inflow at this node.

Mass balance impact:

Adds flow to the node’s lateral inflow for the current timestep only. The value resets each step — call again to sustain. The injected volume appears in the routing mass balance under ex_inflow (external inflow).

Parameters:
Return type:

None

set_pollutant_lateral_mass_flux(value, pollutant_index=0, log=None)[source]#

Set pollutant lateral mass flux at this node.

Mass balance impact:

The mass flux = value (mass/time). This mass is added to the quality routing mass balance. Must be used together with set_lateral_inflow() for the mass to be transported.

Parameters:
Return type:

None

set_depth(value, log=None)[source]#

Override current water depth at this node.

Mass balance impact:

Directly changes stored volume — affects storage balance. Use with care: the volume difference is not automatically tracked as an inflow or outflow.

Parameters:
Return type:

None

property statistics: Dict[str, Any]#

Cumulative node statistics (call after solver.end()).

Bases: object

Iterable collection of all SWMM links in the model.

Parameters:

solver (Solver)

Bases: object

Property-based access to a single SWMM link.

Parameters:
property index: int#
property name: str#
property length: float#

Conduit length.

property slope: float#

Conduit slope.

property full_depth: float#

Full (maximum) depth.

property full_flow: float#

Full-pipe flow rate.

property start_node_offset: float#

Upstream invert offset.

property end_node_offset: float#

Downstream invert offset.

property initial_flow: float#

Initial flow at start of simulation.

property flow_limit: float#

User-specified flow limit.

property inlet_loss: float#
property outlet_loss: float#
property average_loss: float#
property seepage_rate: float#
property flow: float#

Current flow rate.

property depth: float#

Current flow depth.

property velocity: float#

Current flow velocity.

property volume: float#

Current volume in link.

property capacity: float#

Current capacity utilization (0-1).

property setting: float#

Current link control setting (0-1 for pumps/orifices/weirs).

get_pollutant_concentration(pollutant_index=0)[source]#
Parameters:

pollutant_index (int)

Return type:

float

set_setting(value, log=None)[source]#

Set the link control setting.

Mass balance impact:

Changes flow capacity — affects routing. For pumps this controls on/off (0 or 1). For orifices/weirs it controls the fraction open (0-1). For conduits this has no direct effect unless used with inlet control.

Parameters:
Return type:

None

set_flow(value, log=None)[source]#

Directly override the flow in this link.

Mass balance impact:

Bypasses hydraulic routing — the specified flow is used regardless of head difference. Use with extreme care as this can break mass balance if the override is inconsistent with node volumes.

Parameters:
Return type:

None

property statistics: Dict[str, Any]#

Cumulative link statistics (call after solver.end()).

property pump_statistics: Dict[str, Any]#

Cumulative pump statistics (only valid for PUMP links).

class LegacySubcatchments(solver)[source]#

Bases: object

Iterable collection of all SWMM subcatchments.

Parameters:

solver (Solver)

class LegacySubcatchment(solver, index, name='')[source]#

Bases: object

Property-based access to a single SWMM subcatchment.

Parameters:
property index: int#
property name: str#
property area: float#

Subcatchment area (project area units).

property width: float#

Characteristic width of overland flow.

property slope: float#

Average surface slope (%).

property curb_length: float#

Total curb length.

property fraction_impervious: float#

Fraction of impervious area (0-1).

property outlet_type: int#

Outlet type (0=node, 1=subcatchment).

property outlet_index: int#

Index of outlet node or subcatchment.

property infiltration_model: int#

Infiltration model code (0=Horton, 1=ModHorton, 2=GreenAmpt, etc.).

property rainfall: float#

Current rainfall intensity.

property evaporation: float#

Current evaporation rate.

property infiltration: float#

Current infiltration rate.

property runoff: float#

Current runoff flow rate.

get_subarea_mannings_n(sub_index)[source]#

Manning’s n for a subarea. sub_index: 0=impervious, 1=pervious.

Parameters:

sub_index (int)

Return type:

float

get_subarea_depression_storage(sub_index)[source]#

Depression storage for a subarea.

Parameters:

sub_index (int)

Return type:

float

get_subarea_runoff(sub_index)[source]#

Current runoff for a subarea.

Parameters:

sub_index (int)

Return type:

float

get_subarea_depth(sub_index)[source]#

Current depth for a subarea.

Parameters:

sub_index (int)

Return type:

float

property lid_units_count: int#

Number of LID units in this subcatchment.

get_lid_unit_area(lid_index)[source]#

Area of a specific LID unit.

Parameters:

lid_index (int)

Return type:

float

get_lid_unit_full_width(lid_index)[source]#

Full top width of a specific LID unit.

Parameters:

lid_index (int)

Return type:

float

get_lid_unit_surface_depth(lid_index)[source]#

Surface depth of a specific LID unit.

Parameters:

lid_index (int)

Return type:

float

get_lid_unit_soil_moisture(lid_index)[source]#

Soil moisture of a specific LID unit.

Parameters:

lid_index (int)

Return type:

float

get_pollutant_buildup(pollutant_index=0)[source]#

Current pollutant buildup on subcatchment.

Parameters:

pollutant_index (int)

Return type:

float

get_pollutant_runoff_concentration(pollutant_index=0)[source]#

Current pollutant concentration in runoff.

Parameters:

pollutant_index (int)

Return type:

float

get_pollutant_total_load(pollutant_index=0)[source]#

Total pollutant load washed off.

Parameters:

pollutant_index (int)

Return type:

float

set_api_rainfall(value, log=None)[source]#

Override rainfall for this subcatchment.

Mass balance impact:

Overrides the rainfall used in the runoff calculation for this subcatchment. The overridden value appears in the runoff totals under rainfall. Resets each timestep.

Parameters:
Return type:

None

set_api_snowfall(value, log=None)[source]#

Override snowfall for this subcatchment.

Mass balance impact:

Overrides the snowfall used in the snow accumulation/melt calculation. Affects the snow balance in runoff totals.

Parameters:
Return type:

None

set_external_pollutant_buildup(value, pollutant_index=0, log=None)[source]#

Add external pollutant buildup on this subcatchment.

Mass balance impact:

Adds pollutant mass to the surface. This mass is available for washoff and appears in the quality mass balance.

Parameters:
Return type:

None

property statistics: Dict[str, Any]#

Cumulative subcatchment statistics (call after solver.end()).

class LegacyRainGages(solver)[source]#

Bases: object

Iterable collection of all SWMM rain gages.

Parameters:

solver (Solver)

class LegacyRainGage(solver, index, name='')[source]#

Bases: object

Property-based access to a single SWMM rain gage.

Parameters:
property index: int#
property name: str#
property total_precipitation: float#

Current total precipitation (rainfall + snowfall).

property rainfall: float#

Current rainfall intensity.

property snowfall: float#

Current snowfall intensity.

set_rainfall(value, log=None)[source]#

Override rainfall at this gage.

Mass balance impact:

Overrides rainfall for all subcatchments linked to this gage. Appears in runoff totals under rainfall.

Parameters:
Return type:

None

class LegacySystem(solver)[source]#

Bases: object

System-level properties, simulation settings, and mass balance totals.

Wraps a Solver instance and provides convenient property-based access to global simulation parameters and post-simulation mass balance breakdowns.

Parameters:

solver (Solver)

property flow_units: SWMMFlowUnits#

Flow units used in this simulation.

property unit_system: int#

Unit system (0=US, 1=SI).

property routing_step: float#

Routing time step (seconds).

property report_step: float#

Reporting time step (seconds).

property total_steps: int#

Total number of routing steps.

property num_threads: int#

Number of threads for parallel computation.

property allow_ponding: bool#

Whether ponding is allowed at nodes.

property head_tolerance: float#

Head convergence tolerance (length units).

property sys_flow_tolerance: float#

System flow convergence tolerance.

property lat_flow_tolerance: float#

Lateral flow convergence tolerance.

property runoff_error: float#

Runoff continuity error (%).

property flow_error: float#

Flow routing continuity error (%).

property quality_error: float#

Quality routing continuity error (%).

property routing_totals: Dict[str, float]#

System-level flow routing mass balance totals.

Returns a dict with keys: dw_inflow, ww_inflow, gw_inflow, ii_inflow, ex_inflow, flooding, outflow, evap_loss, seep_loss, reacted, init_storage, final_storage, pct_error.

Mass balance equation:

total_inflow = dw + ww + gw + ii + ex
total_outflow = flooding + outflow + evap_loss + seep_loss
storage_change = final_storage - init_storage
balance = total_inflow - total_outflow - storage_change
property runoff_totals: Dict[str, float]#

System-level surface runoff mass balance totals.

Returns a dict with keys: rainfall, evap, infil, runoff, drains, runon, init_storage, final_storage, init_snow_cover, final_snow_cover, snow_removed, pct_error.

property mass_balance_error: Tuple[float, float, float]#

Mass balance errors as (runoff_err%, flow_err%, quality_err%).

class ExternalForcingLog[source]#

Bases: object

Append-only log that records external forcing applied during a simulation.

Each entry stores the simulation time, target object, property modified, and the value applied.

record(sim_time, object_type, object_id, property_name, value, mass_balance_category='')[source]#

Append a forcing record.

Parameters:

  • sim_time (datetime) – Current simulation datetime.

  • object_type (str) – E.g. "node", "link", "subcatchment".

  • object_id (str) – Object name or index string.

  • property_name (str) – Property that was set.

  • value (float) – The value applied.

  • mass_balance_category (str) – Which mass-balance bucket is affected.

Return type:

None

property records: List[Dict[str, Any]]#

Return the raw list of recorded forcing entries.

clear()[source]#

Remove all recorded entries.

Return type:

None

to_dataframe()[source]#

Convert to a pandas.DataFrame.

Columns: time, object_type, object_id, property, value, mass_balance_category.

Raises:

ImportError – If pandas is not installed.

Return type:

pd.DataFrame

openswmm.legacy.output — SWMM 5.x binary output reader#

The openswmm.legacy.output subpackage reads the binary .out file produced by either the legacy SWMM 5.x solver or the v6.0 engine.

openswmm.legacy.output#

Legacy EPA SWMM 5.x binary output file reader (Cython).

This subpackage provides the Output class for reading SWMM .out result files, and enumeration types for element and attribute access.

class UnitSystem(*values)#

Bases: Enum

Enumeration of the unit system used in the output file.

Variables:

  • US – US customary units.

  • SI – SI metric units.

US = Ellipsis#
SI = Ellipsis#
class FlowUnits(*values)#

Bases: Enum

Enumeration of the flow units used in the simulation.

Variables:

  • CFS – Cubic feet per second.

  • GPM – Gallons per minute.

  • MGD – Million gallons per day.

  • CMS – Cubic meters per second.

  • LPS – Liters per second.

  • MLD – Million liters per day.

CFS = Ellipsis#
GPM = Ellipsis#
MGD = Ellipsis#
CMS = Ellipsis#
LPS = Ellipsis#
MLD = Ellipsis#
class ConcentrationUnits(*values)#

Bases: Enum

Enumeration of the concentration units used in the simulation.

Variables:

  • MG – Milligrams per liter.

  • UG – Micrograms per liter.

  • COUNT – Counts per liter.

  • NONE – No units.

MG = Ellipsis#
UG = Ellipsis#
COUNT = Ellipsis#
NONE = Ellipsis#
class ElementType(*values)#

Bases: Enum

Enumeration of the SWMM element types.

Variables:

  • SUBCATCHMENT – Subcatchment.

  • NODE – Node.

  • LINK – Link.

  • SYS – System.

  • POLLUTANT – Pollutant.

SUBCATCHMENT = Ellipsis#
NODE = Ellipsis#
SYSTEM = Ellipsis#
POLLUTANT = Ellipsis#
class TimeAttribute(*values)#

Bases: Enum

Enumeration of the report time related attributes.

Variables:

  • REPORT_STEP – Report step size (seconds).

  • NUM_PERIODS – Number of reporting periods.

REPORT_STEP = Ellipsis#
NUM_PERIODS = Ellipsis#
class SubcatchAttribute(*values)#

Bases: Enum

Enumeration of the subcatchment attributes.

Variables:

  • RAINFALL – Subcatchment rainfall (in/hr or mm/hr).

  • SNOW_DEPTH – Subcatchment snow depth (in or mm).

  • EVAPORATION_LOSS – Subcatchment evaporation loss (in/hr or mm/hr).

  • INFILTRATION_LOSS – Subcatchment infiltration loss (in/hr or mm/hr).

  • RUNOFF_RATE – Subcatchment runoff flow (flow units).

  • GROUNDWATER_OUTFLOW – Subcatchment groundwater flow (flow units).

  • GW_TABLE – Subcatchment groundwater elevation (ft or m).

  • SOIL_MOISTURE – Subcatchment soil moisture content (-).

  • POLLUTANT_CONCENTRATION – Subcatchment pollutant concentration (-).

RAINFALL = Ellipsis#
SNOW_DEPTH = Ellipsis#
EVAPORATION_LOSS = Ellipsis#
INFILTRATION_LOSS = Ellipsis#
RUNOFF_RATE = Ellipsis#
GROUNDWATER_OUTFLOW = Ellipsis#
GROUNDWATER_TABLE_ELEVATION = Ellipsis#
SOIL_MOISTURE = Ellipsis#
POLLUTANT_CONCENTRATION = Ellipsis#
class NodeAttribute(*values)#

Bases: Enum

Enumeration of the node attributes.

Variables:

  • INVERT_DEPTH – Node depth above invert (ft or m).

  • HYDRAULIC_HEAD – Node hydraulic head (ft or m).

  • STORED_VOLUME – Node volume stored (ft3 or m3).

  • LATERAL_INFLOW – Node lateral inflow (flow units).

  • TOTAL_INFLOW – Node total inflow (flow units).

  • FLOODING_LOSSES – Node flooding losses (flow units).

  • POLLUTANT_CONCENTRATION – Node pollutant concentration (-).

INVERT_DEPTH = Ellipsis#
HYDRAULIC_HEAD = Ellipsis#
STORED_VOLUME = Ellipsis#
LATERAL_INFLOW = Ellipsis#
TOTAL_INFLOW = Ellipsis#
FLOODING_LOSSES = Ellipsis#
POLLUTANT_CONCENTRATION = Ellipsis#
class LinkAttribute(*values)#

Bases: Enum

Enumeration of the link attributes.

Variables:

  • FLOW_RATE – Link flow rate (flow units).

  • FLOW_DEPTH – Link flow depth (ft or m).

  • FLOW_VELOCITY – Link flow velocity (ft/s or m/s).

  • FLOW_VOLUME – Link flow volume (ft3 or m3).

  • CAPACITY – Link capacity (fraction of conduit filled).

  • POLLUTANT_CONCENTRATION – Link pollutant concentration (-).

FLOW_RATE = Ellipsis#
FLOW_DEPTH = Ellipsis#
FLOW_VELOCITY = Ellipsis#
FLOW_VOLUME = Ellipsis#
CAPACITY = Ellipsis#
POLLUTANT_CONCENTRATION = Ellipsis#
class SystemAttribute(*values)#

Bases: Enum

Enumeration of the system attributes.

Variables:

  • AIR_TEMP – Air temperature (deg. F or deg. C).

  • RAINFALL – Rainfall intensity (in/hr or mm/hr).

  • SNOW_DEPTH – Snow depth (in or mm).

  • EVAP_INFIL_LOSS – Evaporation and infiltration loss rate (in/day or mm/day).

  • RUNOFF_FLOW – Runoff flow (flow units).

  • DRY_WEATHER_INFLOW – Dry weather inflow (flow units).

  • GROUNDWATER_INFLOW – Groundwater inflow (flow units).

  • RDII_INFLOW – Rainfall Derived Infiltration and Inflow (RDII) (flow units).

  • DIRECT_INFLOW – Direct inflow (flow units).

  • TOTAL_LATERAL_INFLOW – Total lateral inflow; sum of variables 4 to 8 (flow units).

  • FLOOD_LOSSES – Flooding losses (flow units).

  • OUTFALL_FLOWS – Outfall flow (flow units).

  • VOLUME_STORED – Volume stored in storage nodes (ft3 or m3).

  • EVAPORATION_RATE – Evaporation rate (in/day or mm/day).

AIR_TEMP = Ellipsis#
RAINFALL = Ellipsis#
SNOW_DEPTH = Ellipsis#
EVAP_INFIL_LOSS = Ellipsis#
RUNOFF_FLOW = Ellipsis#
DRY_WEATHER_INFLOW = Ellipsis#
GROUNDWATER_INFLOW = Ellipsis#
RDII_INFLOW = Ellipsis#
DIRECT_INFLOW = Ellipsis#
TOTAL_LATERAL_INFLOW = Ellipsis#
FLOOD_LOSSES = Ellipsis#
OUTFALL_FLOWS = Ellipsis#
VOLUME_STORED = Ellipsis#
EVAPORATION_RATE = Ellipsis#
exception SWMMOutputException(message)#

Bases: Exception

Exception class for SWMM output file processing errors.

Constructor to initialize the exception message.

Parameters:

message (str) – Error message.

Return type:

None

__init__(message)#

Constructor to initialize the exception message.

Parameters:

message (str) – Error message.

Return type:

None

class Output(output_file)#

Bases: object

Class to read and process the output file generated by the SWMM simulation.

Variables:

  • _output_file_handle – Handle to the SWMM output file.

  • _version – Version of the SWMM output file.

  • _units – Unit system used in the SWMM output file.

  • _flow_units – Flow units used in the SWMM output file.

  • _output_size – Size of the project in the SWMM output file.

  • _pollutant_units – Pollutant units used in the SWMM output file.

  • _start_date – Start date of the simulation in the SWMM output file.

  • _report_step – Report step size in seconds.

  • _num_periods – Number of reporting periods.

  • _times – Times of the simulation in the SWMM output file.

Parameters:

output_file (str)

Constructor to open the SWMM output file.

Parameters:

output_file (str) – Path to the SWMM output file.

__init__(output_file)#

Constructor to open the SWMM output file.

Parameters:

output_file (str) – Path to the SWMM output file.

Return type:

None

property flow_units: FlowUnits#

Method to get the flow units used in the SWMM output file.

Returns:

Flow units used in the SWMM output file.

Return type:

FlowUnits

get_element_name(element_type, element_index)#

Method to get the name of an element in the SWMM output file.

Parameters:

  • element_type (int) – Type of the element.

  • indelement_indexex – Index of the element.

  • element_index (int)

Returns:

Name of the element.

Return type:

str

get_element_names(element_type)#

Method to get the names of all elements of a given type in the SWMM output file.

Parameters:

element_type (int) – Type of the element.

Returns:

Names of all elements of the given type.

Return type:

List[str]

Method to get the time series data for a link attribute in the SWMM output file.

Parameters:

  • element_index (int) – Index of the link.

  • attribute (LinkAttribute) – Link attribute.

  • start_date_index (int) – Start date index. Default is 0.

  • end_date_index (int) – End date index. Default is the last date index.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Time series data for the link attribute.

Return type:

Dict[datetime, double]

Method to get the link values for all links for a given time index and attribute.

Parameters:

  • time_index (int) – Time index.

  • attribute (LinkAttribute) – Link attribute.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Link values for all links.

Return type:

Dict[str, float]

Method to get all attributes of a given link for specified time.

Parameters:

  • time_index (int) – Time index.

  • element_index (int, str) – Index of the link.

Returns:

Dictionary of link attributes.

Return type:

Dict[str, float]

get_node_timeseries(element_index, attribute, start_date_index=Ellipsis, end_date_index=Ellipsis, sub_index=Ellipsis)#

Method to get the time series data for a node attribute in the SWMM output file.

Parameters:

  • element_index (int or str) – Index of the node.

  • attribute (NodeAttribute) – Node attribute.

  • start_date_index (int) – Start date index. Default is 0.

  • end_date_index (int) – End date index. Default is the last date index.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Time series data for the node attribute.

Return type:

Dict[datetime, double]

get_node_values_by_time_and_attribute(time_index, attribute, sub_index=Ellipsis)#

Method to get the node values for all nodes for a given time index and attribute.

Parameters:

  • time_index (int) – Time index.

  • attribute (NodeAttribute) – Node attribute.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Node values for all nodes.

Return type:

Dict[str, float]

get_node_values_by_time_and_element_index(time_index, element_index)#

Method to get all attributes of a given node for specified time.

Parameters:

  • time_index (int) – Time index.

  • element_index (int) – Index of the node.

Returns:

Dictionary of node attributes.

Return type:

Dict[str, float]

get_num_properties(element_type)#

Method to get the number of properties for an element type in the SWMM output file.

Parameters:

element_type (int) – Type of the element.

Returns:

Number of properties for the element type.

Return type:

int

get_num_variables(element_type)#

Method to get the number of variables for an element type in the SWMM output file.

Parameters:

element_type (int) – Type of the element.

Returns:

Number of variables for the element type.

Return type:

int

get_property_code(element_type, property_index)#

Method to get the property code for an element type in the SWMM output file.

Parameters:

  • element_type (int) – Type of the element.

  • property_index (int) – Index of the property.

Returns:

Property code for the element type.

Return type:

int

get_property_codes(element_type)#

Method to get the property codes for an element type in the SWMM output file.

Parameters:

element_type (int) – Type of the element.

Returns:

Property codes for the element type.

Return type:

List[int]

get_property_value(element_type, element_index, property_code)#

Method to get the property value for an element in the SWMM output file.

Parameters:

  • element_type (int) – Type of the element.

  • element_index (int) – Index of the element.

  • property_code (int) – Property code.

Returns:

Property value for the element.

Return type:

float

get_property_values(element_type, element_index)#

Method to get the property values for an element type in the SWMM output file.

Parameters:

  • element_type (int) – Type of the element.

  • element_index (int) – Element index.

Returns:

Property values for the element type.

Return type:

List[float]

get_subcatchment_timeseries(element_index, attribute, start_date_index=Ellipsis, end_date_index=Ellipsis, sub_index=Ellipsis)#

Method to get the time series data for a subcatchment attribute in the SWMM output file.

Parameters:

  • element_index (int or str) – Index of the subcatchment.

  • attribute (SubcatchAttribute) – Subcatchment attribute.

  • start_date_index (int) – Start date index. Default is 0.

  • end_date_index (int) – End date index. Default is the last date index.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Time series data for the subcatchment attribute.

Return type:

Dict[datetime, double]

get_subcatchment_values_by_time_and_attribute(time_index, attribute, sub_index=Ellipsis)#

Method to get the subcatchment values for all subcatchments for a given time index and attribute.

Parameters:

  • time_index (int) – Time index.

  • attribute (SubcatchAttribute) – Subcatchment attribute.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Subcatchment values for all subcatchments.

Return type:

Dict[str, float]

get_subcatchment_values_by_time_and_element_index(time_index, element_index)#

Method to get all attributes of a given subcatchment for specified time.

Parameters:

  • time_index (int) – Time index.

  • element_index (int or str) – Index of the subcatchment.

Returns:

Dictionary of subcatchment attributes.

Return type:

Dict[str, float]

get_system_timeseries(attribute, start_date_index=Ellipsis, end_date_index=Ellipsis, sub_index=Ellipsis)#

Method to get the time series data for a system attribute in the SWMM output file.

Parameters:

  • attribute (SystemAttribute) – System attribute.

  • start_date_index (int) – Start date index. Default is 0.

  • end_date_index (int) – End date index. Default is the last date index.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

Time series data for the system attribute.

Return type:

Dict[datetime, double]

get_system_values_by_time(time_index)#

Method to get all attributes of the system for specified time.

Parameters:

time_index (int) – Time index.

Returns:

Dictionary of system attributes.

Return type:

Dict[str, float]

get_system_values_by_time_and_attribute(time_index, attribute, sub_index=Ellipsis)#

Method to get the system values for a given time index and attribute.

Parameters:

  • time_index (int) – Time index.

  • attribute (SystemAttribute) – System attribute.

  • sub_index (int) – Attribute index for the subcatchment non enumerated attributes primarily for the pollutants

Returns:

System values.

Return type:

Dict[str, float]

get_time_attribute(time_attribute)#

Method to get the temporal attributes of the simulation in the SWMM output file.

Parameters:

time_attribute (TimeAttribute) – Temporal attribute.

Returns:

Temporal attributes of the simulation in the SWMM output file.

Return type:

int

get_variable_code(element_type, variable_index)#

Method to get the variable code for an element type in the SWMM output file.

Parameters:

  • element_type (int) – Type of the element.

  • variable_index (int) – Index of the variable.

Returns:

Variable code for the element type.

Return type:

int

get_variable_codes(element_type)#

Method to get the variable codes for an element type in the SWMM output file.

Parameters:

element_type (int) – Type of the element.

Returns:

Variable codes for the element type.

Return type:

List[int]

property output_size: Dict[str, int]#

Method to get the size of the project in the SWMM output file.

Returns:

Size of the project in the SWMM output file.

Return type:

int

property pollutant_units: List[ConcentrationUnits]#

Method to get the pollutant units used in the SWMM output file.

Returns:

Pollutant units used in the SWMM output file.

Return type:

List[ConcentrationUnits]

property start_date: datetime#

Method to get the start date of the simulation in the SWMM output file.

Returns:

Start date of the simulation in the SWMM output file.

Return type:

datetime

property times: List[datetime]#

Method to get the times of the simulation in the SWMM output file.

Returns:

Times of the simulation in the SWMM output file.

Return type:

List[datetime]

property units: Tuple[UnitSystem, FlowUnits, List[ConcentrationUnits] | None]#

Method to get the unit system used in the SWMM output file.

Returns:

Tuple of the unit system, flow units, and pollutant units used in the SWMM output file.

Return type:

Tuple[UnitSystem, FlowUnits, Optional[List[ConcentrationUnits]]]

property version: int#

Method to get the version of the SWMM output file.

Returns:

Version of the SWMM output file.

Return type:

str

On this page
Show Source