openswmm::transport::ReactionIntegrator Class Reference

#include <ReactionIntegrator.hpp>

Collaboration diagram for openswmm::transport::ReactionIntegrator:

Static Public Member Functions
static RxStepReport	step (const ReactionData &rx, const std::vector< ReactionExprForm > &forms, const std::vector< RxExprSpan > &expressions, double dt, double *species, double *hydvar, RxWorkspace &ws, const double *pollutants=nullptr, const double *kinetic_scale=nullptr, const double *coefficients=nullptr, std::span< const RxRateContext > contexts={})
	Integrate one explicit reactor law set over a local species block.
static RxStepReport	stepSubcycled (const ReactionData &rx, const std::vector< ReactionExprForm > &forms, const std::vector< RxExprSpan > &expressions, double dt, double *species, double *hydvar, RxWorkspace &ws, const double *pollutants=nullptr, const double *kinetic_scale=nullptr, const double *coefficients=nullptr, std::span< const RxRateContext > contexts={})
	Retry an owned reaction interval by bounded bisection while restoring species on returned failure.
static RxStepReport	step (const ReactionData &rx, bool tank, double dt, double *species, double *hydvar, RxWorkspace &ws, const double *pollutants=nullptr, const double *coefficients=nullptr)
	Select tank or pipe law arrays then integrate one local species block.

Member Function Documentation

step() [1/2]

RxStepReport openswmm::transport::ReactionIntegrator::step ( const ReactionData & rx, bool tank, double dt, double * species, double * hydvar, RxWorkspace & ws, const double * pollutants = nullptr, const double * coefficients = nullptr )

static

Select tank or pipe law arrays then integrate one local species block.

Parameters

[in]	rx	Stable compiled reaction system, token/spans/dependencies/tolerances already validated.
[in]	dt	Positive finite reaction duration s; ordinary step returns successful no-op for uncompiled/zero-species/nonpositive dt, but does not explicitly reject NaN.
[in,out]	species	Writable rx.n_species() local values in declared species concentration/area units; full readable state required for referenced expressions. No automatic positivity clamp.
[in,out]	hydvar	Writable RxHydVar::COUNT_ tuple, required; DT overwritten with dt for active solve. Other entries held by caller (HRT seconds, TEMP degC, AV declared area/L and groundwater SI fields).
[in,out]	ws	Workspace initialized for exact species/term dimensions, exclusive to this solve; scratch/caches overwritten. Distinct concurrent reactors need separate workspaces.
[in]	pollutants	Optional stable pollutant concentration tuple, required for referenced tokens.
[in]	coefficients	Optional rx.coef_value-sized coefficient override; null uses rx.coef_value. All borrowed inputs remain valid through synchronous call and do not alias species/workspace updates.
[in]	tank	True uses tank forms/spans, false pipe; no groundwater or other scoped fallback.

Returns

Status with accepted RATE substep and Newton counts, interval_limit for work/floor exhaustion and error text for refusal. No independent concentration/nonnegativity/physical mass qualification beyond solver's finite final-state checks; caller handles acceptance/ledger policy.

Note

RATE integrates first (FULL joint, NONE freezes other RATE rows at entry), then joint EQUIL Newton using absolute global atol, then FORMULA in declaration order. Reachable terms recompute forward for each evaluation. No hydraulic/global ledger/engine clock advance. Shape/profile errors return before solve; ordinary numerical failure can leave trial/accepted species and DT changed. No rollback or warning emission. Pre-sized numerical path avoids allocation, but report strings or unexpected dependency failures can throw; caller must isolate state for transactional acceptance.

Here is the call graph for this function:

step() [2/2]

RxStepReport openswmm::transport::ReactionIntegrator::step ( const ReactionData & rx, const std::vector< ReactionExprForm > & forms, const std::vector< RxExprSpan > & expressions, double dt, double * species, double * hydvar, RxWorkspace & ws, const double * pollutants = nullptr, const double * kinetic_scale = nullptr, const double * coefficients = nullptr, std::span< const RxRateContext > contexts = {} )

static

Integrate one explicit reactor law set over a local species block.

Parameters

[in]	rx	Stable compiled reaction system, token/spans/dependencies/tolerances already validated.
[in]	dt	Positive finite reaction duration s; ordinary step returns successful no-op for uncompiled/zero-species/nonpositive dt, but does not explicitly reject NaN.
[in,out]	species	Writable rx.n_species() local values in declared species concentration/area units; full readable state required for referenced expressions. No automatic positivity clamp.
[in,out]	hydvar	Writable RxHydVar::COUNT_ tuple, required; DT overwritten with dt for active solve. Other entries held by caller (HRT seconds, TEMP degC, AV declared area/L and groundwater SI fields).
[in,out]	ws	Workspace initialized for exact species/term dimensions, exclusive to this solve; scratch/caches overwritten. Distinct concurrent reactors need separate workspaces.
[in]	pollutants	Optional stable pollutant concentration tuple, required for referenced tokens.
[in]	coefficients	Optional rx.coef_value-sized coefficient override; null uses rx.coef_value. All borrowed inputs remain valid through synchronous call and do not alias species/workspace updates.
[in]	forms	Exactly n_species NONE/RATE/EQUIL/FORMULA selectors for this reactor.
[in]	expressions	Exactly n_species compiled spans into rx.token_pool, selected with forms.
[in]	kinetic_scale	Optional n_species multiplicative RATE weights; single-context values are not generically finite/range checked here. Null means1; must be null for shared contexts.
[in]	contexts	Optional synchronous shared RATE contexts. Each has n_species forms/spans, nonnull hydvar and nonnegative finite n_species scales, optional pollutants. Only NONE/RATE forms allowed, context RATE rows must appear in primary RATE mask. Contributions sum on same species state.

Returns

Status with accepted RATE substep and Newton counts, interval_limit for work/floor exhaustion and error text for refusal. No independent concentration/nonnegativity/physical mass qualification beyond solver's finite final-state checks; caller handles acceptance/ledger policy.

Note

RATE integrates first (FULL joint, NONE freezes other RATE rows at entry), then joint EQUIL Newton using absolute global atol, then FORMULA in declaration order. Reachable terms recompute forward for each evaluation. No hydraulic/global ledger/engine clock advance. Shape/profile errors return before solve; ordinary numerical failure can leave trial/accepted species and DT changed. No rollback or warning emission. Pre-sized numerical path avoids allocation, but report strings or unexpected dependency failures can throw; caller must isolate state for transactional acceptance.

< last ACCEPTED step (BDF2 history)

Here is the call graph for this function:

Here is the caller graph for this function:

stepSubcycled()

RxStepReport openswmm::transport::ReactionIntegrator::stepSubcycled ( const ReactionData & rx, const std::vector< ReactionExprForm > & forms, const std::vector< RxExprSpan > & expressions, double dt, double * species, double * hydvar, RxWorkspace & ws, const double * pollutants = nullptr, const double * kinetic_scale = nullptr, const double * coefficients = nullptr, std::span< const RxRateContext > contexts = {} )

static

Retry an owned reaction interval by bounded bisection while restoring species on returned failure.

Parameters

[in]	rx	Stable compiled reaction system, token/spans/dependencies/tolerances already validated.
[in]	dt	Positive finite reaction duration s; ordinary step returns successful no-op for uncompiled/zero-species/nonpositive dt, but does not explicitly reject NaN.
[in,out]	species	Writable rx.n_species() local values in declared species concentration/area units; full readable state required for referenced expressions. No automatic positivity clamp.
[in,out]	hydvar	Writable RxHydVar::COUNT_ tuple, required; DT overwritten with dt for active solve. Other entries held by caller (HRT seconds, TEMP degC, AV declared area/L and groundwater SI fields).
[in,out]	ws	Workspace initialized for exact species/term dimensions, exclusive to this solve; scratch/caches overwritten. Distinct concurrent reactors need separate workspaces.
[in]	pollutants	Optional stable pollutant concentration tuple, required for referenced tokens.
[in]	coefficients	Optional rx.coef_value-sized coefficient override; null uses rx.coef_value. All borrowed inputs remain valid through synchronous call and do not alias species/workspace updates.
[in]	forms	Exactly n_species NONE/RATE/EQUIL/FORMULA selectors for this reactor.
[in]	expressions	Exactly n_species compiled spans into rx.token_pool, selected with forms.
[in]	kinetic_scale	Optional n_species multiplicative RATE weights; single-context values are not generically finite/range checked here. Null means1; must be null for shared contexts.
[in]	contexts	Optional synchronous shared RATE contexts. Each has n_species forms/spans, nonnull hydvar and nonnegative finite n_species scales, optional pollutants. Only NONE/RATE forms allowed, context RATE rows must appear in primary RATE mask. Contributions sum on same species state.

Returns

Report from accepted interval(s), aggregating successful/rejected attempt counters. Only interval_limit permits up to8 nested halvings; shape/law/Newton/finite failures retain their error.

Note

Saves species at every recursion, restores all n_species values on returned failure and before retry. Does not restore workspace/caches or other caller state; resets primary/context DT to original dt after normal return. Unlike ordinary step, species/hydvar pointers must be valid even for inactive or zero-duration work because snapshots/DT reset still occur. Allocations and exceptions are not caught and can bypass restoration. Tolerances unchanged; no hydraulic/global-ledger/clock update.

Here is the call graph for this function:

---

The documentation for this class was generated from the following files:

• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/transport/components/ReactionModule/ReactionIntegrator.hpp
• /home/runner/work/openswmm.engine/openswmm.engine/src/engine/transport/components/ReactionModule/ReactionIntegrator.cpp