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 |
|---|---|
|
SWMM binary output path. |
| RAISES | DESCRIPTION |
|---|---|
OutputError
|
If the file cannot be opened, has incomplete metadata, has an unsupported schema, or fails structural validation. |
Examples:
| 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:
|
metadata |
Return eagerly parsed immutable output metadata.
TYPE:
|
source_path |
Return the path supplied when this reader was constructed.
TYPE:
|
times |
Return the cached Nominal Report Date axis. |
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:
source_path
property
source_path: Path
Return the path supplied when this reader was constructed.
| RETURNS | DESCRIPTION |
|---|---|
Path
|
Informational local source path. |
Examples:
times
property
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 |
|---|---|
|
SWMM binary output path. |
| RAISES | DESCRIPTION |
|---|---|
OutputError
|
If opening, reading, allocation, or file validation fails. |
Examples:
link_series
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:
|
|
Family-specific typed attribute or exact canonical string.
TYPE:
|
|
Inclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Exclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Selective-read strategy when true; by-period strategy when false.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OutputTimeSeries
|
Canonical selection, nominal times, and aligned values. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If a selector, bound, or |
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 |
|---|---|
|
Zero-based node position or exact stored name.
TYPE:
|
|
Family-specific typed attribute or exact canonical string.
TYPE:
|
|
Inclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Exclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Selective-read strategy when true; by-period strategy when false.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OutputTimeSeries
|
Canonical selection, nominal times, and aligned values. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If a selector, bound, or |
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 |
|---|---|
|
Ordered selections. Duplicate selections remain duplicate result columns.
TYPE:
|
|
Inclusive local period offset or naive Nominal Report Date lower bound.
TYPE:
|
|
Exclusive local period offset or naive Nominal Report Date lower bound.
TYPE:
|
|
If
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
BulkSeriesResult
|
Shared nominal time axis and ordered immutable value series. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If selections, bounds, or |
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 |
|---|---|
|
Inclusive period offset or naive Nominal Report Date lower bound.
TYPE:
|
|
Exclusive period offset or naive Nominal Report Date lower bound.
TYPE:
|
| 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 |
|---|---|
|
Zero-based subcatchment position or exact stored name.
TYPE:
|
|
Family-specific typed attribute or exact canonical string.
TYPE:
|
|
Inclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Exclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Selective-read strategy when true; by-period strategy when false.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OutputTimeSeries
|
Canonical selection, nominal times, and aligned values. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If a selector, bound, or |
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 |
|---|---|
|
Typed system attribute or exact canonical string.
TYPE:
|
|
Inclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Exclusive period offset or naive nominal-date lower bound.
TYPE:
|
|
Selective-read strategy when true; by-period strategy when false.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
OutputTimeSeries
|
Canonical system selection, nominal times, and aligned values. |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If an attribute, bound, or |
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. |
value
value(period_offset: int, selection_offset: int) -> float
Return one value using offsets local to this result.
| PARAMETER | DESCRIPTION |
|---|---|
|
Zero-based position in :attr:
TYPE:
|
|
Zero-based position in :attr:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
float
|
Selected stored result value promoted exactly from |
| 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. |
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. |
SeriesSelection
dataclass
Select one stored result attribute for one output element.
| METHOD | DESCRIPTION |
|---|---|
__post_init__ |
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. |
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:
|
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. |
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. |
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. |
nominal_date
Return the rounded naive date for a zero-based report period.
| PARAMETER | DESCRIPTION |
|---|---|
|
Zero-based report-period offset.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
datetime or None
|
Nominal Report Date rounded to a whole second using round-half-to-even,
or |
| RAISES | DESCRIPTION |
|---|---|
TypeError
|
If |
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
NodeMetadata
dataclass
LinkMetadata
dataclass
PollutantMetadata
dataclass
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. |
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:
|
is_success |
Report whether the finalized run completed without a warning.
TYPE:
|
UnknownCode
dataclass
Preserve one unknown signed 32-bit categorical code.
| METHOD | DESCRIPTION |
|---|---|
__post_init__ |
Reject booleans and values outside the stored signed range. |