Process components ([PROCESS_COMPONENTS])#
Note
Engine: OpenSWMM 6 — refactored.
solver.process_components enumerates and edits the
[PROCESS_COMPONENTS] registrations — the file-binding surface that
tells the engine which optional process components (heat, water age,
reactions, …) are active and where each one’s config file lives.
Reference: openswmm_process_components.h.
Extra arguments and foreign instances#
arguments(key) returns ordered (name, value) pairs without loading a
component. set_argument(key, name, value) sets or replaces a row argument;
None removes it. These edits require BUILDING/OPENED and are consumed at the
next model open. config remains the registration’s separate configuration
path; it cannot be set as an extra argument.
components = solver.process_components
components.register("receiving", "receiving.json")
components.set_argument("receiving", "library", "components/receiver.so")
components.set_argument("receiving", "component", "example.receiving")
print(components.arguments("receiving"))
Foreign runtime hosting requires the optional HydroCouple build feature and an
openswmm.hosted-component/1 configuration. The qualified export profile uses
native external-outfall water, pollutant mass and heat receipts with explicit
one-to-one item connections. Metadata inspection does not create or advance the
foreign instance. Configuration inspection and authoring remain separate from
runtime compatibility qualification. See docs/HYDROCOUPLE_HOSTING.md in the
engine repository for ownership, units, cancellation and acceptance semantics.
Quickstart#
from openswmm.engine import Solver
with Solver("model.inp") as s:
for c in s.process_components:
print(c.component_index, c.id, c.config, c.resolved)
"heat" in s.process_components # membership by id
s.process_components["heat"].config # config="…" as written
# Register first, then write the file it points at.
s.process_components.register("waterage", "model.age")
open("model.age", "w").write("[WATER_AGE_SOURCES]\n")
s.process_components.remove("waterage")
Warning
register and remove are BUILDING/OPENED only.
The registration record#
Each entry is a ProcessComponent named tuple.
Field |
Meaning |
|---|---|
|
Position in the section, |
|
Component id, e.g. |
|
The |
|
The effective path the config was actually read from at the last open. |
Important
resolved is "" until the last open resolved it. An empty
resolved therefore means “not resolved yet”, not “no file” — check
config to tell the two apart. On a model built programmatically
and never opened, every resolved is empty.
Enumerating and finding#
Operation |
Behaviour |
|---|---|
|
Number of registrations. |
|
One |
|
Iterate in section order. |
|
Membership test on the component id. |
|
Registration index for an id. |
|
Add a registration; returns the new
|
|
Delete by index or id. |
Registering before the file exists#
The “create a component and its config file” flow registers first,
then writes the file. A config_path that does not exist yet is
legal: the path is stored as written, and resolution happens at the next
open.
c = s.process_components.register("reactions", "chlorine.rxn")
assert c.resolved == "" # nothing resolved it yet
s.reactions.save("chlorine.rxn") # now the file exists
Warning
A duplicate id is refused. Check with
inorProcessComponents.get_index()before registering, rather than relying on a retry.ProcessComponents.remove()shifts the indices of every later registration. Cachedcomponent_indexvalues go stale — re-enumerate, or address components by id.
See also#
Heat transport (fluxes, solar, cloud, source temperature) — the
model.heatcomponent.Water age ([WATER_AGE_SOURCES]) — the
model.agecomponent, andWaterAge.save().Reactions (multi-species: species, coefficients, terms) — the
.rxncomponent, andReactions.save().Programmatic model construction — building a model that registers components from scratch.
Error handling, edge cases & debugging — what a duplicate id or a bad index raises.
Built-in registry#
solver.process_components.known() returns immutable registry entries with
id, description and implemented fields. The registry describes the
build’s vocabulary; it differs from the components configured on a model.
Entries with implemented=False are placeholders and cannot supply a process
implementation merely by being registered in the model.