Simulation

Simulation is where you open a project, get its objects, and control its run. It owns the isolated SWMM project, files, lifecycle, collections, and current generation. See Package metadata for package and embedded solver identities, or the user guide for lifecycle and continuation examples.

Typed Python bindings for an isolated EPA SWMM simulation owner.

The package exposes lifecycle management, live project-object views, immutable snapshots, solver metadata, and typed public failures.

CLASS	DESCRIPTION
`Simulation`	Own an isolated SWMM project lifecycle.
`SimulationStatus`	Immutable lifecycle and progress values from one owner acquisition.

Simulation

Own an isolated SWMM project lifecycle.

PARAMETER	DESCRIPTION
`input_path`	Path to an EPA SWMM input file. TYPE: `str or PathLike[str]`
`report_path`	Destination for the generated text report. When omitted, the binding derives a report path from `input_path`. TYPE: `str or PathLike[str]` DEFAULT: `None`
`output_path`	Destination for the binary output file. When omitted, SWMM uses a scratch output artifact. TYPE: `str or PathLike[str]` DEFAULT: `None`

Notes

A Simulation owns exactly one Project Generation at a time. Collections and object views obtained from it become stale after close() or open() starts a replacement generation.

Examples:

Run a project to completion with deterministic cleanup::

from swmmrs import Simulation

with Simulation("model.inp") as simulation:
    simulation.execute()

METHOD	DESCRIPTION
`__copy__`	Reject copying Simulation Owner identity.
`__deepcopy__`	Reject deep-copying Simulation Owner identity.
`__del__`	Warn before the native owner performs best-effort destruction.
`__enter__`	Enter one cleanup scope without starting the open project.
`__exit__`	Finalize a started run and close without replacing a body exception.
`__init__`	Create and open a simulation.
`__iter__`	Return this simulation's single lifecycle iterator.
`__next__`	Advance the exclusively owned iterator or stop at its checkpoint.
`__reduce__`	Reject pickling Simulation Owner identity.
`__reduce_ex__`	Reject protocol-specific pickling of Simulation Owner identity.
`close`	Close the project and finalize owned artifacts.
`end`	Finalize the current run while retaining its project generation.
`execute`	Run the complete non-interactive lifecycle and close the project.
`fork`	Create an independent child owner at the current lifecycle boundary.
`load_checkpoint_state`	Import checkpoint physical continuation state into this open owner.
`open`	Open a fresh Project Generation on this closed facade.
`replace_amm_assignments`	Atomically replace all AMM node assignments in project units.
`replace_rdii_assignments`	Atomically replace all RTK RDII node assignments in project units.
`report`	Generate and flush the detailed report for an ended run.
`reset_solver`	Discard stale run state without reopening or validating the project.
`resume`	Resume an independent owner from an immutable Simulation Checkpoint.
`save_checkpoint`	Save a deterministic Simulation Checkpoint at the current boundary.
`save_hotstart`	Write current state in EPA hotstart format and wait until it is usable.
`sleep_workers`	Park Dynamic Wave workers until the next routing operation,
`start`	Initialize an open or ended project and enter the running state.
`step`	Advance one routing step.
`step_advance`	Set or clear the cadence used by ordinary iteration.
`stride`	Advance toward a positive whole-second interval.
`terminate`	Request orderly termination at the next iterator checkpoint.
`update_schedule`	Atomically update coupled start, report-start, and end dates.
`use_hotstart`	Set or clear persistent hotstart input for this Project Generation.

ATTRIBUTE	DESCRIPTION
`amm_assignments`	Return detached AMM node assignments in configured order. TYPE: `tuple[AmmAssignment, ...]`
`amm_models`	Return configured AMM models in project order. TYPE: `ObjectCollection[AmmModel]`
`aquifers`	Return configured aquifers in project order. TYPE: `ObjectCollection[Aquifer]`
`configuration_dirty`	Return whether accepted configuration needs pre-start preparation. TYPE: `bool`
`controls`	Return configured control rules in project order. TYPE: `ObjectCollection[ControlRule]`
`current_time`	Return the current model wall-clock time. TYPE: `datetime`
`curves`	Return configured curves in project order. TYPE: `ObjectCollection[Curve]`
`effective_threads`	Return the actual caller-inclusive solver team size. TYPE: `int`
`elapsed_time`	Return elapsed model time from the configured start. TYPE: `timedelta`
`end_time`	Timezone-naive end time. Setter lifecycle: `OPEN`, `ENDED`. TYPE: `datetime`
`flow_units`	Return configured project flow units. TYPE: `FlowUnits`
`inlet_designs`	Return configured inlet designs in project order. TYPE: `ObjectCollection[InletDesign]`
`input_path`	Return the absolute input path from the last successful open. TYPE: `Path`
`is_open`	Return whether a Project Generation remains open. TYPE: `bool`
`is_started`	Return whether the current run is running or complete. TYPE: `bool`
`land_uses`	Return configured land uses in project order. TYPE: `ObjectCollection[LandUse]`
`lid_controls`	Return configured LID controls in project order. TYPE: `ObjectCollection[LidControl]`
`links`	Return configured links in project order. TYPE: `LinkCollection`
`nodes`	Return configured nodes in project order. TYPE: `NodeCollection`
`options`	Return a generation-bound typed simulation policy view. TYPE: `SimulationOptions`
`output_path`	Return the last retained output path, or `None` for scratch output. TYPE: `Path \| None`
`percent_complete`	Return elapsed model duration as a percentage of the configured run. TYPE: `float`
`pollutants`	Return configured pollutants in project order. TYPE: `ObjectCollection[Pollutant]`
`rain_gages`	Return configured rain gages in project order. TYPE: `ObjectCollection[RainGage]`
`rdii_assignments`	Return detached RTK RDII node assignments in node order. TYPE: `tuple[RdiiAssignment, ...]`
`report_path`	Return the absolute report destination from the last successful open. TYPE: `Path`
`report_period_count`	Return the number of saved binary report periods. TYPE: `int`
`report_start`	Timezone-naive report start. Setter lifecycle: `OPEN`, `ENDED`. TYPE: `datetime`
`shapes`	Return configured custom shapes in project order. TYPE: `ObjectCollection[CustomShape]`
`snowmelt_sets`	Return configured snowmelt parameter sets in project order. TYPE: `ObjectCollection[SnowmeltParameterSet]`
`start_time`	Timezone-naive start time. Setter lifecycle: `OPEN`, `ENDED`. TYPE: `datetime`
`state`	Return the authoritative typed owner lifecycle state. TYPE: `SimulationState`
`statistics`	Return one coherent immutable system statistics acquisition. TYPE: `SimulationStatistics`
`status`	Return an atomic lifecycle and progress snapshot. TYPE: `SimulationStatus`
`streets`	Return configured streets in project order. TYPE: `ObjectCollection[Street]`
`subcatchments`	Return configured subcatchments in project order. TYPE: `SubcatchmentCollection`
`time_patterns`	Return configured time patterns in project order. TYPE: `ObjectCollection[TimePattern]`
`time_series`	Return configured time series in project order. TYPE: `ObjectCollection[TimeSeries]`
`transects`	Return configured transects in project order. TYPE: `ObjectCollection[Transect]`
`unit_hydrographs`	Return configured unit hydrographs in project order. TYPE: `ObjectCollection[UnitHydrograph]`
`unit_system`	Return configured project unit system. TYPE: `UnitSystem`
`warning_count`	Return the accumulated solver warning count. TYPE: `int`

amm_assignments `property` `writable`

amm_assignments: tuple[AmmAssignment, ...]

Return detached AMM node assignments in configured order.

amm_models `property`

amm_models: ObjectCollection[AmmModel]

Return configured AMM models in project order.

aquifers `property`

aquifers: ObjectCollection[Aquifer]

Return configured aquifers in project order.

configuration_dirty `property`

configuration_dirty: bool

Return whether accepted configuration needs pre-start preparation.

controls `property`

controls: ObjectCollection[ControlRule]

Return configured control rules in project order.

current_time `property`

current_time: datetime

Return the current model wall-clock time.

curves `property`

curves: ObjectCollection[Curve]

Return configured curves in project order.

effective_threads `property`

effective_threads: int

Return the actual caller-inclusive solver team size.

elapsed_time `property`

elapsed_time: timedelta

Return elapsed model time from the configured start.

end_time `property` `writable`

end_time: datetime

Timezone-naive end time. Setter lifecycle: OPEN, ENDED.

flow_units `property`

flow_units: FlowUnits

Return configured project flow units.

inlet_designs `property`

inlet_designs: ObjectCollection[InletDesign]

Return configured inlet designs in project order.

input_path `property`

input_path: Path

Return the absolute input path from the last successful open.

is_open `property`

is_open: bool

Return whether a Project Generation remains open.

is_started `property`

is_started: bool

Return whether the current run is running or complete.

land_uses `property`

land_uses: ObjectCollection[LandUse]

Return configured land uses in project order.

lid_controls `property`

lid_controls: ObjectCollection[LidControl]

Return configured LID controls in project order.

links `property`

links: LinkCollection

Return configured links in project order.

nodes `property`

nodes: NodeCollection

Return configured nodes in project order.

options `property`

options: SimulationOptions

Return a generation-bound typed simulation policy view.

output_path `property`

output_path: Path | None

Return the last retained output path, or None for scratch output.

percent_complete `property`

percent_complete: float

Return elapsed model duration as a percentage of the configured run.

pollutants `property`

pollutants: ObjectCollection[Pollutant]

Return configured pollutants in project order.

rain_gages `property`

rain_gages: ObjectCollection[RainGage]

Return configured rain gages in project order.

rdii_assignments `property` `writable`

rdii_assignments: tuple[RdiiAssignment, ...]

Return detached RTK RDII node assignments in node order.

report_path `property`

report_path: Path

Return the absolute report destination from the last successful open.

report_period_count `property`

report_period_count: int

Return the number of saved binary report periods.

report_start `property` `writable`

report_start: datetime

Timezone-naive report start. Setter lifecycle: OPEN, ENDED.

shapes `property`

shapes: ObjectCollection[CustomShape]

Return configured custom shapes in project order.

snowmelt_sets `property`

snowmelt_sets: ObjectCollection[SnowmeltParameterSet]

Return configured snowmelt parameter sets in project order.

start_time `property` `writable`

start_time: datetime

Timezone-naive start time. Setter lifecycle: OPEN, ENDED.

state `property`

state: SimulationState

Return the authoritative typed owner lifecycle state.

statistics `property`

statistics: SimulationStatistics

Return one coherent immutable system statistics acquisition.

status `property`

status: SimulationStatus

Return an atomic lifecycle and progress snapshot.

streets `property`

streets: ObjectCollection[Street]

Return configured streets in project order.

subcatchments `property`

subcatchments: SubcatchmentCollection

Return configured subcatchments in project order.

time_patterns `property`

time_patterns: ObjectCollection[TimePattern]

Return configured time patterns in project order.

time_series `property`

time_series: ObjectCollection[TimeSeries]

Return configured time series in project order.

transects `property`

transects: ObjectCollection[Transect]

Return configured transects in project order.

unit_hydrographs `property`

unit_hydrographs: ObjectCollection[UnitHydrograph]

Return configured unit hydrographs in project order.

unit_system `property`

unit_system: UnitSystem

Return configured project unit system.

warning_count `property`

warning_count: int

Return the accumulated solver warning count.

copy

__copy__() -> Never

Reject copying Simulation Owner identity.

deepcopy

__deepcopy__(memo: object) -> Never

Reject deep-copying Simulation Owner identity.

del

__del__() -> None

Warn before the native owner performs best-effort destruction.

enter

__enter__() -> Self

Enter one cleanup scope without starting the open project.

exit

__exit__(exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: object) -> Literal[False]

Finalize a started run and close without replacing a body exception.

init

__init__(input_path: _PathInput, report_path: _PathInput | None = None, output_path: _PathInput | None = None) -> None

PARAMETER	DESCRIPTION
`input_path`	Path to the input file to open. TYPE: `str or PathLike[str]`
`report_path`	Text-report destination. TYPE: `str or PathLike[str]` DEFAULT: `None`
`output_path`	Binary-output destination. TYPE: `str or PathLike[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`SolverError`	If the native solver cannot open or validate the project.
`ValidationError`	If paths are invalid or collide.

iter

__iter__() -> Self

Return this simulation's single lifecycle iterator.

reduce

__reduce__() -> Never

Reject pickling Simulation Owner identity.

__reduce_ex__

__reduce_ex__(protocol: SupportsIndex) -> Never

Reject protocol-specific pickling of Simulation Owner identity.

close

close() -> None

Close the project and finalize owned artifacts.

Notes

Closing invalidates every collection and live view from the current Project Generation.

end

end() -> None

Finalize the current run while retaining its project generation.

RAISES	DESCRIPTION
`LifecycleError`	If the simulation has not been started.

execute

execute(*, save_results: bool = True) -> None

Run the complete non-interactive lifecycle and close the project.

PARAMETER	DESCRIPTION
`save_results`	Whether to save report-period results to the binary output. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`SolverError`	If the solver rejects any lifecycle stage.
`ValidationError`	If `save_results` is not a bool or deferred Configuration Preparation rejects the requested declarations. Batch cleanup closes the owner; use explicit `start()` for structured diagnostic repair/retry workflows.

fork

fork(report_path: _PathInput, output_path: _PathInput) -> Self

Create an independent child owner at the current lifecycle boundary.

The child receives fresh report/output destinations and a clone of the source's retained editable declarations.

load_checkpoint_state

load_checkpoint_state(checkpoint_path: _PathInput) -> None

Import checkpoint physical continuation state into this open owner.

The receiver retains its dates, inputs, declarations, statistics, accounting, iterator cadence, and output artifacts. Compatible physical state and persistent forcing are committed immediately and retained so the next start() can reapply them after processor initialization.

open

open(input_path: _PathInput, report_path: _PathInput | None = None, output_path: _PathInput | None = None) -> None

Open a fresh Project Generation on this closed facade.

PARAMETER	DESCRIPTION
`input_path`	Path to the input file to open. TYPE: `str or PathLike[str]`
`report_path`	Text-report destination. TYPE: `str or PathLike[str]` DEFAULT: `None`
`output_path`	Binary-output destination. TYPE: `str or PathLike[str]` DEFAULT: `None`

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not closed or is owned by a context manager.
`SolverError`	If the native solver rejects the new project.

replace_amm_assignments

replace_amm_assignments(assignments: Iterable[AmmAssignment]) -> None

Atomically replace all AMM node assignments in project units.

replace_rdii_assignments

replace_rdii_assignments(assignments: Iterable[RdiiAssignment]) -> None

Atomically replace all RTK RDII node assignments in project units.

report

report() -> None

Generate and flush the detailed report for an ended run.

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not ended.
`SolverError`	If SWMM cannot write the report.

reset_solver

reset_solver() -> None

Discard stale run state without reopening or validating the project.

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not open or ended, or iteration owns advancement.
`SolverError`	If stale output state cannot be released.

resume `classmethod`

resume(checkpoint_path: _PathInput, report_path: _PathInput, output_path: _PathInput) -> Self

Resume an independent owner from an immutable Simulation Checkpoint.

PARAMETER	DESCRIPTION
`checkpoint_path`	Existing checkpoint manifest. TYPE: `str or PathLike[str]`
`report_path`	Fresh report destination. TYPE: `str or PathLike[str]`
`output_path`	Fresh binary-output destination. TYPE: `str or PathLike[str]`

RETURNS	DESCRIPTION
`Simulation`	Independent owner restored at the saved lifecycle boundary.

Notes

Checkpoints restore prepared state, runtime continuation, and editable declarations, so the resumed owner can later be ended, edited, and rerun.

save_checkpoint

save_checkpoint(path: _PathInput) -> None

Save a deterministic Simulation Checkpoint at the current boundary.

PARAMETER	DESCRIPTION
`path`	Checkpoint manifest destination. Saving creates or atomically replaces the manifest; immutable sidecars are published beside it. TYPE: `str or PathLike[str]`

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not running or complete.
`ValidationError`	If `path` collides with a simulation-owned artifact.
`SolverError`	If checkpoint capture or atomic publication fails.

save_hotstart

save_hotstart(path: _PathInput) -> None

Write current state in EPA hotstart format and wait until it is usable.

PARAMETER	DESCRIPTION
`path`	Destination for the EPA hotstart file. TYPE: `str or PathLike[str]`

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not running or complete.
`ValidationError`	If `path` collides with a simulation-owned artifact.
`SolverError`	If SWMM cannot write the checkpoint.

sleep_workers

sleep_workers() -> None

Park Dynamic Wave workers until the next routing operation, including iterator advancement.

start

start(*, save_results: bool = True) -> None

Initialize an open or ended project and enter the running state.

PARAMETER	DESCRIPTION
`save_results`	Whether to save report-period results to the binary output. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`LifecycleError`	If the project is neither open nor ended, or iteration owns advancement.
`ValidationError`	If `save_results` is not a bool.
`ConfigurationError`	If deferred Configuration Preparation reports ordered relational diagnostics. Requested declarations remain available for repair.
`SolverError`	If SWMM cannot initialize the run.

step

step() -> datetime | None

Advance one routing step.

RETURNS	DESCRIPTION
`datetime or None`	The new model time, or `None` after the final step.

RAISES	DESCRIPTION
`LifecycleError`	If the simulation is not running.

step_advance

step_advance(duration: timedelta | float | None, *, strict: bool = True) -> None

Set or clear the cadence used by ordinary iteration.

PARAMETER	DESCRIPTION
`duration`	Positive whole-second cadence, or `None` to iterate at SWMM's normal routing step. TYPE: `timedelta or float or None`
`strict`	End exactly at each interval when true, potentially shortening the final routing step. When false, advance with ordinary routing steps until reaching or passing the target. Ignored when `duration` is `None`. TYPE: `bool` DEFAULT: `True`

RAISES	DESCRIPTION
`LifecycleError`	If the project is closed.
`ValidationError`	If `duration` is invalid or `strict` is not a bool.

stride

stride(duration: timedelta | float, *, strict: bool = True) -> datetime | None

Advance toward a positive whole-second interval.

PARAMETER	DESCRIPTION
`duration`	Target advance in seconds. TYPE: `timedelta or float`
`strict`	End exactly at the requested interval when true. When false, advance with ordinary routing steps until reaching or passing the target. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`datetime or None`	The new model time, or `None` after the final step.

RAISES	DESCRIPTION
`ValidationError`	If `duration` is not a positive whole-second duration or `strict` is not a bool.

terminate

terminate() -> None

Request orderly termination at the next iterator checkpoint.

update_schedule

update_schedule(**changes: object) -> None

Atomically update coupled start, report-start, and end dates.

use_hotstart

use_hotstart(path: _PathInput | None) -> None

Set or clear persistent hotstart input for this Project Generation.

PARAMETER	DESCRIPTION
`path`	EPA hotstart file to load before the next `start()`, or `None` to clear the configured hotstart input. TYPE: `str or PathLike[str] or None`

RAISES	DESCRIPTION
`LifecycleError`	If called outside the open or ended state.
`ValidationError`	If `path` collides with a simulation-owned artifact.

SimulationStatus


              flowchart TD
              swmmrs.SimulationStatus[SimulationStatus]

              

              click swmmrs.SimulationStatus href "" "swmmrs.SimulationStatus"

Immutable lifecycle and progress values from one owner acquisition.

Simulation

Simulation

input_path

report_path

output_path

amm_assignments property writable

amm_models property

aquifers property

configuration_dirty property

controls property

current_time property

curves property

effective_threads property

elapsed_time property

end_time property writable

flow_units property

inlet_designs property

input_path property

is_open property

is_started property

land_uses property

lid_controls property

links property

nodes property

options property

output_path property

percent_complete property

pollutants property

rain_gages property

rdii_assignments property writable

report_path property

report_period_count property

report_start property writable

shapes property

snowmelt_sets property

start_time property writable

state property

statistics property

status property

streets property

subcatchments property

time_patterns property

time_series property

transects property

unit_hydrographs property

unit_system property

warning_count property

__copy__

__deepcopy__

__del__

__enter__

__exit__

__init__

input_path

report_path

output_path

__iter__

__next__

__reduce__

__reduce_ex__

close

end

execute

save_results

fork

load_checkpoint_state

open

input_path

report_path

output_path

replace_amm_assignments

replace_rdii_assignments

report

reset_solver

resume classmethod

checkpoint_path

report_path

output_path

save_checkpoint

path

`input_path`

`report_path`

`output_path`

amm_assignments `property` `writable`

amm_models `property`

aquifers `property`

configuration_dirty `property`

controls `property`

current_time `property`

curves `property`

effective_threads `property`

elapsed_time `property`

end_time `property` `writable`

flow_units `property`

inlet_designs `property`

input_path `property`

is_open `property`

is_started `property`

land_uses `property`

lid_controls `property`

links `property`

nodes `property`

options `property`

output_path `property`

percent_complete `property`

pollutants `property`

rain_gages `property`

rdii_assignments `property` `writable`

report_path `property`

report_period_count `property`

report_start `property` `writable`

shapes `property`

snowmelt_sets `property`

start_time `property` `writable`

state `property`

statistics `property`

status `property`

streets `property`

subcatchments `property`

time_patterns `property`

time_series `property`

transects `property`

unit_hydrographs `property`

unit_system `property`

warning_count `property`

copy

deepcopy

del

enter

exit

init

`input_path`

`report_path`

`output_path`

iter

next

reduce

`save_results`

`input_path`

`report_path`

`output_path`

resume `classmethod`

`checkpoint_path`

`report_path`

`output_path`

`path`

`path`

`save_results`

`duration`

`strict`

`duration`

`strict`

`path`