Mutable compiled control rules and per-action PID history. Use one owning simulation thread. Rule/context edits, parsing and evaluation must be serialized. No method catches allocation failures or rolls back all preceding mutations on exception. Hydraulic quantities use project display units; serial dates/time comparisons use SWMM days unless stated otherwise. More...

#include <Controls.hpp>

Collaboration diagram for openswmm::controls::ControlEngine:

Classes
struct	PremiseSoA
	Pre-sorted premise index for batch evaluation. More...

Public Member Functions
void	init (const std::vector< Rule > &rules)
	Copy compiled rules, reindex actions and rebuild premise caches.

int	evaluate (SimulationContext &ctx, double current_date, double dt, bool rule_time_reached=true)
	Evaluate premises, arbitrate actions and update link target settings.

int	parseRuleText (const std::string &text, SimulationContext &ctx)
	Append rules, named variables and expressions from control-section text.

const ParseError &	lastParseError () const noexcept
	Borrow the most recent parser diagnostic without clearing it.

void	clearRules ()
	Discard rules, PID/named-expression state, caches and parser diagnostic. Use before recompiling a complete rule-text store because parseRuleText appends. Does not reset lastActionCount(), evaluation clocks, tracked modulation values or context target settings/logs. Existing borrowed rule elements are invalidated.

void	addNamedVariable (const std::string &name, ConditionVar var, int idx, int param=0)
	Append a named binding without resolving or validating its object.

int	addExpression (const std::string &name, const std::string &formula)
	Parse and register a named arithmetic expression.

std::vector< Rule > &	rules ()
	Borrow the mutable compiled rule sequence.

int	lastActionCount () const
	Read the target-change count of the last returned evaluate() call.

void	buildPremiseSoA ()
	Rebuild flattened premise offsets, variable-type groups and work buffers. Call after any premise/rule structural change, with all counts and cumulative offsets representable as int. Expression LHS values are evaluated separately; variable RHS entries retain placeholder slots for the scalar pass. Group order is unspecified. Does not reset PID history, pending actions or diagnostics.

void	batchEvaluateGroup (PremiseSoA &group, const SimulationContext &ctx, double current_time, double half_step)
	Gather and compare one homogeneous ordinary-variable premise group.

Friends
class	openswmm::SWMMEngine

Detailed Description

Mutable compiled control rules and per-action PID history. Use one owning simulation thread. Rule/context edits, parsing and evaluation must be serialized. No method catches allocation failures or rolls back all preceding mutations on exception. Hydraulic quantities use project display units; serial dates/time comparisons use SWMM days unless stated otherwise.

Member Function Documentation

◆ addExpression()

int openswmm::controls::ControlEngine::addExpression	(	const std::string &	name,
		const std::string &	formula )

Parse and register a named arithmetic expression.

Parameters

name	Copied case-insensitive lookup key. A duplicate redirects the name to the new expression while existing compiled expression indices remain valid.
formula	Borrowed MathExpr syntax; symbol values are resolved at evaluation.

Returns: New zero-based expression index or -1 for parser rejection, which does not change the registry. Allocation failures propagate and are not transactional.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addNamedVariable()

void openswmm::controls::ControlEngine::addNamedVariable	(	const std::string &	name,
		ConditionVar	var,
		int	idx,
		int	param = 0 )

Append a named binding without resolving or validating its object.

Parameters

name	Copied variable name; lookup is case insensitive, first duplicate wins.
var	Attribute returned when expressions/premises refer to the binding.
idx	Zero-based matching node/link/gage index; system variables ignore it.
param	Rain-history hours in [1,48] for GAGE_RAIN_PAST; otherwise ignored. Invalid indices are handled by getVariableValue(), not rejected at registration.

Here is the caller graph for this function:

◆ batchEvaluateGroup()

void openswmm::controls::ControlEngine::batchEvaluateGroup	(	PremiseSoA &	group,
		const SimulationContext &	ctx,
		double	current_time,
		double	half_step )

Gather and compare one homogeneous ordinary-variable premise group.

Parameters

[in,out]	group	Valid group created by buildPremiseSoA(), with nonnegative count and all parallel/work arrays at least count long, valid flat cache indices. Writes lhs_values/results and this engine's flat cache; variable RHS slots are set false for later scalar evaluation. Missing LHS also yields false.
	ctx	Compatible initialized context with aligned arrays and valid units.
	current_time	Absolute SWMM date in days used by link-duration variables; system clock values come from this engine's evaluate() clock members.
	half_step	Finite nonnegative comparison tolerance in days. No rule reduction, action application or control-value tracking is done here.

Here is the caller graph for this function:

◆ buildPremiseSoA()

void openswmm::controls::ControlEngine::buildPremiseSoA ( )

Rebuild flattened premise offsets, variable-type groups and work buffers. Call after any premise/rule structural change, with all counts and cumulative offsets representable as int. Expression LHS values are evaluated separately; variable RHS entries retain placeholder slots for the scalar pass. Group order is unspecified. Does not reset PID history, pending actions or diagnostics.

Here is the caller graph for this function:

◆ clearRules()

void openswmm::controls::ControlEngine::clearRules ( )

Discard rules, PID/named-expression state, caches and parser diagnostic. Use before recompiling a complete rule-text store because parseRuleText appends. Does not reset lastActionCount(), evaluation clocks, tracked modulation values or context target settings/logs. Existing borrowed rule elements are invalidated.

◆ evaluate()

int openswmm::controls::ControlEngine::evaluate	(	SimulationContext &	ctx,
		double	current_date,
		double	dt,
		bool	rule_time_reached = true )

Evaluate premises, arbitrate actions and update link target settings.

Parameters

[in,out]	ctx	Compatible initialized context with aligned object arrays, valid flow-unit enum, tables and current link state. Updates target settings, table cursors, optional action log and interned rule names; routing owns actual settings and link open/closed transition timestamps.
	current_date	Finite absolute SWMM date in days at step start plus 1 ms, as supplied by routing. Its floor, fraction and difference from start_date form the date, clock and elapsed-time variables respectively.
	dt	Finite positive routing step in seconds; half this duration in days is the equality window, and PID integration converts it to minutes.
	rule_time_reached	Caller-computed RULE_STEP gate. False returns zero and resets lastActionCount(), retaining previous clocks, caches and PID state.

Returns: Number of targets whose exact numeric value changed, not evaluated or queued actions. Rebuild premise caches after changing rules. All ordinary and scalar premises are evaluated before ordered Boolean reduction (a failed AND stops that reduction). Actions run last-authored first within a selected branch; first candidate per link wins ties, strictly higher priority replaces it. Modulators update before arbitration, so losing PID actions can advance history. Numeric targets are not clamped here. Exceptions can leave partial state.

Here is the call graph for this function:

◆ init()

void openswmm::controls::ControlEngine::init ( const std::vector< Rule > & rules )

Copy compiled rules, reindex actions and rebuild premise caches.

Parameters

rules Borrowed rules copied into this engine; object/table indices must match the simulation subsequently evaluated and rule/premise counts must fit int. Clears PID history and the obsolete private link clock. Retains named variables, expressions, diagnostics and last-action count. Copied PID indices do not create PID states; use parsed rules when PID controller state is required.

Here is the call graph for this function:

◆ lastActionCount()

int openswmm::controls::ControlEngine::lastActionCount ( ) const

inline

Read the target-change count of the last returned evaluate() call.

Returns: Stored count, initially zero; a skipped RULE_STEP call stores zero. init(), clearRules() and parsing do not reset this count.

◆ lastParseError()

const ParseError & openswmm::controls::ControlEngine::lastParseError ( ) const

inlinenoexcept

Borrow the most recent parser diagnostic without clearing it.

Returns: Member reference valid until destruction; contents change on parse/clear. Line/code/token/message describe rejection only after parseRuleText() returned -1. Copy before subsequent parsing if the diagnostic must be retained.

Here is the caller graph for this function:

◆ parseRuleText()

int openswmm::controls::ControlEngine::parseRuleText	(	const std::string &	text,
		SimulationContext &	ctx )

Append rules, named variables and expressions from control-section text.

Parameters

text	Borrowed whitespace-tokenized body without a [CONTROLS] header; keywords/named lookups are case insensitive, object names use context tables. Time constants accept hours or colon time; date/calendar/status parsing follows the helper contracts. No quoted-name or inline-comment grammar is added here.
ctx	Borrowed model used to resolve object, curve and time-series indices; this method does not modify its hydraulic state.

Returns: Newly appended rule count, zero for blank input, or -1 with lastParseError(). Clears the prior diagnostic first. Completed rules/variables/expressions/PID states appended before rejection remain; failure does not rebuild caches, so clear/reparse before evaluation after a rejected append. Successful nonempty input reindexes all actions and rebuilds caches. Extra tokens and otherwise unhandled lines can be ignored; this is not full structural model validation.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ rules()

std::vector< Rule > & openswmm::controls::ControlEngine::rules ( )

inline

Borrow the mutable compiled rule sequence.

Returns: Owned vector valid until destruction; structural edits invalidate element references/caches. Caller reindexes action rule_idx and rebuilds premise caches before evaluation, and keeps PID/expression/object indices compatible.

Here is the caller graph for this function:

Friends And Related Symbol Documentation

◆ openswmm::SWMMEngine

friend class openswmm::SWMMEngine

friend

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

/home/runner/work/openswmm.engine/openswmm.engine/src/engine/controls/Controls.hpp
/home/runner/work/openswmm.engine/openswmm.engine/src/engine/controls/Controls.cpp

Classes

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ addExpression()

◆ addNamedVariable()

◆ batchEvaluateGroup()

◆ buildPremiseSoA()

◆ clearRules()

◆ evaluate()

◆ init()

◆ lastActionCount()

◆ lastParseError()

◆ parseRuleText()

◆ rules()

Friends And Related Symbol Documentation

◆ openswmm::SWMMEngine