openswmm_gymnasium._engine#

openswmm_gymnasium._engine#

Thin adapter over openswmm.engine.Solver (the handle-based, thread-safe v6 engine). This is the B{only} place in the package that touches the engine — every other module imports from here, never directly from openswmm.engine. Plan §2 / §2.3.

author:

Caleb Buahin

copyright:

Copyright (c) 2026 Caleb Buahin

license:

MIT

exception openswmm_gymnasium._engine.LegacySolverRejectedError[source]#

Bases: TypeError

Raised when a legacy v5 singleton solver is passed where the v6 handle-based solver is required. Plan §0 #7.

class openswmm_gymnasium._engine.SolverAdapter(inp, rpt=None, out=None, *, solver=None)[source]#

Bases: object

Thin lifecycle wrapper around openswmm.engine.Solver.

Construction does B{not} open the engine. Call open (or use with adapter: ...) to allocate the underlying SWMM_Engine handle.

Each SolverAdapter owns a distinct SWMM_Engine handle, so two adapters on different threads do not share C-side state. Plan §2.3 (Threading & vectorized rollout).

@ivar _inp: Resolved absolute path to the inp file. :type _inp: str @ivar _rpt: Resolved rpt path, or empty string if reporting

is disabled.

Parameters:

  • inp (PathLike)

  • rpt (PathLike | None)

  • out (PathLike | None)

  • solver (Solver | None)

@ivar _out: Resolved out path, or empty string if binary

output is disabled.

Parameters:

  • inp (PathLike)

  • rpt (PathLike | None)

  • out (PathLike | None)

  • solver (Solver | None)

@ivar _solver: The wrapped openswmm.engine.Solver instance. :type _solver: openswmm.engine.Solver @ivar _owned: True if this adapter is responsible for closing

the solver; False if the solver was injected by the caller.

Parameters:

  • inp (PathLike)

  • rpt (PathLike | None)

  • out (PathLike | None)

  • solver (Solver | None)

close()[source]#

Close the engine handle. Idempotent.

Note:

Safe to call multiple times. Closes only when this adapter owns the solver (i.e. constructed it internally).

Return type:

None

property controls: openswmm.engine.Controls#

Lazily-constructed, cached openswmm.engine.Controls accessor.

Return type:

openswmm.engine.Controls

property current_time: float#

Current simulation time as an OADate (decimal days).

Return type:

float

property elapsed: float#

Elapsed simulation time in days.

Return type:

float

end()[source]#

End the simulation (transitions to ENDED).

Return type:

None

property end_time: float#

Simulation end time as an OADate (decimal days).

Return type:

float

property gages: openswmm.engine.Gages#

Lazily-constructed, cached openswmm.engine.Gages accessor.

Return type:

openswmm.engine.Gages

initialize()[source]#

Initialize the simulation (transitions OPENED -> RUNNING).

Raises:

RuntimeError – If the underlying C API returns a non-zero code.

Return type:

None

property is_running: bool#

Whether the simulation is still advancing.

Return type:

bool

Lazily-constructed, cached openswmm.engine.Links accessor.

Return type:

openswmm.engine.Links

property nodes: openswmm.engine.Nodes#

Lazily-constructed, cached openswmm.engine.Nodes accessor.

Return type:

openswmm.engine.Nodes

open(plugin_lib=None)[source]#

Open the input file and allocate the engine handle.

Parameters:

plugin_lib (str, os.PathLike, or None) – Optional path to a plugin shared library.

Raises:

RuntimeError – If the underlying C API returns a non-zero code.

Return type:

None

report()[source]#

Write the report file.

Return type:

None

property solver: openswmm.engine.Solver#

Underlying real openswmm.engine.Solver. Use sparingly.

Return type:

openswmm.engine.Solver

property start_time: float#

Simulation start time as an OADate (decimal days).

Return type:

float

property state: openswmm.engine.EngineState#

Current engine state.

Return type:

openswmm.engine.EngineState

step()[source]#

Advance one routing timestep.

Returns:

Engine return code (0 on success).

Return type:

int

stride(n_steps)[source]#

Advance n_steps routing timesteps in one call.

Parameters:

n_steps (int) – Number of timesteps to advance.

Returns:

Engine return code (0 on success).

Return type:

int

property subcatchments: openswmm.engine.Subcatchments#

Lazily-constructed, cached openswmm.engine.Subcatchments accessor.

Return type:

openswmm.engine.Subcatchments