openswmm::treatment Namespace Reference

Classes
struct	Token
struct	TreatExpr

Enumerations
enum class	TokenType : int {   NUMBER = 0 ,   VARIABLE = 1 ,   ADD = 2 ,   SUB = 3 ,   MUL = 4 ,   DIV = 5 ,   POW = 6 ,   NEG = 7 ,   FUNC_EXP = 8 ,   FUNC_LOG = 9 ,   FUNC_SQRT = 10 ,   FUNC_MIN = 11 ,   FUNC_MAX = 12 ,   FUNC_ABS = 13 ,   FUNC_SGN = 14 ,   FUNC_STEP = 15 ,   LPAREN = 16 ,   RPAREN = 17 ,   COMMA = 18 }
enum class	TreatVar : int {   C = 0 ,   R = 1 ,   DT = 2 ,   HRT = 3 ,   Q = 4 ,   V = 5 ,   D = 6 ,   C_POLLUT = 7 ,   R_POLLUT = 8 ,   AREA = 9 }

Functions
int	parse (const std::string &expr_str, TreatExpr &result)
	Parse the strict C/R equation prefix and convert built-in-only RHS to postfix.
int	validate (const std::string &expr_str, std::string &msg, int &col)
	Validate built-in-only treatment grammar with an editor diagnostic and source offset.
double	evaluate (const TreatExpr &expr, double c, double dt, double hrt, double q, double v, double d, double area)
	Evaluate built-in treatment postfix with scalar hydraulic inputs only.
double	applyTreatment (const TreatExpr &expr, double c_in, double dt, double hrt, double q, double v, double d, double area)
	Apply scalar-only treatment and clamp its output to removal-only concentration bounds.
int	parse (const std::string &expr_str, TreatExpr &result, const std::vector< std::string > &pollut_names)
	Parse named pollutant/co-treatment references against a stable name table.
double	evaluate (const TreatExpr &expr, double c, double dt, double hrt, double q, double v, double d, const double *cin, const double *removal, int n_pollut, double area, const double *cpollut)
	Evaluate treatment postfix with optional pollutant concentration/removal views.
int	parse (const std::string &expr_str, TreatExpr &result, int(*pollut_lookup)(const std::string &name))
	Parse named treatment references using an optional native name-resolution function.

Enumeration Type Documentation

TokenType

enum class openswmm::treatment::TokenType : int

strong

Enumerator
NUMBER
VARIABLE
ADD
SUB
MUL
DIV
POW
NEG	Unary negation.
FUNC_EXP
FUNC_LOG
FUNC_SQRT
FUNC_MIN
FUNC_MAX
FUNC_ABS
FUNC_SGN
FUNC_STEP	Heaviside step.
LPAREN	Left parenthesis (parser internal, never in output)
RPAREN	Right parenthesis (parser internal, never in output)
COMMA	Comma separator for min/max (parser internal)

TreatVar

enum class openswmm::treatment::TreatVar : int

strong

Enumerator
C	Current concentration (this pollutant)
R	Removal fraction (this pollutant, unused in expressions)
DT	Timestep (sec)
HRT	Hydraulic residence time (hours, per legacy convention)
Q	Flow rate in user units (Q*UCF(FLOW), matching legacy pvFLOW)
V	Volume (ft3 or m3)
D	Depth in user units (y*UCF(LENGTH), matching legacy pvDEPTH)
C_POLLUT	Concentration of another pollutant (uses pollut_ref)
R_POLLUT	Removal fraction of another pollutant (uses pollut_ref, co-treatment)
AREA	Node surface area in user units² ((a1+a2)/2*UCF(LENGTH)², matching legacy pvAREA)

Function Documentation

applyTreatment()

double openswmm::treatment::applyTreatment	(	const TreatExpr &	expr,
		double	c_in,
		double	dt,
		double	hrt,
		double	q,
		double	v,
		double	d,
		double	area )

Apply scalar-only treatment and clamp its output to removal-only concentration bounds.

Apply treatment at a node for one pollutant.

Parameters

[in]	expr	Stable parsed expression; is_removal selects removal versus direct concentration.
[in]	c_in	Finite nonnegative current/inflow native concentration to bound output.
[in]	dt	Accepted duration s.
[in]	hrt	Residence time hours.
[in]	q	Display-unit treatment flow.
[in]	v	Caller treatment volume convention, passed verbatim.
[in]	d	Display-unit node depth.
[in]	area	Display length2 node area.

Returns

For removal equation c_in*(1-clamp(eval,0,1)); for concentration min(c_in,max(0,eval)).

Note

Uses scalar evaluate (named pollutant references become0, STEP0=1); domain/malformed-stack fallbacks apply. No context mass/ledger/water/clock mutation. Allocation may throw; caller handles finite input/physical validation and books the accepted treatment mass separately.

For a removal equation (R=): the expression result is clamped to [0,1] and the output concentration is c_in * (1 - R). For a concentration equation (C=): the expression result is clamped to [0, c_in] and the output concentration is the expression result. This matches the legacy treatmnt.c behavior.

• Argument expr: Treatment expression.
• Argument c_in: Inflow/current concentration (Cin for R=, node conc for C=).
• Argument dt: Timestep (sec).
• Argument hrt: Hydraulic residence time (hours).
• Argument q: Flow.
• Argument v: Volume.
• Argument d: Depth.

  Returns

  Treated concentration.

Here is the call graph for this function:

evaluate() [1/2]

double openswmm::treatment::evaluate	(	const TreatExpr &	expr,
		double	c,
		double	dt,
		double	hrt,
		double	q,
		double	v,
		double	d,
		const double *	cin,
		const double *	removal,
		int	n_pollut,
		double	area,
		const double *	cpollut )

Evaluate treatment postfix with optional pollutant concentration/removal views.

Evaluate with co-treatment support (R_pollutant references).

Parameters

[in]	expr	Stable postfix expression; caller supplies valid stack/enum metadata and expected units.
[in]	c	Current pollutant concentration in caller's native concentration units.
[in]	dt	Accepted interval s.
[in]	hrt	Hydraulic residence time hours.
[in]	q	Native treatment FLOW/Q input in project display flow units.
[in]	v	Caller-supplied volume in its treatment convention; used verbatim (no conversion).
[in]	d	Native treatment DEPTH/D in project display length.
[in]	area	Node surface area in project display length2, used verbatim.

Returns

Stack top, zero for empty stack or missing operator operands. Extra stack entries are not rejected. R variable always zero; invalid log/sqrt domain and division by zero return0 locally, while exp/pow/ordinary arithmetic may yield nonfinite values. No automatic concentration/removal bounds or dimensional validation. Allocates an evaluation stack and may throw; no model mutation.

Parameters

[in]	cin	Optional readable n_pollut inflow concentration array, fallback for named C rows.
[in]	removal	Optional readable n_pollut removal fractions; negative/not-computed treated0.
[in]	n_pollut	Nonnegative readable extent of all provided pollutant arrays; token index outside [0,n_pollut) produces0 without dereference.
[in]	cpollut	Optional readable n_pollut current mixed concentration view, preferred over cin for named C rows; null falls back to cin, both null gives0. Arrays borrowed for call only.

Note

STEP(0)=0 here (strict>0), unlike scalar-only overload. No recursive treatment resolution; caller computes removal dependencies/loop detection. No physical/clock changes, arrays must remain stable, and external mutation concurrent with evaluation is unsupported.

• Argument expr: Parsed expression.
• Argument c: Concentration for this pollutant.
• Argument dt: Timestep (sec).
• Argument hrt: HRT (hours).
• Argument q: Flow rate in user units.
• Argument v: Volume.
• Argument d: Depth in user units.
• Argument cin: Inflow concentrations for all pollutants.
• Argument removal: Removal fractions for all pollutants (-1=not computed).
• Argument n_pollut: Number of pollutants.
• Argument area: Node surface area in user units² (Gap #16, legacy pvAREA).

  Returns

  Computed value.

evaluate() [2/2]

double openswmm::treatment::evaluate	(	const TreatExpr &	expr,
		double	c,
		double	dt,
		double	hrt,
		double	q,
		double	v,
		double	d,
		double	area )

Evaluate built-in treatment postfix with scalar hydraulic inputs only.

Evaluate a treatment expression with given variable values.

Parameters

[in]	expr	Stable postfix expression; caller supplies valid stack/enum metadata and expected units.
[in]	c	Current pollutant concentration in caller's native concentration units.
[in]	dt	Accepted interval s.
[in]	hrt	Hydraulic residence time hours.
[in]	q	Native treatment FLOW/Q input in project display flow units.
[in]	v	Caller-supplied volume in its treatment convention; used verbatim (no conversion).
[in]	d	Native treatment DEPTH/D in project display length.
[in]	area	Node surface area in project display length2, used verbatim.

Returns

Stack top, zero for empty stack or missing operator operands. Extra stack entries are not rejected. R variable always zero; invalid log/sqrt domain and division by zero return0 locally, while exp/pow/ordinary arithmetic may yield nonfinite values. No automatic concentration/removal bounds or dimensional validation. Allocates an evaluation stack and may throw; no model mutation.

Note

Co-pollutant C/R references evaluate0 in this overload. STEP(0)=1 here (>=0), unlike the co-treatment overload's strict-positive STEP. Read-only expression, no clock/physical advance.

• Original argument expr: Parsed expression.
• Original argument c: Current concentration.
• Original argument dt: Timestep (sec).
• Original argument hrt: Hydraulic residence time (hours).
• Original argument q: Flow rate.
• Original argument v: Volume.
• Original argument d: Depth.

  Returns

  Computed value (concentration or removal fraction).

Here is the caller graph for this function:

parse() [1/3]

int openswmm::treatment::parse	(	const std::string &	expr_str,
		TreatExpr &	result )

Parse the strict C/R equation prefix and convert built-in-only RHS to postfix.

Parse a treatment expression string into postfix tokens.

Parameters

[in]	expr_str	Whole C=... or R=... expression; surrounding LHS whitespace permitted, case ignored.
[out]	result	Clears tokens and is_removal first, retains pollutant_idx. Success installs postfix; shunting-yard failure clears tokens, other early failures can retain chosen removal flag.

Returns

Zero on nonempty tokenized/parenthesis-valid RHS, -1 on prefix/empty/unknown identifier or parenthesis error. Does not prove operand stack shape; use validate() for editor syntax checks.

Note

Unknown punctuation can be skipped and numeric substrings accepted by tokenizer; no independent finite evaluation/physical-unit validation. No pollutant name resolution. Allocation/numeric exceptions propagate; no context or physical/clock changes. Requires exclusive result, nonaliasing input.

The expression string should be of the form "C = ..." or "R = ...". The parser determines whether this is a concentration or removal equation from the left-hand side, then parses the right-hand side (after the '=') into a postfix token sequence using the Shunting-yard algorithm.

Supported operators: + - * / ^ (standard precedence) Supported functions: exp, log, sqrt, min, max, abs, sgn, step Supported variables: C, R, DT, HRT, Q, V, D, AREA

• Argument expr_str: Full expression string (e.g., "R = 1.0 - exp(-0.5 * HRT)").
• Argument result: [out] Parsed expression with is_removal set.

  Returns

  0 on success, -1 on parse error.

Here is the caller graph for this function:

parse() [2/3]

int openswmm::treatment::parse	(	const std::string &	expr_str,
		TreatExpr &	result,
		const std::vector< std::string > &	pollut_names )

Parse named pollutant/co-treatment references against a stable name table.

Parse a treatment expression, resolving pollutant references against a name table.

Parameters

[in]	expr_str	Callback-enabled equation text; first character C/R, no leading whitespace.
[out]	result	Reset and filled through parse_impl; partial output may remain on failure.
[in]	pollut_names	Stable native names, case-insensitive first match supplies zero-based ID; lookup returns negative for absent. Borrowed only during call, not retained.

Returns

Zero/-1 from permissive callback parser, which can accept empty RHS and does not validate operand stack shape/full LHS. No physical context/clock change; allocation/numeric errors may throw.

Note

Bare names and R_name/C_name references accepted; callback tokenizer also accepts other prefix letters before '_'. Caller compiles only qualified expressions and supplies exclusive result.

The deck-compile path holds the pollutant NAMES, not a free function, so this is the overload it needs. Without it no deck-authored pollutant reference resolves at all — neither a bare name (legacy's project_findObject(POLLUT, s) branch, treatmnt.c:313) nor the R_xxx co-treatment form.

parse() [3/3]

int openswmm::treatment::parse	(	const std::string &	expr_str,
		TreatExpr &	result,
		int(*	pollut_lookup )(const std::string &name) )

Parse named treatment references using an optional native name-resolution function.

Parse with pollutant name resolution for co-treatment.

Parameters

[in]	expr_str	Whole expression passed unchanged to legacy-permissive parse_impl.
[out]	result	Reset/fill candidate; partial parse output may remain on diagnostic failure.
[in]	pollut_lookup	Optional function pointer returning nonnegative native species ID or -1 for absent; called synchronously with original-case name, must stay callable throughout call.

Returns

Zero/-1 from parse_impl; null lookup permits built-ins only but keeps that overload's permissive prefix/empty-RHS behavior. No pointer retained or context/physical/clock update.

Note

Numeric/allocation/callback exceptions propagate. Caller handles full syntax/operand/finite qualification and exclusive result, callback side effects remain external.

• Argument expr_str: Full expression string.
• Argument result: [out] Parsed expression.
• Argument pollut_lookup: Pollutant name → index resolver. Returns -1 if not found.

  Returns

  0 on success, -1 on parse error.

validate()

int openswmm::treatment::validate	(	const std::string &	expr_str,
		std::string &	msg,
		int &	col )

Validate built-in-only treatment grammar with an editor diagnostic and source offset.

Validate a treatment expression without touching engine state.

Parameters

[in]	expr_str	Whole C=... or R=... expression; byte offsets refer to this complete string.
[out]	msg	Cleared first, populated on diagnostic failure.
[out]	col	Set -1 first; zero-based byte error offset when attributable, otherwise -1.

Returns

Zero for nonempty strict known-character/identifier, parenthesis and operand-stack-valid expression passing a final basic parse cross-check; -1 for diagnosed failure.

Note

Unlike parse() rejects unknown characters; co-pollutant references unsupported in this route. Recognizes numeric std::stod conversion errors but does not check full numeric substring consumption or finite/domain evaluation, so success is not a physical/numerical admissibility guarantee. Allocations or final parser numeric exceptions may propagate; no context/physics/clock mutation. Output references must be exclusive and msg must not alias expr_str (cleared before parsing).

Diagnostic peer of parse() for editors: same grammar, but reports a human-readable message and character position on failure. Stricter than parse() in one deliberate way — unknown characters are an error here, where the tokenizer silently skips them. Ends with a parse() cross-check so the verdict can never drift ahead of what the engine accepts.

• Argument expr_str: Full expression string ("R = ..." / "C = ...").
• Argument msg (out): Failure diagnostic (empty on success).
• Argument col (out): 0-based character offset of the error, or -1 when the position is not attributable.

  Returns

  0 when valid, -1 otherwise.

Here is the call graph for this function:

Here is the caller graph for this function: