Skip to content

Binary output

Open a SWMM binary output file with OutputReader to inspect its metadata and read immutable result series. It detects finalized files and recovers complete records when the final trailer is missing. An interrupted run may still have useful results to offer.

The reader exposes exact Stored Report Dates and a shared Nominal Report Date axis. It wraps the standalone swmm-output reader and works independently of a live Simulation.

Read finalized or incomplete SWMM binary output without solver ownership.

CLASS DESCRIPTION
OutputReader

Own and query one local SWMM binary output file.

BulkSeriesResult

Immutable column-oriented result for an ordered bulk request.

OutputValueSeries

Immutable values aligned to one canonical selection.

OutputTimeSeries

Immutable dates and values aligned to one canonical selection.

SeriesSelection

Select one stored result attribute for one output element.

PollutantAttribute

Select one pollutant result attribute.

OutputName

Preserve exact stored bytes with an optional lossless UTF-8 view.

OutputMetadata

Complete immutable metadata parsed from one SWMM output file.

ResultSchema

Ordered, immutable family-specific result schema entries.

ReportTiming

Immutable report schedule and available complete period count.

SubcatchmentMetadata

Exact stored subcatchment identity and area.

NodeMetadata

Exact stored node identity, kind, and static properties.

LinkMetadata

Exact stored link identity, kind, and static properties.

PollutantMetadata

Exact stored pollutant identity, name, and concentration units.

ResultElementType

Identify one physical output-result family.

SubcatchmentResultAttribute

Identify one known SWMM/PySWMM subcatchment result attribute.

NodeResultAttribute

Identify one known SWMM/PySWMM node result attribute.

LinkResultAttribute

Identify one known SWMM/PySWMM link result attribute.

SystemResultAttribute

Identify one known SWMM/PySWMM system result attribute.

ResultAttributeCode

Preserve one unknown signed 32-bit result-attribute code.

ConcentrationUnits

Identify pollutant concentration units stored in the output file.

FlowUnits

Represent supported project flow-unit codes.

UnitSystem

Represent the project's US customary or SI unit system.

NodeKind

Represent configured node subtypes.

LinkKind

Represent configured link subtypes.

RunStatus

Preserve a finalized status code or mark an unfinalized output.

UnknownCode

Preserve one unknown signed 32-bit categorical code.

OutputError

Report one structured binary-output failure.

OutputReader

Own and query one local SWMM binary output file.

A valid final trailer is detected automatically. Without one, the reader exposes every complete result record visible when the file is opened.

PARAMETER DESCRIPTION

source_path

SWMM binary output path.

TYPE: str or PathLike[str]

RAISES DESCRIPTION
OutputError

If the file cannot be opened, has incomplete metadata, has an unsupported schema, or fails structural validation.

Examples:

>>> reader = OutputReader("model.out")
>>> reader.metadata.report_timing.period_count > 0
True
METHOD DESCRIPTION
__init__

Open the file and eagerly parse immutable output metadata.

link_series

Read one link result series.

node_series

Read one node result series.

read_bulk_series

Read ordered result series using one of two physical I/O strategies.

read_stored_dates

Read exact Stored Report Date serial values.

subcatchment_series

Read one subcatchment result series.

system_series

Read one system result series.

ATTRIBUTE DESCRIPTION
is_finalized

Return whether the file contained a valid final trailer when opened.

TYPE: bool

metadata

Return eagerly parsed immutable output metadata.

TYPE: OutputMetadata

source_path

Return the path supplied when this reader was constructed.

TYPE: Path

times

Return the cached Nominal Report Date axis.

TYPE: tuple[datetime, ...]

is_finalized property

is_finalized: bool

Return whether the file contained a valid final trailer when opened.

metadata property

metadata: OutputMetadata

Return eagerly parsed immutable output metadata.

RETURNS DESCRIPTION
OutputMetadata

Physical identities, schemas, units, status, and report timing.

Examples:

>>> reader = OutputReader("model.out")
>>> reader.metadata.nodes[0].index
0

source_path property

source_path: Path

Return the path supplied when this reader was constructed.

RETURNS DESCRIPTION
Path

Informational local source path.

Examples:

>>> reader = OutputReader("model.out")
>>> reader.source_path.name
'model.out'

times property

times: tuple[datetime, ...]

Return the cached Nominal Report Date axis.

RETURNS DESCRIPTION
tuple of datetime

Naive datetimes rounded to whole seconds using round-half-to-even.

RAISES DESCRIPTION
OutputError

If a nominal report date is outside Python's datetime range.

Examples:

>>> reader = OutputReader("model.out")
>>> len(reader.times) == reader.metadata.report_timing.period_count
True
Notes

The tuple is built on first access and then reused by identity. Stored Report Dates remain separately available through :meth:read_stored_dates.

__init__

__init__(source_path: _PathInput) -> None
PARAMETER DESCRIPTION
source_path

SWMM binary output path.

TYPE: str or PathLike[str]

RAISES DESCRIPTION
OutputError

If opening, reading, allocation, or file validation fails.

Examples:

>>> reader = OutputReader("model.out")
>>> reader.source_path.name
'model.out'
link_series(element: _ElementSelector, attribute: LinkResultAttribute | PollutantAttribute | ResultAttributeCode | str, start: int | datetime | None = None, end: int | datetime | None = None, *, low_memory: bool = False) -> OutputTimeSeries

Read one link result series.

PARAMETER DESCRIPTION

Zero-based link position or exact stored name.

TYPE: int, str, bytes, or OutputName

Family-specific typed attribute or exact canonical string.

TYPE: LinkResultAttribute, PollutantAttribute, ResultAttributeCode, or str

Inclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

Exclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

Selective-read strategy when true; by-period strategy when false.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
OutputTimeSeries

Canonical selection, nominal times, and aligned values.

RAISES DESCRIPTION
TypeError

If a selector, bound, or low_memory has an invalid type.

ValueError

If a selector or bound has an invalid value.

OutputError

If the element or attribute is absent or ambiguous, the range is inverted, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> flow = reader.link_series("C1", "flow_rate", low_memory=True)
>>> len(flow.times) == len(flow.values)
True

node_series

node_series(element: _ElementSelector, attribute: NodeResultAttribute | PollutantAttribute | ResultAttributeCode | str, start: int | datetime | None = None, end: int | datetime | None = None, *, low_memory: bool = False) -> OutputTimeSeries

Read one node result series.

PARAMETER DESCRIPTION
element

Zero-based node position or exact stored name.

TYPE: int, str, bytes, or OutputName

attribute

Family-specific typed attribute or exact canonical string.

TYPE: NodeResultAttribute, PollutantAttribute, ResultAttributeCode, or str

start

Inclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

end

Exclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

low_memory

Selective-read strategy when true; by-period strategy when false.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
OutputTimeSeries

Canonical selection, nominal times, and aligned values.

RAISES DESCRIPTION
TypeError

If a selector, bound, or low_memory has an invalid type.

ValueError

If a selector or bound has an invalid value.

OutputError

If the element or attribute is absent or ambiguous, the range is inverted, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> depth = reader.node_series("J1", "invert_depth", start=0, end=12)
>>> depth.selection.element_type is ResultElementType.NODE
True

read_bulk_series

read_bulk_series(selections: Sequence[SeriesSelection], start: int | datetime | None = None, end: int | datetime | None = None, *, low_memory: bool = False) -> BulkSeriesResult

Read ordered result series using one of two physical I/O strategies.

PARAMETER DESCRIPTION
selections

Ordered selections. Duplicate selections remain duplicate result columns.

TYPE: Sequence of SeriesSelection

start

Inclusive local period offset or naive Nominal Report Date lower bound.

TYPE: int, datetime, or None DEFAULT: None

end

Exclusive local period offset or naive Nominal Report Date lower bound.

TYPE: int, datetime, or None DEFAULT: None

low_memory

If False, read one complete result payload per selected period. If True, read only selected adjacent cell runs with smaller scratch space.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
BulkSeriesResult

Shared nominal time axis and ordered immutable value series.

RAISES DESCRIPTION
TypeError

If selections, bounds, or low_memory have invalid types.

ValueError

If a bound is negative, out of range, or timezone-aware.

OutputError

If a selection is invalid, bounds are inverted, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> selections = (
...     SeriesSelection("node", "J1", "invert_depth"),
...     SeriesSelection("link", "C1", "flow_rate"),
... )
>>> result = reader.read_bulk_series(selections, start=0, end=12)
>>> len(result.series)
2
>>> narrow = reader.read_bulk_series(
...     selections,
...     start=0,
...     end=12,
...     low_memory=True,
... )
>>> narrow == result
True
Notes

Both strategies return bit-identical values. low_memory=False usually favors wide requests by reducing physical read calls. low_memory=True limits scratch memory and avoids reading unselected payload cells.

read_stored_dates

read_stored_dates(start: int | datetime | None = None, end: int | datetime | None = None) -> list[float]

Read exact Stored Report Date serial values.

PARAMETER DESCRIPTION
start

Inclusive period offset or naive Nominal Report Date lower bound.

TYPE: int, datetime, or None DEFAULT: None

end

Exclusive period offset or naive Nominal Report Date lower bound.

TYPE: int, datetime, or None DEFAULT: None

RETURNS DESCRIPTION
list of float

Exact finite SWMM serial-day values in resolved period order.

RAISES DESCRIPTION
TypeError

If a bound has an invalid type.

ValueError

If a bound is negative, out of range, or timezone-aware.

OutputError

If bounds are inverted, a stored date is non-finite, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> stored = reader.read_stored_dates(start=0, end=2)
>>> len(stored)
2
Notes

Stored Report Dates are file facts and never select, round, or replace the nominal datetime axis. Integer-only reads do not populate :attr:times.

subcatchment_series

subcatchment_series(element: _ElementSelector, attribute: SubcatchmentResultAttribute | PollutantAttribute | ResultAttributeCode | str, start: int | datetime | None = None, end: int | datetime | None = None, *, low_memory: bool = False) -> OutputTimeSeries

Read one subcatchment result series.

PARAMETER DESCRIPTION
element

Zero-based subcatchment position or exact stored name.

TYPE: int, str, bytes, or OutputName

attribute

Family-specific typed attribute or exact canonical string.

TYPE: SubcatchmentResultAttribute, PollutantAttribute, ResultAttributeCode, or str

start

Inclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

end

Exclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

low_memory

Selective-read strategy when true; by-period strategy when false.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
OutputTimeSeries

Canonical selection, nominal times, and aligned values.

RAISES DESCRIPTION
TypeError

If a selector, bound, or low_memory has an invalid type.

ValueError

If a selector or bound has an invalid value.

OutputError

If the element or attribute is absent or ambiguous, the range is inverted, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> runoff = reader.subcatchment_series("S1", "runoff_flow")
>>> len(runoff.times) == len(runoff.values)
True

system_series

system_series(attribute: SystemResultAttribute | ResultAttributeCode | str, start: int | datetime | None = None, end: int | datetime | None = None, *, low_memory: bool = False) -> OutputTimeSeries

Read one system result series.

PARAMETER DESCRIPTION
attribute

Typed system attribute or exact canonical string.

TYPE: SystemResultAttribute, ResultAttributeCode, or str

start

Inclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

end

Exclusive period offset or naive nominal-date lower bound.

TYPE: int, datetime, or None DEFAULT: None

low_memory

Selective-read strategy when true; by-period strategy when false.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
OutputTimeSeries

Canonical system selection, nominal times, and aligned values.

RAISES DESCRIPTION
TypeError

If an attribute, bound, or low_memory has an invalid type.

ValueError

If an attribute or bound has an invalid value.

OutputError

If the attribute is absent or ambiguous, the range is inverted, or native I/O fails.

Examples:

>>> reader = OutputReader("model.out")
>>> rainfall = reader.system_series("rainfall")
>>> rainfall.selection.element is None
True

BulkSeriesResult dataclass

Immutable column-oriented result for an ordered bulk request.

METHOD DESCRIPTION
__post_init__

Freeze dimensions and enforce shared-axis alignment.

__repr__

Summarize both result dimensions without rendering data.

value

Return one value using offsets local to this result.

__post_init__

__post_init__() -> None

Freeze dimensions and enforce shared-axis alignment.

__repr__

__repr__() -> str

Summarize both result dimensions without rendering data.

value

Return one value using offsets local to this result.

PARAMETER DESCRIPTION
period_offset

Zero-based position in :attr:times.

TYPE: int

selection_offset

Zero-based position in :attr:series.

TYPE: int

RETURNS DESCRIPTION
float

Selected stored result value promoted exactly from f32.

RAISES DESCRIPTION
IndexError

If either offset is not an integer or is outside its result dimension.

Examples:

>>> selection = SeriesSelection("system", None, "rainfall")
>>> values = OutputValueSeries(selection, (1.0, 2.0))
>>> result = BulkSeriesResult(
...     (datetime(2020, 1, 1), datetime(2020, 1, 2)),
...     (values,),
... )
>>> result.value(1, 0)
2.0

OutputValueSeries dataclass

Immutable values aligned to one canonical selection.

METHOD DESCRIPTION
__post_init__

Freeze the value sequence and validate its selection.

__repr__

Summarize the selection and period count without rendering values.

__post_init__

__post_init__() -> None

Freeze the value sequence and validate its selection.

__repr__

__repr__() -> str

Summarize the selection and period count without rendering values.

OutputTimeSeries dataclass

Immutable dates and values aligned to one canonical selection.

METHOD DESCRIPTION
__post_init__

Freeze dimensions and enforce series alignment.

__repr__

Summarize the selection and period count without rendering data.

__post_init__

__post_init__() -> None

Freeze dimensions and enforce series alignment.

__repr__

__repr__() -> str

Summarize the selection and period count without rendering data.

SeriesSelection dataclass

Select one stored result attribute for one output element.

METHOD DESCRIPTION
__post_init__

Normalize and validate one family, element, and attribute.

__post_init__

__post_init__() -> None

Normalize and validate one family, element, and attribute.

PollutantAttribute dataclass

Select one pollutant result attribute.

METHOD DESCRIPTION
__post_init__

Validate an index or exact stored-name selector.

__post_init__

__post_init__() -> None

Validate an index or exact stored-name selector.

OutputName dataclass

Preserve exact stored bytes with an optional lossless UTF-8 view.

METHOD DESCRIPTION
__post_init__

Require exact immutable bytes without decoding or normalization.

__repr__

Render decoded names compactly while preserving invalid bytes.

ATTRIBUTE DESCRIPTION
text

Decode the exact stored name when it is valid UTF-8.

TYPE: str | None

text property

text: str | None

Decode the exact stored name when it is valid UTF-8.

RETURNS DESCRIPTION
str or None

Lossless UTF-8 text, or None when the stored bytes are not UTF-8.

Examples:

>>> OutputName(b"J1").text
'J1'
>>> OutputName(b"\xff").text is None
True

__post_init__

__post_init__() -> None

Require exact immutable bytes without decoding or normalization.

__repr__

__repr__() -> str

Render decoded names compactly while preserving invalid bytes.

OutputMetadata dataclass

Complete immutable metadata parsed from one SWMM output file.

METHOD DESCRIPTION
__post_init__

Freeze metadata collections and preserve the source path.

__repr__

Summarize output identity, run details, and collection sizes.

__post_init__

__post_init__() -> None

Freeze metadata collections and preserve the source path.

__repr__

__repr__() -> str

Summarize output identity, run details, and collection sizes.

ResultSchema dataclass

Ordered, immutable family-specific result schema entries.

METHOD DESCRIPTION
__post_init__

Freeze collections and reject attributes from another family.

__repr__

Summarize result families by entry count.

__post_init__

__post_init__() -> None

Freeze collections and reject attributes from another family.

__repr__

__repr__() -> str

Summarize result families by entry count.

ReportTiming dataclass

Immutable report schedule and available complete period count.

METHOD DESCRIPTION
__repr__

Summarize the schedule with compact field names.

nominal_date

Return the rounded naive date for a zero-based report period.

__repr__

__repr__() -> str

Summarize the schedule with compact field names.

nominal_date

nominal_date(period: int) -> datetime | None

Return the rounded naive date for a zero-based report period.

PARAMETER DESCRIPTION
period

Zero-based report-period offset.

TYPE: int

RETURNS DESCRIPTION
datetime or None

Nominal Report Date rounded to a whole second using round-half-to-even, or None when period is outside the available report range.

RAISES DESCRIPTION
TypeError

If period is not an integer.

OutputError

If the nominal date is outside Python's datetime range.

Examples:

>>> timing = ReportTiming(0.0, 300, 2)
>>> timing.nominal_date(0)
datetime.datetime(1899, 12, 30, 0, 5)
>>> timing.nominal_date(2) is None
True

SubcatchmentMetadata dataclass

Exact stored subcatchment identity and area.

METHOD DESCRIPTION
__repr__

Summarize the subcatchment identity and area.

__repr__

__repr__() -> str

Summarize the subcatchment identity and area.

NodeMetadata dataclass

Exact stored node identity, kind, and static properties.

METHOD DESCRIPTION
__repr__

Summarize the node identity and kind.

__repr__

__repr__() -> str

Summarize the node identity and kind.

LinkMetadata dataclass

Exact stored link identity, kind, and static properties.

METHOD DESCRIPTION
__repr__

Summarize the link identity and kind.

__repr__

__repr__() -> str

Summarize the link identity and kind.

PollutantMetadata dataclass

Exact stored pollutant identity, name, and concentration units.

METHOD DESCRIPTION
__repr__

Summarize the pollutant identity and concentration units.

__repr__

__repr__() -> str

Summarize the pollutant identity and concentration units.

ResultElementType


              flowchart TD
              swmmrs.output.ResultElementType[ResultElementType]

              

              click swmmrs.output.ResultElementType href "" "swmmrs.output.ResultElementType"
            

Identify one physical output-result family.

SubcatchmentResultAttribute


              flowchart TD
              swmmrs.output.SubcatchmentResultAttribute[SubcatchmentResultAttribute]

              

              click swmmrs.output.SubcatchmentResultAttribute href "" "swmmrs.output.SubcatchmentResultAttribute"
            

Identify one known SWMM/PySWMM subcatchment result attribute.

NodeResultAttribute


              flowchart TD
              swmmrs.output.NodeResultAttribute[NodeResultAttribute]

              

              click swmmrs.output.NodeResultAttribute href "" "swmmrs.output.NodeResultAttribute"
            

Identify one known SWMM/PySWMM node result attribute.

LinkResultAttribute


              flowchart TD
              swmmrs.output.LinkResultAttribute[LinkResultAttribute]

              

              click swmmrs.output.LinkResultAttribute href "" "swmmrs.output.LinkResultAttribute"
            

Identify one known SWMM/PySWMM link result attribute.

SystemResultAttribute


              flowchart TD
              swmmrs.output.SystemResultAttribute[SystemResultAttribute]

              

              click swmmrs.output.SystemResultAttribute href "" "swmmrs.output.SystemResultAttribute"
            

Identify one known SWMM/PySWMM system result attribute.

ResultAttributeCode dataclass

Preserve one unknown signed 32-bit result-attribute code.

METHOD DESCRIPTION
__post_init__

Reject booleans and values outside the stored signed range.

__post_init__

__post_init__() -> None

Reject booleans and values outside the stored signed range.

ConcentrationUnits


              flowchart TD
              swmmrs.output.ConcentrationUnits[ConcentrationUnits]

              

              click swmmrs.output.ConcentrationUnits href "" "swmmrs.output.ConcentrationUnits"
            

Identify pollutant concentration units stored in the output file.

FlowUnits


              flowchart TD
              swmmrs.output.FlowUnits[FlowUnits]

              

              click swmmrs.output.FlowUnits href "" "swmmrs.output.FlowUnits"
            

Represent supported project flow-unit codes.

UnitSystem


              flowchart TD
              swmmrs.output.UnitSystem[UnitSystem]

              

              click swmmrs.output.UnitSystem href "" "swmmrs.output.UnitSystem"
            

Represent the project's US customary or SI unit system.

NodeKind


              flowchart TD
              swmmrs.output.NodeKind[NodeKind]

              

              click swmmrs.output.NodeKind href "" "swmmrs.output.NodeKind"
            

Represent configured node subtypes.

LinkKind


              flowchart TD
              swmmrs.output.LinkKind[LinkKind]

              

              click swmmrs.output.LinkKind href "" "swmmrs.output.LinkKind"
            

Represent configured link subtypes.

RunStatus dataclass

Preserve a finalized status code or mark an unfinalized output.

METHOD DESCRIPTION
__post_init__

Validate a stored signed code when one is available.

ATTRIBUTE DESCRIPTION
is_finalized

Report whether the output contained a final trailer.

TYPE: bool

is_success

Report whether the finalized run completed without a warning.

TYPE: bool

is_finalized property

is_finalized: bool

Report whether the output contained a final trailer.

is_success property

is_success: bool

Report whether the finalized run completed without a warning.

RETURNS DESCRIPTION
bool

True only when the exact stored status code is zero.

Examples:

>>> RunStatus(0).is_success
True
>>> RunStatus(None).is_success
False

__post_init__

__post_init__() -> None

Validate a stored signed code when one is available.

UnknownCode dataclass

Preserve one unknown signed 32-bit categorical code.

METHOD DESCRIPTION
__post_init__

Reject booleans and values outside the stored signed range.

__post_init__

__post_init__() -> None

Reject booleans and values outside the stored signed range.

OutputError


              flowchart TD
              swmmrs.output.OutputError[OutputError]

              

              click swmmrs.output.OutputError href "" "swmmrs.output.OutputError"
            

Report one structured binary-output failure.

ATTRIBUTE DESCRIPTION
category

Stable high-level failure category.

TYPE: str

METHOD DESCRIPTION
__init__

Create an output error.

__init__

__init__(category: str, message: str) -> None
PARAMETER DESCRIPTION
category

Stable high-level failure category.

TYPE: str

message

Descriptive native failure text.

TYPE: str

Examples:

>>> error = OutputError("invalid_format", "bad output file")
>>> error.category
'invalid_format'