Editing, forcing and live output#

Saved results and C API parity (2026-10-21)#

Results now provides named 1D fields and saved 2D HDF5 output through a consistent interface. Output2DReader wraps the public openswmm_output2d.h API and remains importable without optional features; available() reports whether the linked engine has its backend. See Working with results for the full interface, selection rules, units and lifecycle.

OutputReader.pollutant_units exposes stored concentration codes as labels and interprets reserved water-age/temperature columns correctly. solver.open_results() opens configured output after end(). A retained 1D timestamp cache no longer bypasses the reader’s closed-handle check.

The current binding audit covers public engine functions, Python enum selectors, Cython declarations/call sites, type stubs and package exports. Existing runtime APIs include groundwater and layered transport, surface quality, snow/heat, checkpoints, staged authoring, runtime coupling, and solver diagnostics. The source audit found no missing function declarations or enum types before this change; the additions extend output reading.

Run the maintained checks from the repository root:

python python/scripts/api_drift_audit.py --strict
python python/scripts/api_drift_audit.py --json --coverage
python python/scripts/python_surface.py --check
python -m pytest python/tests/test_api_coverage.py python/tests/test_enum_drift.py python/tests/test_solver_pxd_attrs.py

--json --coverage includes per-header totals and each public C function’s Python member mapping. Three C convenience functions intentionally use Python-native equivalents: swmm_get_current_time, swmm_coupling_set_source and swmm_coupling_advance_to. These exclusions remain checked against drift. The machine-readable engine catalog also includes the standalone surface_output reader root. Macro selector checks normalize C line continuations so formatting a header cannot hide selectors from the parity audit.

Batch editing#

ModelEditor retains its engine owner and checks it before every operation. delete_nodes, delete_links, delete_subcatchments and delete_gages accept iterables of names or zero-based indices. All refer to the model before the batch. Duplicates are ignored and invalid indices fail before any deletion. A successful nonempty batch invalidates element views and returns the aggregate cascade report. Reacquire views after an edit; the editor itself remains usable.

Live output#

OutputReader(path, live=True) opens an output whose header is complete, even before the writer finishes. refresh() returns the number of complete periods and clears cached timestamps. Partial trailing records are excluded. is_live becomes false when closing records arrive. This supports monitoring runs and recovering completed records from interrupted runs; it never modifies the file. Concurrent access to a reader during a native series read raises LifecycleError; independent readers can operate concurrently. Close the reader or use its context manager. Reads after close raise BadHandleError.

from openswmm.engine import OutputReader, OutNodeVar

with OutputReader('run.out', live=True) as output:
    count = output.refresh()
    if count:
        depths = output.node_result(count - 1, OutNodeVar.DEPTH)

Staged serialization#

solver.write_staged(final_path, mapper) routes each physical file through mapper(final_path, kind). Kind 0 identifies the INP file, 1 the mesh and 2 a component configuration. Return a distinct staging path, or None to refuse. References inside files are computed from final paths. Success confirms only serialization; the caller owns validation, cleanup and publication of every output. Plugin writers are excluded. Engine access inside the mapper raises LifecycleError. Python callback exceptions are re-raised after the native writer returns safely.

Additional forcing and diagnostics#

forcing.node_temperature uses degrees C for REPLACE, and degrees C times ft³/s for ADD. forcing.node_age uses hours for REPLACE and hours times ft³/s for ADD. Enable heat or water-age transport before initialization respectively. forcing.link_seepage uses ft³/s even for SI projects, positive out of the conduit. Negative values supply water from groundwater. If the built-in aquifer is coupled, the forced exchange also updates that aquifer; disable the internal reach exchange when an external groundwater model supplies the water.

forcing.element_climate takes HeatElemKind, a node/link name or index, and an ELEM_* ForcingType. Air temperature and wind use project units; humidity uses percent and shortwave uses W/m². element_climate_get returns (value, mode), with None for mode when no forcing is present. Setters accept REPLACE or ADD, with the existing one-shot/persistent policy.

surface2d.get_rainfall_bulk() returns m/s. get_rain_volume_bulk() and get_coupling_volume_bulk() return cumulative m³, with positive coupling from 1D to 2D. Arrays are independent snapshots covering triangles and quads. rainfall_weights(cell) returns method, gage indices and weights. Method -1 means not applicable, 0 natural neighbour, 1 inverse distance, and 2 nearest.

Surface2D.output_variables() discovers available output names. output_variable_mask(text) accepts DEFAULT, MINIMAL, ALL or a variable list; invalid selections raise ValueError. output_variable_text(mask) returns the canonical text for storing the selection.

Richards LIDs and surface ownership#

solver.subcatchments[name].snowpack reads the assigned snow-pack name (empty when unassigned). Assign a name before initialization, or assign None to clear it. An unknown name leaves the previous assignment intact.

solver.infrastructure.lids.get_flow_options(control) reports the flow model (0 for the existing formulation or 1 for Richards), numerical cells per porous layer, absolute/relative tolerances and maximum step in seconds. get_materials(control) returns retention mappings in authored layer order; alpha and specific storage use inverse metres in both unit systems. set_layers(control, layers, flow=options, materials=materials) changes the stack and flow model atomically. Supply one material mapping per layer; SURFACE/BOTTOM entries are ignored. Omitted treatments retain their current values; pass an empty list to remove them. Invalid input leaves the model unchanged. richards_profile(node) reports live cell pressure/head in project length units and complete water in project volume units. richards_statistics(node) reports the last interval’s solver counters, minimum step in seconds and water-balance residual in cubic metres.

solver.surface2d.infiltration.authored_rows() returns ordered raw records with cell, tag, row and dest_explicit fields. replace_authored_rows(records) restores a complete set before initialization, including duplicate/order information and obsolete destinations needed for undo. Acceptance for authoring does not enable an obsolete runtime destination. ownership(cell) and ownership_bulk() expose resolved owner, aquifer row and conflict codes without modifying these records.

solver.surface2d.groundwater.options.set_process_options(et=..., link=..., wilting=..., authored=...) atomically changes groundwater ET, conduit exchange and wilting suction. Custom suction is in project length units; authored restores section provenance for undo.

solver.surface2d.get_report_rainfall_bulk(report_date) reads report-instant rainfall in metres per second. The date is an absolute SWMM DateTime in decimal days; routing-window rainfall remains available through get_rainfall_bulk().

Surface ownership is currently an authoring/review facility. While editing, get_surface_owners() reads zero-based subcatchment indices and preview_surface_owners(rows) reviews a proposed complete set. Passing None reviews the stored set. The result contains source objects, cell shares and remaining mesh weather areas in square metres, blocking diagnostics, valid and a revision token. Use that token with replace_surface_owners(rows, token); a stale token or invalid proposal leaves the model unchanged. An empty list clears the records. Initialization currently rejects stored ownership records until the completed-interval runtime adapter is qualified; geometric acceptance alone does not activate recharge or suppress existing weather sources.

Passive exchange and material peers#

solver.passive_exchange exposes the experimental integrated native passive profile. After initialize() and start(False), call enable(capacity=64) before the first step. enable_checkpoint() attaches numerical checkpoints at that initial boundary; use solver.checkpoints to save or restore them. Native eligibility restrictions apply, including a single passive pollutant, isolated wet storage and a serial CPU surface.

status(), pool(node), receipt(index), row(receipt, row, remaining=0), leg(index) and attempt() return frozen V1 snapshots. PassiveAmount.components retains every original ordered expansion component; the exact sum is authoritative. Water and material keep the native units of the C records (ft³ and declared concentration times ft³ for native amounts; m³ and declared concentration times m³ for surface legs). These copies do not carry transfer authority. Inspection during callbacks raises LifecycleError.

solver.material_split exposes the separate experimental in-process material adapter. Both peers must open the same input path. Configure NETWORK and SURFACE roles while OPENED, exchange initialized geometry through encode/decode, apply it on the network, then register a phase callback with set_callback. Start both peers, register set_transport(callback) on the network and call bind(surface, capacity). The phase callback uses owned SplitFrame replies, including SplitPhase.MATERIAL_REPORT. The material callback receives (stage, text) and returns response JSON text; stages are OFFER=1, PROOF=2 and ACK=3. copy_packet(text) validates/canonicalizes schema-10 boundary, offer, proof and acknowledgement values. Copies alone grant no spending authority.

Python retains callback text until native parsing finishes and retains both bound owners. Access is serialized across the pair; callback exceptions stop exchange and are re-raised after the native call. Reentrant stepping or teardown is refused. Explicitly close/destroy both solvers when finished. This interface requires the native 2D and material-component features; omitted-feature builds keep the Python API importable and return PluginError. The integrated passive facade and paired material adapter are separate enrollment alternatives.