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

XSectionGeometry

openswmm_xsect.h

Cross-section geometry kernels (standalone or per-link)

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])

property aquifers: Aquifers#
property climate: Climate#
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 event_count: int#

Number of [EVENTS] entries on the model.

Return type:

int

property events: EventsView#
property flow_units: FlowUnits#

The model’s flow-unit system, resolved from FLOW_UNITS.

Returns:

Active flow-unit system; read this to interpret the project-unit magnitudes returned by all getters.

Return type:

L{FlowUnits}

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

property open_errors: list[str]#
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 open_warnings: list[str]#
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_lenient_open(on=Ellipsis)#
Parameters:

on (bool)

Return type:

None

set_progress_callback(callback)#

Register a progress callback receiving the elapsed fraction [0, 1].

Parameters:

callback (Callable[[float], None] | None) – (elapsed_frac: float) -> None or None to clear.

Return type:

None

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 sim_end_time: datetime#

Resolved simulation end (swmm_get_end_time).

Return type:

datetime

property sim_start_time: datetime#

Resolved simulation start (swmm_get_start_time).

Return type:

datetime

property snowpacks: Snowpacks#
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 surface2d: Surface2D#
property tables: Tables#
property unit_system: str#

'US' (CFS/GPM/MGD) or 'SI' (CMS/LPS/MLD).

Return type:

str

until(target)#
Parameters:

target (datetime | timedelta)

Return type:

timedelta

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

path (str | PathLike[str])

Return type:

None

write_geopackage(path, crs=Ellipsis)#
Parameters:
Return type:

None

write_with_plugin(path, output_plugin_id=Ellipsis)#
Parameters:
Return type:

None

class UserFlagDef(name, type, description)#

Bases: NamedTuple

A [USER_FLAGS] schema definition: (name, type, description).

type is 0=BOOLEAN, 1=INTEGER, 2=REAL, 3=STRING (see UserFlagType).

Create new instance of UserFlagDef(name, type, description)

Parameters:
description: str#

Alias for field number 2

name: str#

Alias for field number 0

type: int#

Alias for field number 1

class UserFlags(solver)#

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

Typed user-flag mapping. See Solver.userflags.

Parameters:

solver (Solver)

clear_value(obj_type, obj_name, flag_name)#
Parameters:

  • obj_type (str)

  • obj_name (str)

  • flag_name (str)

Return type:

None

define(name, type, description='')#
Parameters:
Return type:

None

definitions()#
Return type:

list[UserFlagDef]

get_value(obj_type, obj_name, flag_name)#
Parameters:

  • obj_type (str)

  • obj_name (str)

  • flag_name (str)

Return type:

str | None

set_value(obj_type, obj_name, flag_name, value)#
Parameters:
Return type:

None

undefine(name)#
Parameters:

name (str)

Return type:

None

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

clear_userflag_value(obj_type, obj_name, flag_name)#

Remove a per-object flag value (idempotent).

Raises:

EngineError – On C API failure.

Parameters:

  • obj_type (str)

  • obj_name (str)

  • flag_name (str)

Return type:

None

define_userflag(name, type, description='')#

Define (or redefine) a user-flag schema entry ([USER_FLAGS]).

Parameters:

  • type (int) – 0=BOOLEAN, 1=INTEGER, 2=REAL, 3=STRING (UserFlagType).

  • name (str)

  • description (str)

Raises:

EngineError – On empty name or invalid type.

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.

property generation: int#

Monotonic counter bumped on every structural mutation.

Mirrors Solver.generation so wrapper objects minted from a ModelBuilder can detect staleness the same way.

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_file_path(role, owner=Ellipsis)#

Read an external-file slot’s (absolute, original) paths.

Parameters:

  • role (int) – A FilePathRole value.

  • owner (str) – Owner key for vector slots; ignored for scalar slots.

Return type:

tuple[str, 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_def(index)#

Return (name, type, description) for the definition at index.

Raises:

EngineError – If index is out of range.

Parameters:

index (int)

Return type:

tuple[str, int, str]

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

get_userflag_value(obj_type, obj_name, flag_name)#

Return a per-object flag value string, or None when unassigned.

Raises:

EngineError – On C API failure.

Parameters:

  • obj_type (str)

  • obj_name (str)

  • flag_name (str)

Return type:

str | None

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_file_path(role, new_path, owner=Ellipsis)#

Set an external-file slot’s path token (empty clears it).

Parameters:

  • role (int) – A FilePathRole value.

  • owner (str) – Owner key for vector slots; must already exist.

  • new_path (str)

Return type:

None

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

set_userflag_value(obj_type, obj_name, flag_name, value)#

Assign a per-object flag value from a string (typed parse).

Raises:

EngineError – On undefined flag or unparseable value.

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}

undefine_userflag(name)#

Remove a user-flag definition and all its per-object values.

Raises:

EngineError – If the flag is not defined.

Parameters:

name (str)

Return type:

None

userflag_def_count()#

Return the number of user-flag schema definitions.

Return type:

int

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_aquifer_impact(id_or_idx)#

Preview which subcatchments reference an aquifer.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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.

analyze_hydrograph_impact(uh_name)#

Preview which objects reference a unit-hydrograph group by name.

Parameters:

uh_name (str)

Return type:

list[ImpactEntry]

analyze_inlet_impact(id_or_idx)#

Preview which inlet-usage rows reference an inlet design.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

analyze_landuse_impact(id_or_idx)#

Preview which objects reference a land use.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

analyze_lid_impact(id_or_idx)#

Preview which LID-usage rows reference a LID control.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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_pattern_impact(id_or_idx)#

Preview which objects reference a time pattern.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

analyze_pollutant_impact(id_or_idx)#

Preview which objects reference a pollutant.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

analyze_snowpack_impact(id_or_idx)#

Preview which subcatchments reference a snowpack.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

analyze_street_impact(id_or_idx)#

Preview which inlet-usage rows reference a street.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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_aquifer(id_or_idx)#

Delete an aquifer; referencing subcatchments lose groundwater.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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_hydrograph(uh_name)#

Delete a unit-hydrograph group by name.

Parameters:

uh_name (str)

Return type:

list[ImpactEntry]

delete_inlet(id_or_idx)#

Delete an inlet design; cascade-delete referencing inlet-usage rows.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

delete_landuse(id_or_idx)#

Delete a land use; re-pack buildup/washoff and coverage columns.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

delete_lid(id_or_idx)#

Delete a LID control; cascade-delete referencing LID-usage rows.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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_pattern(id_or_idx)#

Delete a time pattern and clear all name-based references.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

delete_pollutant(id_or_idx)#

Delete a pollutant and re-pack every per-pollutant matrix.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

delete_snowpack(id_or_idx)#

Delete a snowpack; clear referencing subcatchments and renumber.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

delete_street(id_or_idx)#

Delete a street; cascade-delete referencing inlet-usage rows.

Parameters:

id_or_idx (int | str)

Return type:

list[ImpactEntry]

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:
fuse_virtual_junction(id_or_idx)#

Re-fuse the two conduits of a virtual junction into one.

Parameters:

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

Returns:

Index of the surviving conduit AFTER deletions renumber.

Return type:

int

Raises:

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

  • EngineError – If the node is not a two-conduit through virtual junction, or on C API failure.

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

set_node_virtual(id_or_idx, make_virtual=True)#

Set or clear a node’s virtual-junction flag (validated).

Parameters:

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

  • make_virtual (bool) – True to set, False to clear.

Raises:

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

  • EngineError – On a violated usage rule or C API failure.

Return type:

None

split_conduit(id_or_idx, t, new_node_name, new_link_name, make_virtual=False)#

Split a conduit at normalized position t, inserting a new node.

Parameters:

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

  • t (float) – Normalized split position, exclusive (0, 1).

  • new_node_name (str) – Unique name for the inserted node.

  • new_link_name (str) – Unique name for the new downstream conduit.

  • make_virtual (bool) – Flag the inserted node as a virtual junction.

Returns:

(new_node_index, new_link_index).

Return type:

tuple[int, int]

Raises:

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

  • EngineError – On invalid parameters or a rule failure.

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#
tag: str#
index: int#
type: NodeType#
is_virtual: bool#
virtual_rule_violation: int#
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[Any]

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

None

set_lateral_inflows(values)#
Parameters:

values (NDArray[Any])

Return type:

None

depths: NDArray[Any]#
heads: NDArray[Any]#
inflows: NDArray[Any]#
overflows: NDArray[Any]#
volumes: NDArray[Any]#
outflows: NDArray[Any]#
losses: NDArray[Any]#
lateral_inflows: NDArray[Any]#
ids: NDArray[Any]#
class OutfallView#

Bases: object

get_tidal_curve()#
Return type:

int

get_timeseries()#
Return type:

int

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]#
shape: StorageShape#
geometry: Tuple[float, float, float]#
seep_rate: float#
exfil_params: Tuple[float, float, float]#

Cross-Section Geometry#

Type stubs for openswmm.engine._xsect.

class XSectionGeometry(shape, geom1, geom2=Ellipsis, geom3=Ellipsis, geom4=Ellipsis, *, units)#

Bases: object

Parameters:
area(**kwds)#

Helper for @overload to raise when called.

area_from_section_factor(**kwds)#

Helper for @overload to raise when called.

critical_depth(**kwds)#

Helper for @overload to raise when called.

depth_from_area(**kwds)#

Helper for @overload to raise when called.

dsda(**kwds)#

Helper for @overload to raise when called.

property flow_units: str#
classmethod from_curve(full_depth, curve_depths, curve_widths, *, units)#
Parameters:
Return type:

XSectionGeometry

Parameters:

link (Any)

Return type:

XSectionGeometry

classmethod from_street(width, curb_height, slope, roughness, *, gutter_depression=Ellipsis, gutter_width=Ellipsis, sides=Ellipsis, back_width=Ellipsis, back_slope=Ellipsis, back_roughness=Ellipsis, units)#
Parameters:
Return type:

XSectionGeometry

classmethod from_transect(stations, elevations, *, left_bank, right_bank, n_channel, n_left=Ellipsis, n_right=Ellipsis, length_factor=Ellipsis, units)#
Parameters:
Return type:

XSectionGeometry

property full_area: float#
property full_depth: float#
property full_hyd_radius: float#
property full_section_factor: float#
hyd_radius(**kwds)#

Helper for @overload to raise when called.

hyd_radius_from_area(**kwds)#

Helper for @overload to raise when called.

property is_open: bool#
property max_area: float#
property max_width: float#
section_factor(**kwds)#

Helper for @overload to raise when called.

property units: Literal['US', 'SI']#
width(**kwds)#

Helper for @overload to raise when called.

shape: XSectShape#
shape_name(shape)#
Parameters:

shape (XSectShape | int)

Return type:

str

Cross-Section Geometry#

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

Provides the CrossSection dataclass, which wraps the raw (shape, geom1, geom2, geom3, geom4) tuple a link reports with human-readable field labels and a shape_name derived from the XSectShape enum.

Obtain one from Links.get_xsect_info() or link.xsect.info(). For the hydraulic geometry of a section — area, top width, hydraulic radius, critical depth — see XSectionGeometry instead.

Example:

from openswmm.engine import Solver, Links, CrossSection

with Solver("model.inp", "model.rpt", "model.out") as s:
    links = Links(s)
    xs = links.get_xsect_info(0)
    print(xs.shape_name)          # "CIRCULAR"
    print(xs.geom_labels)         # {"diameter": 1.2}
class CrossSection(shape, shape_name, geom1, geom2, geom3, geom4)[source]#

Bases: object

Structured cross-section geometry returned by Links.get_xsect_info().

All four geom values are always present; unused parameters are 0.0. Use geom_labels to get a {label: value} dict that filters out unused (zero) parameters and names each one meaningfully.

Variables:

  • shape – Integer cross-section shape code (see XSectShape).

  • shape_name – Human-readable name, e.g. "CIRCULAR".

  • geom1 – First geometry parameter (meaning depends on shape).

  • geom2 – Second geometry parameter (or 0.0 if unused).

  • geom3 – Third geometry parameter (or 0.0 if unused).

  • geom4 – Fourth geometry parameter (or 0.0 if unused).

Parameters:
shape: int#
shape_name: str#
geom1: float#
geom2: float#
geom3: float#
geom4: float#
classmethod from_raw(shape, geom1, geom2, geom3, geom4)[source]#

Build from the raw (shape, geom1..geom4) the engine reports.

Parameters:

  • shape (int) – Integer shape code (see XSectShape).

  • geom1 (float) – First geometry parameter.

  • geom2 (float) – Second geometry parameter.

  • geom3 (float) – Third geometry parameter.

  • geom4 (float) – Fourth geometry parameter.

Return type:

CrossSection

property geom_labels: dict[str, float]#

Return {label: value} for the geometry parameters of this shape.

Only parameters meaningful for this shape are included (trailing unused zeros are omitted). Example for a 1.2 m diameter circular pipe:

{"diameter": 1.2}
Return type:

dict[str, 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 Aquifers#

Bases: object

Name-keyed collection of [AQUIFERS] entries (solver.aquifers).

get_evap_pattern(aquifer)#
Parameters:

aquifer (int | str)

Return type:

str

get_param(aquifer, param)#
Parameters:

  • aquifer (int | str)

  • param (AquiferParam | int)

Return type:

float

set_evap_pattern(aquifer, name)#
Parameters:
Return type:

None

set_param(aquifer, param, value)#
Parameters:
Return type:

None

class CoverageView(sub)#

Bases: MutableMapping[str, float]

Parameters:

sub (Subcatchment)

class GroundwaterParams(surf_elev, a1, b1, a2, b2, a3, tw, hstar)#

Bases: NamedTuple

Create new instance of GroundwaterParams(surf_elev, a1, b1, a2, b2, a3, tw, hstar)

Parameters:
a1: float#

Alias for field number 1

a2: float#

Alias for field number 3

a3: float#

Alias for field number 5

b1: float#

Alias for field number 2

b2: float#

Alias for field number 4

hstar: float#

Alias for field number 7

surf_elev: float#

Alias for field number 0

tw: float#

Alias for field number 6

class InfiltrationView#

Bases: object

set_curve_number(cn, drying_time)#
Parameters:
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#
curve_number_drying_time: float#
class Snowpacks#

Bases: object

Name-keyed collection of [SNOWPACKS] entries (solver.snowpacks).

get_impervious(snowpack)#
Parameters:

snowpack (int | str)

Return type:

dict[str, float]

get_pervious(snowpack)#
Parameters:

snowpack (int | str)

Return type:

dict[str, float]

get_plowable(snowpack)#
Parameters:

snowpack (int | str)

Return type:

dict[str, float]

get_removal(snowpack)#
Parameters:

snowpack (int | str)

Return type:

dict[str, float]

get_removal_subcatch(snowpack)#
Parameters:

snowpack (int | str)

Return type:

str

set_impervious(snowpack, *, cmin, cmax, tbase, fwfrac, sd0, fw0, last)#
Parameters:
Return type:

None

set_pervious(snowpack, *, cmin, cmax, tbase, fwfrac, sd0, fw0, last)#
Parameters:
Return type:

None

set_plowable(snowpack, *, cmin, cmax, tbase, fwfrac, sd0, fw0, last)#
Parameters:
Return type:

None

set_removal(snowpack, *, dsnow, fout, fimp, fperv, fimelt, fsubcatch)#
Parameters:
Return type:

None

set_removal_subcatch(snowpack, name)#
Parameters:
Return type:

None

class Subcatchment(solver, index)#

Bases: object

Single-subcatchment wrapper. See Subcatchments.

Parameters:
get_gw_state()#
Return type:

tuple[float, float]

get_snow_state(surface)#
Parameters:

surface (int)

Return type:

tuple[float, float, float, float]

ponded_quality(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

quality(pollutant)#
Parameters:

pollutant (int | str)

Return type:

float

set_gw_params(surf_elev, a1, b1, a2, b2, a3, tw, hstar)#
Parameters:
Return type:

None

set_gw_state(theta=Ellipsis, lower_depth=Ellipsis)#
Parameters:
Return type:

None

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

set_snow_state(surface, swe=Ellipsis, fw=Ellipsis, ati=Ellipsis, coldc=Ellipsis)#
Parameters:
Return type:

None

id: str#
tag: str#
index: int#
solver: Solver#
area: float#
width: float#
slope: float#
imperv_pct: float#
zero_imperv_pct: float#
n_imperv: float#
n_perv: float#
ds_imperv: float#
ds_perv: float#
gage: Gage#
outlet: Node | Subcatchment | None#
aquifer: int | None#
gw_node: int | None#
gw_params: GroundwaterParams#
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[Any]

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

None

runoffs: NDArray[Any]#
rainfalls: NDArray[Any]#
evaps: NDArray[Any]#
infils: NDArray[Any]#
snow_depths: NDArray[Any]#
ids: NDArray[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#
scale_factor: float#
snow_factor: float#
rain_interval: float#
rain_units: int#
timeseries: str#
station_id: str#
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[Any]#
ids: NDArray[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, snow_on=Ellipsis, snow_T=Ellipsis, snow_ddf=Ellipsis)#
Parameters:
Return type:

None

clear_hydrograph_group_months(uh_name)#
Parameters:

uh_name (str)

Return type:

None

get_dwf(entry_idx)#
Parameters:

entry_idx (int)

Return type:

Tuple[int, str, float, str, str, str, str]

get_external(entry_idx)#
Parameters:

entry_idx (int)

Return type:

Tuple[int, str, str, str, float, float, float, str]

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

remove_dwf(entry_idx)#
Parameters:

entry_idx (int)

Return type:

None

remove_external(entry_idx)#
Parameters:

entry_idx (int)

Return type:

None

remove_hydrograph_entry(uh_name, month, response)#
Parameters:
Return type:

None

remove_hydrograph_group(uh_name)#
Parameters:

uh_name (str)

Return type:

None

remove_rdii(entry_idx)#
Parameters:

entry_idx (int)

Return type:

None

remove_rdii_decay(uh_name, response)#
Parameters:

  • uh_name (str)

  • response (int)

Return type:

None

rename_hydrograph_group(idx, new_id)#
Parameters:
Return type:

None

set_dwf_baseline(entry_idx, avg_value)#
Parameters:
Return type:

None

set_external_baseline(entry_idx, baseline)#
Parameters:
Return type:

None

set_external_scale(entry_idx, scale)#
Parameters:
Return type:

None

set_hydrograph_gage(uh_name, gage_name)#
Parameters:

  • uh_name (str)

  • gage_name (str)

Return type:

None

set_hydrograph_ia(uh_name, month, response, dmax, drecov, dinit)#
Parameters:
Return type:

None

set_hydrograph_rtk(uh_name, month, response, r, t, k)#
Parameters:
Return type:

None

set_rdii_decay(uh_name, response, k_dep, k_0, k_T, T_ref, theta_rec, T_freeze, snow_on=Ellipsis, snow_T=Ellipsis, snow_ddf=Ellipsis)#
Parameters:
Return type:

None

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, snow_on, snow_T, snow_ddf)#

Bases: NamedTuple

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

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

snow_T: float#

Alias for field number 9

snow_ddf: float#

Alias for field number 10

snow_on: bool#

Alias for field number 8

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

climate_dry_only(flag)#
Parameters:

flag (bool)

Return type:

None

climate_evap(value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:

  • value (float)

  • mode (ForcingMode)

  • persist (bool)

Return type:

None

climate_evap_rate()#
Return type:

float

climate_temperature(value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:

  • value (float)

  • mode (ForcingMode)

  • persist (bool)

Return type:

None

climate_wind(value, *, mode=Ellipsis, persist=Ellipsis)#
Parameters:

  • value (float)

  • mode (ForcingMode)

  • persist (bool)

Return type:

None

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

None

get_climate_dry_only()#
Return type:

bool

get_climate_temperature()#
Return type:

float

get_climate_wind_speed()#
Return type:

float

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

subcatchment_snowfall(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

find_references(object_name)#
Parameters:

object_name (str)

Return type:

list[int]

insert(idx, value)#

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

Parameters:
Return type:

None

remove_rule(idx)#
Parameters:

idx (int)

Return type:

None

Parameters:
Return type:

None

Parameters:
Return type:

None

validate_message(rule_text)#
Parameters:

rule_text (str)

Return type:

Tuple[bool, str]

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#
dwf_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[Any]#
class Pattern(solver, index)#

Bases: object

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

None

index: int#
id: str#
solver: Solver#
type: PatternType#
factors: list[float]#
class Patterns(solver)#

Bases: object

Parameters:

solver (Solver)

add(pattern_id, type=Ellipsis)#
Parameters:

  • pattern_id (str)

  • type (PatternType)

Return type:

Pattern

get_index(pattern_id)#
Parameters:

pattern_id (str)

Return type:

int

remove(key)#
Parameters:

key (int | str)

Return type:

None

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

None

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

get_type(key)#

The type of a table (time series vs. curve kind) as a TableType.

Parameters:

key (int | str) – Table index or id.

Return type:

L{TableType}

class TimeSeries(solver, index)#

Bases: _PointTable

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

None

points: NDArray[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

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(inlet_id)#
Parameters:

inlet_id (str)

Return type:

int

get_params(idx)#
Parameters:

idx (int)

Return type:

dict[str, float | str]

get_type(idx)#
Parameters:

idx (int)

Return type:

str

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

get_drain(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_drainmat(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(lid_id)#
Parameters:

lid_id (str)

Return type:

int

get_pavement(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_soil(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_storage(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_surface(idx)#
Parameters:

idx (int)

Return type:

dict[str, float]

get_type(idx)#
Parameters:

idx (int)

Return type:

int

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

None

set_drainmat(idx, *, thick, void_frac, roughness)#
Parameters:
Return type:

None

set_pavement(idx, *, thick, void_ratio, frac_imperv, ksat, clog_factor=Ellipsis, regen_days=Ellipsis)#
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

usage_count()#
Return type:

int

usage_get(usage_idx)#
Parameters:

usage_idx (int)

Return type:

dict[str, float | int]

usage_remove(usage_idx)#
Parameters:

usage_idx (int)

Return type:

None

class Streets(solver)#

Bases: object

Parameters:

solver (Solver)

add(street_id)#
Parameters:

street_id (str)

Return type:

int

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(street_id)#
Parameters:

street_id (str)

Return type:

int

get_params(idx)#

Read back a street cross-section’s geometric parameters.

Returns:

Keys t_crown, h_curb, sx, n_road, gutter_depres, gutter_width, sides, back_width, back_slope, back_n (the inverse of set_params).

Return type:

dict[str, float]

Parameters:

idx (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

clear_stations(idx)#
Parameters:

idx (int)

Return type:

None

get_bank_stations(idx)#
Parameters:

idx (int)

Return type:

Tuple[float, float]

get_comments(idx)#
Parameters:

idx (int)

Return type:

str

get_encroachment_stations(idx)#
Parameters:

idx (int)

Return type:

Tuple[float, float]

get_id(idx)#
Parameters:

idx (int)

Return type:

str

get_index(transect_id)#
Parameters:

transect_id (str)

Return type:

int

get_modifiers(idx)#
Parameters:

idx (int)

Return type:

Tuple[float, float, float]

get_roughness(idx)#
Parameters:

idx (int)

Return type:

Tuple[float, float, float]

get_station(idx, station_idx)#
Parameters:
Return type:

Tuple[float, float]

remove(key)#
Parameters:

key (int | str)

Return type:

None

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

None

set_bank_stations(idx, left, right)#
Parameters:
Return type:

None

set_comments(idx, text)#
Parameters:
Return type:

None

set_encroachment_stations(idx, left, right)#
Parameters:
Return type:

None

set_modifiers(idx, n_factor, x_factor, y_factor)#
Parameters:
Return type:

None

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

None

station_count(idx)#
Parameters:

idx (int)

Return type:

int

stations(idx)#
Parameters:

idx (int)

Return type:

List[Tuple[float, float]]

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

property crs: str | None#

Coordinate reference system string recorded in the file, or None.

Number of links stored in the hot-start blob.

property node_count: int#

Number of nodes stored in the hot-start blob.

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

property sim_datetime: datetime#

Simulation moment at which the hot-start state was captured.

property warnings: List[str]#

Warnings emitted while opening or applying the hot-start file.

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)

property max_courant: float#

Maximum Courant number reached over the routing run.

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

property routing_continuity_error: float#

Flow-routing continuity (mass-balance) error, as a percentage.

property routing_diagnostics: RoutingDiagnostics#

Routing-solver time-step diagnostics (step sizes, Courant number, convergence counts) as a RoutingDiagnostics record.

routing_total(component)#
Parameters:

component (RoutingTotal)

Return type:

float

property runoff_continuity_error: float#

Runoff continuity (mass-balance) error, as a percentage.

runoff_total(component)#
Parameters:

component (RunoffTotal)

Return type:

float

Statistics#

Simulation statistics (Pythonic v1 surface)#

Type stubs for openswmm.engine._statistics.

class Statistics(solver)#

Bases: object

Parameters:

solver (Solver)

Maximum filling ratio (depth / full depth) in each link.

Parameters:

idx (int)

Return type:

float

Maximum flow rate in each link, in project units.

Parameters:

idx (int)

Return type:

float

Maximum flow velocity in each link, in project units.

Parameters:

idx (int)

Return type:

float

Cumulative surcharge duration in each link, in seconds.

Parameters:

idx (int)

Return type:

float

Cumulative flow volume through each link, in project units.

Parameters:

idx (int)

Return type:

float

property node_max_depth: NDArray[Any]#

Maximum depth reached at each node, in project units.

node_max_depth_at(idx)#
Parameters:

idx (int)

Return type:

float

property node_max_overflow: NDArray[Any]#

Maximum overflow (flooding) rate at each node, in project units.

node_max_overflow_at(idx)#
Parameters:

idx (int)

Return type:

float

property node_time_flooded: NDArray[Any]#

Cumulative flooded duration at each node, in seconds.

node_time_flooded_at(idx)#
Parameters:

idx (int)

Return type:

float

property node_vol_flooded: NDArray[Any]#

Cumulative flooded volume at each node, in project units.

node_vol_flooded_at(idx)#
Parameters:

idx (int)

Return type:

float

property subcatchment_max_runoff: NDArray[Any]#

Peak runoff rate from each subcatchment, in project units.

subcatchment_max_runoff_at(idx)#
Parameters:

idx (int)

Return type:

float

property subcatchment_precip: NDArray[Any]#

Cumulative precipitation depth per subcatchment, in project depth units (in for US, mm for SI). The only statistic without a C _bulk companion; gathered scalar-wise in a nogil loop.

property subcatchment_runoff_vol: NDArray[Any]#

Cumulative runoff volume from each subcatchment, in project units.

subcatchment_runoff_vol_at(idx)#
Parameters:

idx (int)

Return type:

float

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[Any]

Parameters:

  • link (int | str)

  • var (OutLinkVar)

  • start (int | None)

  • end (int | None)

Return type:

NDArray[Any]

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

Dict[OutNodeVar | int, float]

node_result(period, var)#
Parameters:

  • period (int)

  • var (OutNodeVar)

Return type:

NDArray[Any]

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

  • node (int | str)

  • var (OutNodeVar)

  • start (int | None)

  • end (int | None)

Return type:

NDArray[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[Any]

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

  • sub (int | str)

  • var (OutSubcatchVar)

  • start (int | None)

  • end (int | None)

Return type:

NDArray[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[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[Any]#

Spatial (CRS, coordinates, vertices, polygons)#

Type stubs for openswmm.engine._spatial.

class Spatial(solver)#

Bases: object

Parameters:

solver (Solver)

property crs: str#

Coordinate reference system (EPSG token, WKT, or proj string). Reading a model with no CRS raises CRSError; assigning sets it.

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[Any]

node_coord(node)#
Parameters:

node (int | str)

Return type:

Tuple[float, float]

node_coords()#
Return type:

NDArray[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[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[Any]

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 AquiferParam(*values)

Bases: IntEnum

Aquifer parameter codes for Aquifers.get_param / set_param.

Variables:

  • POROSITY – Porosity (volumetric fraction).

  • WILTING_POINT – Wilting point (volumetric fraction).

  • FIELD_CAPACITY – Field capacity (volumetric fraction).

  • CONDUCTIVITY – Saturated hydraulic conductivity.

  • CONDUCT_SLOPE – Conductivity slope.

  • TENSION_SLOPE – Tension slope.

  • UPPER_EVAP_FRAC – Upper-zone evaporation fraction.

  • LOWER_EVAP_DEPTH – Lower-zone evaporation depth.

  • LOWER_LOSS_COEFF – Lower-zone seepage-loss coefficient.

  • BOTTOM_ELEV – Aquifer bottom elevation.

  • WATER_TABLE_ELEV – Initial water table elevation.

  • UPPER_MOISTURE – Initial upper-zone moisture.

POROSITY = 0
WILTING_POINT = 1
FIELD_CAPACITY = 2
CONDUCTIVITY = 3
CONDUCT_SLOPE = 4
TENSION_SLOPE = 5
UPPER_EVAP_FRAC = 6
LOWER_EVAP_DEPTH = 7
LOWER_LOSS_COEFF = 8
BOTTOM_ELEV = 9
WATER_TABLE_ELEV = 10
UPPER_MOISTURE = 11
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 DividerType(*values)

Bases: IntEnum

Flow-diversion method for a DIVIDER node. Mirrors SWMM_DividerType.

CUTOFF = 0
OVERFLOW = 1
TABULAR = 2
WEIR = 3
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 FilePathRole(*values)

Bases: IntEnum

External-file slot selector for swmm_file_path_get/set. Mirrors SWMM_FilePathRole.

RAINFALL = 1
RUNOFF = 2
RDII = 3
INFLOWS = 4
OUTFLOWS = 5
HOTSTART_USE = 6
CLIMATE_TEMP = 7
HOTSTART_SAVE = 8
RAINGAGE_DATA = 9
TIMESERIES_DATA = 10
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. Mirrors SWMM_ForcingMode in openswmm_forcing.h (OVERRIDE=1, ADD=2; 0 is the engine-internal “no forcing” state and is not exposed).

Variables:

  • REPLACE – Replace the computed value entirely.

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

REPLACE = 1
ADD = 2
class ForcingPersist(*values)

Bases: IntEnum

Lifetime of a runtime forcing override. Mirrors SWMM_ForcingPersist.

RESET = 0
PERSIST = 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.

  • CLIMATE – System-wide climate forcing target (temperature, wind).

NODE = 0
LINK = 1
SUBCATCH = 2
GAGE = 3
CLIMATE = 4
class ForcingType(*values)

Bases: IntEnum

Forcing channel for a runtime override. Mirrors SWMM_ForcingType.

NODE_LAT_INFLOW = 0
NODE_HEAD_BOUNDARY = 1
NODE_QUALITY = 2
LINK_FLOW = 3
LINK_SETTING = 4
SUBCATCH_RAINFALL = 5
SUBCATCH_EVAP = 6
GAGE_RAINFALL = 7
CLIMATE_TEMPERATURE = 8
CLIMATE_WIND = 9
SUBCATCH_SNOWFALL = 10
CLIMATE_EVAP = 11
LINK_QUALITY = 12
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 RefType(*values)

Bases: IntEnum

Object kind holding a reference (editing API). Mirrors SWMM_RefType.

NODE = 0
LINK = 1
SUBCATCH = 2
GAGE = 3
TABLE = 4
TRANSECT = 5
INLET_USAGE = 6
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 StorageShape(*values)

Bases: IntEnum

Storage-unit surface-area relation codes.

TABULAR = 0
FUNCTIONAL = 1
CYLINDRICAL = 2
CONICAL = 3
PARABOLOID = 4
PYRAMIDAL = 5
class SurfaceBoundaryType(*values)

Bases: IntEnum

2D mesh edge boundary-condition type. Mirrors openswmm::twoD::BoundaryType.

WALL = 0
NORMAL_FLOW = 1
SPECIFIED_STAGE = 2
SPECIFIED_FLOW = 3
RATING_CURVE = 4
class SurfaceForcingMode(*values)

Bases: IntEnum

2D surface forcing mode. Mirrors SWMM_ForcingMode (OVERRIDE=1, ADD=2).

NONE = 0
OVERRIDE = 1
ADD = 2
class TableType(*values)

Bases: IntEnum

Table type code from swmm_table_get_type. Mirrors openswmm::TableType.

TIMESERIES = 0
CURVE_STORAGE = 1
CURVE_DIVERSION = 2
CURVE_RATING = 3
CURVE_SHAPE = 4
CURVE_CONTROL = 5
CURVE_TIDAL = 6
CURVE_PUMP1 = 7
CURVE_PUMP2 = 8
CURVE_PUMP3 = 9
CURVE_PUMP4 = 10
CURVE_PUMP5 = 11
class UserFlagType(*values)

Bases: IntEnum

User-flag schema value type for swmm_userflag_define. Mirrors openswmm::UserFlagType.

BOOLEAN = 0
INTEGER = 1
REAL = 2
STRING = 3
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.

Mirrors the engine’s SWMM_XSectShape storage codes exactly.

Warning

Renumbered in 6.0. IRREGULAR, CUSTOM and FORCE_MAIN previously carried 16/17/18, which the engine read as RECT_TRIANG/RECT_ROUND/HORIZ_ELLIPSE.

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.

  • RECT_TRIANG – Rectangular-triangular channel.

  • RECT_ROUND – Rectangular-round channel.

  • HORIZ_ELLIPSE – Horizontal elliptical pipe.

  • VERT_ELLIPSE – Vertical elliptical pipe.

  • ARCH – Arch pipe.

  • IRREGULAR – Irregular (from transect data).

  • CUSTOM – Custom shape (from shape curve).

  • FORCE_MAIN – Force main (pressurized).

  • STREET_XSECT – Street cross-section.

  • DUMMY – Dummy — no geometry.

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
RECT_TRIANG = 16
RECT_ROUND = 17
HORIZ_ELLIPSE = 18
VERT_ELLIPSE = 19
ARCH = 20
IRREGULAR = 21
CUSTOM = 22
FORCE_MAIN = 23
STREET_XSECT = 24
DUMMY = 25

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 the explicit local-inertial finite-volume marcher. 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

add_triangle_coupling(tri_idx, node_name, cd, area)#

Append one node->cell coupling row for a triangle ([2D_TRIANGLE_NODE_MAP] repeated-row form; appends, does not overwrite).

Parameters:
Return type:

None

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.

clear_triangle_couplings()#

Remove every authored node->cell coupling row; vertex couplings are untouched.

Return type:

None

property continuity_error: float#

Global 2D surface continuity error.

Returns:

M{(total_in - total_out) / total_in}, the domain mass-balance error as a fraction.

Return type:

float

Raises:

RuntimeError – If the 2D module did not run.

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=Ellipsis, persist=Ellipsis)#

Force a coupling flux on a specific triangle.

Parameters:

  • idx (int) – Triangle index.

  • value (float) – Coupling flux value (m/s, positive = into 2D).

  • mode (L{SurfaceForcingMode}) – How the value is applied (OVERRIDE or ADD).

  • persist (L{ForcingPersist}) – PERSIST to hold until cleared; RESET for a single step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_evap(idx, value, *, mode=Ellipsis, persist=Ellipsis)#

Force evaporation on a specific triangle.

The rate is a demand: wet cells lose depth at this rate, shutting off smoothly as a cell dries (depths never go negative). The default rate is 0 unless forced. Negative values are treated as zero.

Parameters:

  • idx (int) – Triangle index.

  • value (float) – Evaporation rate (m/s; same SI convention as rainfall).

  • mode (L{SurfaceForcingMode}) – How the value is applied (OVERRIDE or ADD).

  • persist (L{ForcingPersist}) – PERSIST to hold until cleared; RESET for a single step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_evap_uniform(value, *, mode=Ellipsis, persist=Ellipsis)#

Force uniform evaporation on all triangles.

Parameters:

  • value (float) – Evaporation rate (m/s; same SI convention as rainfall).

  • mode (L{SurfaceForcingMode}) – How the value is applied (OVERRIDE or ADD).

  • persist (L{ForcingPersist}) – PERSIST to hold until cleared; RESET for a single step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_rainfall(idx, value, *, mode=Ellipsis, persist=Ellipsis)#

Force rainfall on a specific triangle.

Parameters:

  • idx (int) – Triangle index.

  • value (float) – Rainfall rate (m/s).

  • mode (L{SurfaceForcingMode}) – How the value is applied (OVERRIDE or ADD).

  • persist (L{ForcingPersist}) – PERSIST to hold until cleared; RESET for a single step.

Raises:

RuntimeError – If the C API rejects the forcing.

Return type:

None

force_rainfall_uniform(value, *, mode=Ellipsis, persist=Ellipsis)#

Force uniform rainfall on all triangles.

Parameters:

  • value (float) – Rainfall rate (m/s).

  • mode (L{SurfaceForcingMode}) – How the value is applied (OVERRIDE or ADD).

  • persist (L{ForcingPersist}) – PERSIST to hold until cleared; RESET for a 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_flow(tri_idx, edge)#

Return the prescribed flow per metre for a SPECIFIED_FLOW edge.

Parameters:

  • tri_idx (int) – Triangle index.

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

Returns:

Prescribed flow per metre of edge (m^3/s/m).

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.

Return type:

L{SurfaceBoundaryType}

Raises:

RuntimeError – If the C API call fails.

get_edge_conveyance(tri, edge)#

Return the per-edge conveyance factor in [0, 1].

Parameters:

  • tri (int) – Triangle index in [0, triangle_count).

  • edge (int) – Local edge index in {0, 1, 2}.

Returns:

Conveyance factor (1.0 = unrestricted, 0.0 = wall).

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_edge_conveyance_bulk()#

Return a NumPy array of all per-edge conveyance factors.

Length is triangle_count * 3, indexed [tri*3 + edge].

Return type:

np.ndarray

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[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[float64], NDArray[float64], NDArray[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_mass_balance()#

Return the global 2D mass-balance terms.

Returns:

Mapping with keys init_storage, final_storage, rainfall_in, coupling_1d_to_2d_in, coupling_2d_to_1d_out, outfall_in, boundary_in, boundary_out, C{evap_out} (all m^3) and continuity_error (fraction).

Return type:

dict[str, float]

Raises:

RuntimeError – If the 2D module did not run.

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_continuity_err()#

Return cumulative maximum M{abs(continuity residual)} envelope per triangle.

Returns:

Array of shape (n_triangles,) with dtype float64, in m^3/s.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_stat_max_depths()#

Return cumulative maximum-depth envelope for all triangles.

Returns:

Array of shape (n_triangles,) with dtype float64, in m.

Return type:

np.ndarray

Raises:

RuntimeError – If the C API call fails.

get_stat_max_velocities()#

Return cumulative maximum velocity-magnitude envelope per triangle.

Returns:

Array of shape (n_triangles,) with dtype float64, in m/s.

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_coupling_row(row_idx)#

Read one authored row: (tri_idx, node_idx, cd, area); node_idx is -1 if unresolved.

Parameters:

row_idx (int)

Return type:

tuple[int, int, float, float]

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_tag(idx)#

Return the descriptive tag of a triangle ([2D_TRIANGLES] TAG).

Parameters:

idx (int)

Return type:

str

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_coupling_area(vertex_idx)#

Return the coupling exchange area of a vertex.

Corresponds to the [2D_VERTEX_NODE_MAP] AREA column in m^2 (default 1.0).

Parameters:

vertex_idx (int) – Vertex index (0-based).

Returns:

Exchange area in m^2.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_vertex_coupling_cd(vertex_idx)#

Return the coupling discharge coefficient of a vertex.

Corresponds to the [2D_VERTEX_NODE_MAP] CD column (default 0.65).

Parameters:

vertex_idx (int) – Vertex index (0-based).

Returns:

Discharge coefficient.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

get_vertex_head(idx)#

Scalar water-surface head at one mesh vertex (project units).

Return type:

float

Parameters:

idx (int)

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.

get_vertex_render_depths()#

Return render-oriented signed water depths at all vertices.

The wet-masked, depth-weighted free-surface reconstruction eta_v - z_v (m) that GUIs should interpolate for water-surface rendering. 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.

get_vertex_tag(idx)#

Return the descriptive tag of a vertex ([2D_VERTICES] TAG).

Parameters:

idx (int)

Return type:

str

get_vertex_xyz(idx)#

Scalar (x, y, z) for one mesh vertex (project units).

Return type:

tuple[float, float, float]

Parameters:

idx (int)

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.

prepare_for_edit()#

Make the parsed 2D mesh editable without a full initialize().

Return type:

None

reset_edge_conveyance()#

Reset every edge’s conveyance factor to 1.0 (unrestricted).

Return type:

None

set_edge_bc_flow(tri_idx, edge, flow)#

Set the prescribed flow per metre for a SPECIFIED_FLOW edge.

Parameters:

  • tri_idx (int) – Triangle index.

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

  • flow (float) – Prescribed flow per metre of edge (m^3/s/m).

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_edge_bc_flow_tseries_name(tri_idx, edge, name)#

Set the timeseries name driving a SPECIFIED_FLOW edge.

Parameters:

  • tri_idx (int) – Triangle index.

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

  • name (str) – Timeseries name, or "" to clear.

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

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_rating_curve_name(tri_idx, edge, name)#

Set the rating-curve name driving a RATING_CURVE edge.

Parameters:

  • tri_idx (int) – Triangle index.

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

  • name (str) – Rating-curve name, or "" to clear.

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_tseries_name(tri_idx, edge, name)#

Set the timeseries name driving a SPECIFIED_STAGE edge.

Parameters:

  • tri_idx (int) – Triangle index.

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

  • name (str) – Timeseries name, or "" to clear.

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 (L{SurfaceBoundaryType}) – Boundary condition type.

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_edge_conveyance(tri, edge, conveyance)#

Set the per-edge conveyance factor in [0, 1].

For interior edges the value is mirrored to the partner slot on the neighbouring triangle so mass conservation is preserved.

Parameters:

  • tri (int) – Triangle index in [0, triangle_count).

  • edge (int) – Local edge index in {0, 1, 2}.

  • conveyance (float) – New value in [0, 1].

Raises:

RuntimeError – If the C API rejects the assignment.

Return type:

None

set_triangle_mannings(idx, n)#

Set Manning’s M{n} for a triangle (must be strictly positive).

Parameters:
Return type:

None

set_triangle_tag(idx, tag)#

Set the descriptive tag of a triangle (empty string clears it).

Parameters:
Return type:

None

set_vertex_coupled_node(vertex_idx, node_name)#

Couple a mesh vertex to a 1D SWMM node by name ("" clears).

Parameters:

  • vertex_idx (int)

  • node_name (str)

Return type:

None

set_vertex_coupling_area(vertex_idx, area)#

Set the coupling exchange area of a vertex in m^2 (must be > 0).

Parameters:
Return type:

None

set_vertex_coupling_cd(vertex_idx, cd)#

Set the coupling discharge coefficient of a vertex (must be > 0).

Parameters:
Return type:

None

set_vertex_tag(idx, tag)#

Set the descriptive tag of a vertex (empty string clears it).

Parameters:
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 solver_last_step: float#

The explicit marcher’s last sub-step size in seconds.

Renamed from cvode_last_step with the D2 CVODE/ARKODE retirement.

Returns:

Step size.

Return type:

float

Raises:

RuntimeError – If the C API call fails.

property solver_steps: int#

Number of explicit-marcher sub-steps in the last advance.

Renamed from cvode_steps with the D2 CVODE/ARKODE retirement.

Returns:

Step count.

Return type:

int

Raises:

RuntimeError – If the C API call fails.

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 triangle_coupling_rows: int#

Number of authored node->cell coupling rows.

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_SCALEFACTOR – Rainfall scaling factor (dimensionless, > 0)

GAGE_TOTAL_PRECIPITATION = Ellipsis#
GAGE_RAINFALL = Ellipsis#
GAGE_SNOWFALL = Ellipsis#
GAGE_SCALEFACTOR = 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

  • API_PET – API prescribed potential evapotranspiration rate

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#
API_PET = Ellipsis#
GW_MOISTURE = Ellipsis#
GW_LOWER_DEPTH = Ellipsis#
SNOW_SWE = Ellipsis#
SNOW_FW = Ellipsis#
SNOW_ATI = Ellipsis#
SNOW_COLDC = Ellipsis#
RAIN_SCALE_FACTOR = Ellipsis#
SNOW_SCALE_FACTOR = 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

  • EVAP_RATE – Current climate-derived evaporation rate (read-only)

  • TEMPERATURE – Current air temperature (read-only)

  • API_TEMPERATURE – API prescribed air temperature

  • WIND_SPEED – Current wind speed (read-only)

  • API_WIND_SPEED – API prescribed wind speed

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#
EVAP_RATE = Ellipsis#
TEMPERATURE = Ellipsis#
API_TEMPERATURE = Ellipsis#
WIND_SPEED = Ellipsis#
API_WIND_SPEED = Ellipsis#
API_EVAP = Ellipsis#
EVAP_DRY_ONLY = Ellipsis#
class SWMMPollutantProperties(*values)#

Bases: Enum

Enumeration of SWMM pollutant properties (runtime-settable source concentrations in pollutant units).

Variables:

  • RAIN_CONCENTRATION – Rain (wet deposition) concentration

  • GW_CONCENTRATION – Groundwater inflow concentration

  • RDII_CONCENTRATION – RDII inflow concentration

  • DWF_CONCENTRATION – Dry weather sanitary flow concentration

  • KDECAY – First-order decay constant (1/day); live each step

  • CO_POLLUTANT – Co-pollutant index (-1 = none)

  • CO_FRACTION – Co-pollutant fraction (0-1)

  • SNOW_ONLY – Buildup-only-under-snow flag (0/1)

  • INIT_CONCENTRATION – Initial network concentration (pre-start only)

RAIN_CONCENTRATION = Ellipsis#
GW_CONCENTRATION = Ellipsis#
RDII_CONCENTRATION = Ellipsis#
DWF_CONCENTRATION = Ellipsis#
KDECAY = Ellipsis#
CO_POLLUTANT = Ellipsis#
CO_FRACTION = Ellipsis#
SNOW_ONLY = Ellipsis#
INIT_CONCENTRATION = Ellipsis#
class SWMMPatternProperties(*values)#

Bases: Enum

Enumeration of SWMM time-pattern properties (runtime-settable multiplier factors). For FACTOR pass the 0-based factor position as the sub_index argument of set_value/get_value.

Variables:

  • FACTOR – One multiplier factor (sub_index = factor position)

  • COUNT – Number of factors in the pattern (read-only)

  • TYPE – Pattern type code (read-only): 0 monthly/1 daily/2 hourly/3 weekend

FACTOR = Ellipsis#
COUNT = Ellipsis#
TYPE = Ellipsis#
class SWMMLandUseProperties(*values)#

Bases: Enum

Enumeration of SWMM land-use properties (runtime-settable street sweeping parameters).

Buildup/washoff parameters are per land use and pollutant; pass the 0-based pollutant index as the sub_index argument.

Variables:

  • SWEEP_INTERVAL – Street-sweeping interval (days)

  • SWEEP_REMOVAL – Fraction of buildup available for sweeping (0-1)

  • BUILDUP_FUNC – Buildup function type code (sub_index = pollutant)

  • BUILDUP_COEFF1 – Buildup coefficient c0 / max buildup

  • BUILDUP_COEFF2 – Buildup coefficient c1 / rate

  • BUILDUP_COEFF3 – Buildup coefficient c2 / exponent

  • BUILDUP_NORMALIZER – Buildup normalizer: 0 area, 1 curb length

  • WASHOFF_FUNC – Washoff function type code

  • WASHOFF_COEFF – Washoff coefficient

  • WASHOFF_EXPON – Washoff exponent

  • WASHOFF_SWEEP_EFFIC – Washoff street-sweeping efficiency (0-1)

  • WASHOFF_BMP_EFFIC – Washoff BMP efficiency (0-1)

SWEEP_INTERVAL = Ellipsis#
SWEEP_REMOVAL = Ellipsis#
BUILDUP_FUNC = Ellipsis#
BUILDUP_COEFF1 = Ellipsis#
BUILDUP_COEFF2 = Ellipsis#
BUILDUP_COEFF3 = Ellipsis#
BUILDUP_NORMALIZER = Ellipsis#
WASHOFF_FUNC = Ellipsis#
WASHOFF_COEFF = Ellipsis#
WASHOFF_EXPON = Ellipsis#
WASHOFF_SWEEP_EFFIC = Ellipsis#
WASHOFF_BMP_EFFIC = Ellipsis#
class SWMMAquiferProperties(*values)#

Bases: Enum

Enumeration of SWMM aquifer properties (input-file units).

The flux-coefficient properties (conductivity, slopes, evap/loss coefficients) are read live each step and are settable both before the simulation starts and while it is running; the structural / initial-condition properties are pre-start-only.

Variables:

  • POROSITY – Porosity (volumetric fraction, pre-start-only)

  • WILTING_POINT – Wilting point (volumetric fraction, pre-start-only)

  • FIELD_CAPACITY – Field capacity (volumetric fraction, pre-start-only)

  • CONDUCTIVITY – Saturated hydraulic conductivity (in/hr or mm/hr)

  • CONDUCT_SLOPE – Conductivity slope

  • TENSION_SLOPE – Tension slope (ft or m)

  • UPPER_EVAP_FRAC – Upper-zone evaporation fraction (0-1)

  • LOWER_EVAP_DEPTH – Lower-zone evaporation depth (ft or m)

  • LOWER_LOSS_COEFF – Lower-zone seepage-loss coefficient (in/hr or mm/hr)

  • BOTTOM_ELEV – Aquifer bottom elevation (ft or m, pre-start-only)

  • WATER_TABLE_ELEV – Initial water table elevation (ft or m, pre-start-only)

  • UPPER_MOISTURE – Initial upper-zone moisture (volumetric fraction, pre-start-only)

POROSITY = Ellipsis#
WILTING_POINT = Ellipsis#
FIELD_CAPACITY = Ellipsis#
CONDUCTIVITY = Ellipsis#
CONDUCT_SLOPE = Ellipsis#
TENSION_SLOPE = Ellipsis#
UPPER_EVAP_FRAC = Ellipsis#
LOWER_EVAP_DEPTH = Ellipsis#
LOWER_LOSS_COEFF = Ellipsis#
BOTTOM_ELEV = Ellipsis#
WATER_TABLE_ELEV = Ellipsis#
UPPER_MOISTURE = 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

clear_treatment(node_index, pollutant_index)#

Remove the treatment expression for a node/pollutant pair.

Callable before the simulation starts or while it is running; zero removal applies from the next routing step on.

Parameters:

  • node_index (int or str) – Node index or name (e.g., 0, ‘J1’)

  • pollutant_index (int) – Pollutant index (e.g., 0)

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_lid_drain(lid_index, coeff, expon, offset)#

Set the underdrain flow parameters of a LID process at runtime.

The drain parameters are read live each routing step, so a mid-run edit takes effect on the next step. Values use input-file units, matching the [LID_CONTROLS] DRAIN line.

Parameters:

  • lid_index (int or str) – LID process index or name (e.g., 0, ‘RB1’)

  • coeff (float) – Underdrain flow coefficient (in/hr or mm/hr)

  • expon (float) – Underdrain head exponent

  • offset (float) – Offset height of the underdrain (in or mm)

Return type:

None

set_treatment(node_index, pollutant_index, expression)#

Set (or replace) the treatment expression for a node/pollutant pair.

Callable before the simulation starts or while it is running; a mid-run edit is evaluated from the next routing step on. A failed parse raises and leaves no treatment in place for the pair.

Parameters:

  • node_index (int or str) – Node index or name (e.g., 0, ‘J1’)

  • pollutant_index (int) – Pollutant index (e.g., 0)

  • expression (str) – Treatment expression in input-file form, e.g. “R = 0.5” or “C = BOD * 0.2”

Return type:

None

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 rain_scale_factor: float#

Per-subcatchment rainfall scale factor (> 0; 1.0 = no scaling).

Optional [SUBCATCHMENTS] token 9. Multiplies the gage-derived rainfall, composing with the gage scale factor. Settable mid-run. Raises if <= 0.

property snow_scale_factor: float#

Per-subcatchment snowfall scale factor (> 0; 1.0 = no scaling).

Optional [SUBCATCHMENTS] token 10. Composes with the gage snow catch factor (SCF). Settable mid-run. Raises if <= 0.

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_api_pet(value, log=None)[source]#

Prescribe a potential evapotranspiration rate for this subcatchment.

Overrides the climate-derived evaporation rate for the subcatchment’s surface, LID, and groundwater upper-zone evaporation. The prescribed rate is applied as-is (it bypasses the DRY_ONLY option and monthly adjustments). Actual evaporation is capped to available water, so losses appear in the runoff totals under evaporation. Persists until cleared with clear_api_pet.

Parameters:

  • value (float) – PET rate in user units (in/day or mm/day).

  • log (ExternalForcingLog or None) – Optional external forcing log for audit.

Returns:

None

Return type:

None

get_api_pet()[source]#

Return the currently prescribed PET rate for this subcatchment.

Returns:

Prescribed PET rate in user units (in/day or mm/day), or a negative value when no prescription is active.

Return type:

float

clear_api_pet(log=None)[source]#

Clear any prescribed PET rate, reverting to climate-derived evaporation.

Parameters:

log (ExternalForcingLog or None) – Optional external forcing log for audit.

Returns:

None

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 gw_moisture: float#

Groundwater upper-zone moisture content (state injection).

Reading returns the current upper-zone moisture; setting injects it mid-run. The subcatchment must have groundwater. Mass balance reflects the resulting storage discontinuity (hotstart-equivalent semantics).

property gw_lower_depth: float#

Groundwater saturated-zone depth above the aquifer bottom (project length units; state injection).

set_snow_state(surface, swe=None, fw=None, ati=None, coldc=None)[source]#

Inject the snow-pack state on one snow surface (state assimilation).

Parameters:

  • surface (int) – Snow subarea (0 plowable, 1 impervious, 2 pervious), passed through as the property sub_index.

  • swe (float or None) – Snow water equivalent in project depth units; omit to leave unchanged.

  • fw (float or None) – Free water in project depth units; omit to leave unchanged.

  • ati (float or None) – Antecedent temperature index (deg F US, deg C SI); omit to leave unchanged.

  • coldc (float or None) – Cold content in project depth units; omit to leave unchanged.

Return type:

None

get_snow_state(surface)[source]#

Read the snow-pack state on one snow surface.

Parameters:

surface (int) – Snow subarea (0 plowable, 1 impervious, 2 pervious).

Returns:

{"swe", "fw", "ati", "coldc"} in project units.

Return type:

dict

set_ponded_concentration(pollutant_index, value)[source]#

Place pollutant mass on this subcatchment’s ponded water.

Requires ponded depth > 0 (set during the storm). The injected mass washes off into the quality mass balance.

Parameters:

  • pollutant_index (int) – 0-based pollutant index (property sub_index).

  • value (float) – Ponded concentration in the pollutant’s units.

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.

property scale_factor: float#

Rainfall scaling factor (dimensionless; 1.0 = no scaling).

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.

get_evap_rate()[source]#

Return the current climate-derived evaporation rate.

The rate the engine would apply in the absence of any PET prescription, including monthly adjustments (read-only). Intended for caller-side composition with LegacySubcatchment.set_api_pet: read this rate, apply your own adjustment logic, and prescribe the result.

Returns:

Evaporation rate in user units (in/day or mm/day).

Return type:

float

get_temperature()[source]#

Return the current air temperature.

Returns:

Air temperature in user units (deg F or deg C).

Return type:

float

set_api_temperature(value)[source]#

Prescribe the air temperature used for snowmelt and temperature-derived evaporation.

Overrides the climate data-source value (bypassing monthly adjustments) and keeps derived quantities (saturation vapor pressure) consistent. Persists until cleared with clear_api_temperature.

Parameters:

value (float) – Air temperature in user units (deg F or deg C).

Returns:

None

Return type:

None

get_api_temperature()[source]#

Return the prescribed air temperature.

Returns:

Prescribed temperature in user units, or -999 when no prescription is active.

Return type:

float

clear_api_temperature()[source]#

Clear any prescribed air temperature, reverting to climate data.

Returns:

None

Return type:

None

get_wind_speed()[source]#

Return the current wind speed.

Returns:

Wind speed in user units (mph or km/hr).

Return type:

float

set_api_wind_speed(value)[source]#

Prescribe the wind speed used in rain-on-snow melt.

Overrides the monthly/climate-file value. Persists until cleared with clear_api_wind_speed.

Parameters:

value (float) – Wind speed in user units (mph or km/hr), >= 0.

Returns:

None

Return type:

None

get_api_wind_speed()[source]#

Return the prescribed wind speed.

Returns:

Prescribed wind speed in user units, or a negative value when no prescription is active.

Return type:

float

clear_api_wind_speed()[source]#

Clear any prescribed wind speed, reverting to climate data.

Returns:

None

Return type:

None

set_api_evap_rate(value)[source]#

Prescribe the system-wide evaporation rate.

Replaces the climate-derived rate (after monthly adjustments) for every consumer — subcatchments, LID units, groundwater, conduits and storage nodes. Per-subcatchment LegacySubcatchment.set_api_pet still takes precedence. Persists until cleared with clear_api_evap_rate.

Parameters:

value (float) – Evaporation rate in user units (in/day or mm/day), >= 0.

Returns:

None

Return type:

None

get_api_evap_rate()[source]#

Return the prescribed system-wide evaporation rate.

Returns:

Prescribed rate in user units, or a negative value when no prescription is active.

Return type:

float

clear_api_evap_rate()[source]#

Clear any prescribed evaporation rate, reverting to climate data.

Returns:

None

Return type:

None

set_evap_dry_only(flag)[source]#

Set the evaporation DRY_ONLY option at runtime.

Parameters:

flag (bool) – True suppresses evaporation during rainfall.

Returns:

None

Return type:

None

get_evap_dry_only()[source]#

Return the evaporation DRY_ONLY option.

Returns:

True if evaporation is suppressed during rainfall.

Return type:

bool

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