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.paramsreads or atomically replaces the complete divider record. Flow and length fields use the project’s display units.solver.surface2d.validate_node_couplingandreplace_node_couplingaccept a complete parameter mapping and its authored-row flag.solver.infrastructure.inlet_usages.validatepreflights a usage mapping.solver.infrastructure.lids.usage_recordcopies every placement field, including both report-path strings and the drain target.validate_usagechecks a record, andreplace_usagesatomically replaces one subcatchment’s ordered records while preserving other owners.lids.node_snapshot,prepare_node,validate_nodeandreplace_nodeexpose a complete storage-LID assignment and its keyed anchors. Snapshot fields ending in_ftdeliberately 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.