Native water peers and atomic editor records#

Native water peers#

solver.split exposes the experimental native water-only peer profile. It retains the native eligibility checks and lifecycle: configure the two OPENED engines before initialization, export the initialized surface geometry, import it into the initialized network, register the network’s callback, then start both peers. Both peers must use the same authored input file. The surface peer must omit the 1D binary output path.

from openswmm.engine import SplitRole

network.split.validate_input()
network.split.configure(SplitRole.NETWORK)
surface.split.configure(SplitRole.SURFACE)
surface.initialize()
with surface.split.geometry() as geometry:
    network.initialize()
    network.split.apply_geometry(geometry)

def exchange(phase, request):
    return surface.split.evaluate(phase, request)

network.split.set_callback(exchange)
surface.start(save_results=False)
network.start(save_results=True)
for elapsed in network.steps():
    pass
network.end()

A callback request is borrowed, restricted to its callback thread, and expires when the callback returns. The callback must return a newly owned frame from evaluate; returning the borrowed request is an error. The native host consumes the returned reply, so its Python wrapper becomes invalid immediately. Owned geometry and decoded frames support close and the context manager. Keep the receiving engine alive through the callback. Python exceptions are captured at the C boundary and re-raised after the native operation; completed physics is not rolled back. Callback registration and removal require the INITIALIZED network state, before start.

SplitFrame.node returns SI values. source and outfall_return expose the documented native ft³/s and ft³ receipts only when the native reviewed-source profile supplies them. encode and decode copy versioned UTF-8 JSON and never advance either engine. They require the optional native packet codec; otherwise they raise PluginError. Decoded packets expose only the quantities published for their phase, rather than a complete native node snapshot.

solver.set_phase_callback(observer) registers a read-only diagnostic observer receiving (phase, start_seconds, end_seconds). It may read public state but must not mutate or advance an engine. Pass None between steps to unregister it. Observer exceptions are re-raised after the current native step.

Atomic editor records#

The following operations are available before initialization. Native validation failures preserve the authored state, including a failure in the last member.

  • node.divider.params reads or atomically replaces the complete divider record. Flow and length fields use the project’s display units.

  • solver.surface2d.validate_node_coupling and replace_node_coupling accept a complete parameter mapping and its authored-row flag.

  • solver.infrastructure.inlet_usages.validate preflights a usage mapping.

  • solver.infrastructure.lids.usage_record copies every placement field, including both report-path strings and the drain target. validate_usage checks a record, and replace_usages atomically replaces one subcatchment’s ordered records while preserving other owners.

  • lids.node_snapshot, prepare_node, validate_node and replace_node expose a complete storage-LID assignment and its keyed anchors. Snapshot fields ending in _ft deliberately retain exact internal feet in both unit systems for lossless replay. They are not ordinary project-unit editor inputs.

Inlet designs can be checked without modifying the model with solver.infrastructure.inlets.validate_design(record). The returned record contains the normalized active fields and the resolved custom curve kind; it can be passed directly to set_design after review.

Complete table and control edits are also atomic. table.validate_points(rows) checks raw numeric pairs without mutation; replace_points publishes the rows and relative-prefix metadata together. Time-series X and anchor values are native OADate days. file_token=None preserves a FILE binding; an empty token detaches it. solver.controls.replace_program(blocks, publish=False) validates the whole ordered program, including declarations shared by later rules; the default publishes it atomically. Diagnostics use a growing buffer.

lids.validate_type and validate_layers preflight type and complete NODE profile changes. The latter accepts the same layers, treatment and material records as set_layers, with explicit flow options. get_extra/set_extra use LidExtraField for stored scalar members; get_drain_curve returns a copied curve token. These operations retain the native lifecycle and input-unit rules.