C API — the reaction system ([REACTION_*] / .rxn) surface for GUI editors (E-C1: validation + discovery). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_reactions.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	SWMM_RXN_SCOPE_TERM 0

#define	SWMM_RXN_SCOPE_PIPE 1

#define	SWMM_RXN_SCOPE_TANK 2

#define	SWMM_RXN_SCOPE_SUBCATCHMENT 4

#define	SWMM_RXN_SCOPE_SUBSURFACE 3

#define	SWMM_RXN_FORM_NONE 0

#define	SWMM_RXN_FORM_RATE 1

#define	SWMM_RXN_FORM_EQUIL 2

#define	SWMM_RXN_FORM_FORMULA 3

Functions
SWMM_ENGINE_API int	swmm_reaction_validate_expression (SWMM_Engine engine, int scope, const char expr, char errbuf, int buflen, int *col_out)
	Compile an expression against the current reaction/model vocabulary without changing state.

SWMM_ENGINE_API int	swmm_reaction_species_count (SWMM_Engine engine)
	Count declared reaction species.

SWMM_ENGINE_API int	swmm_reaction_species_get (SWMM_Engine engine, int idx, char name, int name_len, int is_wall, char units, int units_len, double atol, double *rtol)
	Read one reaction-species declaration.

SWMM_ENGINE_API int	swmm_reaction_coeff_count (SWMM_Engine engine)
	Count declared coefficients.

SWMM_ENGINE_API int	swmm_reaction_coeff_get (SWMM_Engine engine, int idx, char name, int name_len, int is_param, double *value)
	Read one reaction coefficient declaration.

SWMM_ENGINE_API int	swmm_reaction_term_count (SWMM_Engine engine)
	Count declared intermediate terms.

SWMM_ENGINE_API int	swmm_reaction_term_get (SWMM_Engine engine, int idx, char name, int name_len, char expr, int expr_len)
	Read an intermediate term name and source expression.

SWMM_ENGINE_API int	swmm_reaction_expr_get (SWMM_Engine engine, int scope, int species_idx, int form, char expr, int expr_len)
	Read a species reaction form and source text in one supported domain.

SWMM_ENGINE_API int	swmm_reaction_option_get (SWMM_Engine engine, const char key, char value, int value_len)
	Format a reaction option as its canonical token or numeric string.

SWMM_ENGINE_API int	swmm_reaction_species_add (SWMM_Engine engine, const char name, int is_wall, const char units, double atol, double rtol)
	Append a species and rebuild its unified registry block.

SWMM_ENGINE_API int	swmm_reaction_species_remove (SWMM_Engine engine, int idx)
	Remove an unreferenced species and renumber dependent reaction indices.

SWMM_ENGINE_API int	swmm_reaction_coeff_add (SWMM_Engine engine, const char *name, int is_param, double value)
	Append a coefficient without recompiling unchanged expression indices.

SWMM_ENGINE_API int	swmm_reaction_coeff_set_value (SWMM_Engine engine, int idx, double value)
	Replace one coefficient value without changing its identity or compiled index.

SWMM_ENGINE_API int	swmm_reaction_coeff_remove (SWMM_Engine engine, int idx)
	Remove a coefficient only when no compiled expression/override uses it.

SWMM_ENGINE_API int	swmm_reaction_term_add (SWMM_Engine engine, const char name, const char expr)
	Append a copied intermediate term and eagerly compile the system.

SWMM_ENGINE_API int	swmm_reaction_term_set_expr (SWMM_Engine engine, int idx, const char *expr)
	Replace a term source expression and recompile dependent expressions.

SWMM_ENGINE_API int	swmm_reaction_term_remove (SWMM_Engine engine, int idx)
	Remove an intermediate term that has no compiled references.

SWMM_ENGINE_API int	swmm_reaction_expr_set (SWMM_Engine engine, int scope, int species_idx, int form, const char *expr)
	Set or clear a species reaction expression in one domain.

SWMM_ENGINE_API int	swmm_reaction_option_set (SWMM_Engine engine, const char key, const char value)
	Parse and assign one reaction option before initialization.

SWMM_ENGINE_API int	swmm_reaction_init_global_get (SWMM_Engine engine, int species_idx, double *value)
	Read a species global initial concentration.

SWMM_ENGINE_API int	swmm_reaction_init_global_set (SWMM_Engine engine, int species_idx, double value)
	Assign a species global initial concentration before initialization.

SWMM_ENGINE_API int	swmm_reaction_rain_conc_get (SWMM_Engine engine, int species_idx, double *value)
	Read a species rainfall concentration.

SWMM_ENGINE_API int	swmm_reaction_rain_conc_set (SWMM_Engine engine, int species_idx, double value)
	Assign a species rainfall concentration before initialization.

SWMM_ENGINE_API int	swmm_reaction_init_elem_count (SWMM_Engine engine)
	Count declared per-element reaction seed rows.

SWMM_ENGINE_API int	swmm_reaction_init_elem_get (SWMM_Engine engine, int entry_idx, int is_link, int elem_idx, int species_idx, double value)
	Read a reaction per-element initial concentration row.

SWMM_ENGINE_API int	swmm_reaction_init_elem_set (SWMM_Engine engine, int is_link, int elem_idx, int species_idx, double value)
	Upsert a reaction per-element initial concentration.

SWMM_ENGINE_API int	swmm_reaction_init_elem_remove (SWMM_Engine engine, int entry_idx)
	Remove one per-element reaction seed row and shift later indices down.

SWMM_ENGINE_API int	swmm_reactions_serialize (SWMM_Engine engine, char buf, int buflen, int needed_len)
	Serialize the current reaction system into complete NUL-terminated canonical text.

SWMM_ENGINE_API int	swmm_reactions_check_text (SWMM_Engine engine, const char text, char errbuf, int buflen)
	Parse and compile complete reaction text without retaining the staged system.

SWMM_ENGINE_API int	swmm_reactions_apply_text (SWMM_Engine engine, const char text, char errbuf, int buflen)
	Replace the reaction system and its registry block from complete component text.

SWMM_ENGINE_API int	swmm_reactions_save (SWMM_Engine engine, const char *path_or_null)
	Write canonical reaction text to an explicit or bound config path.

SWMM_ENGINE_API int	swmm_reaction_hydvar_count (void)
	Count hydraulic identifiers exposed by the expression compiler.

SWMM_ENGINE_API int	swmm_reaction_hydvar_get (int idx, char name, int name_len, char description, int desc_len)
	Copy one compiler hydraulic-variable name and optional description.

SWMM_ENGINE_API int	swmm_reaction_function_count (void)
	Count built-in expression functions.

SWMM_ENGINE_API int	swmm_reaction_function_get (int idx, char name, int name_len, int arity)
	Copy a compiler function name and its argument arity.

Detailed Description

C API — the reaction system ([REACTION_*] / .rxn) surface for GUI editors (E-C1: validation + discovery).

The discovery getters are the AUTHORITATIVE completer/highlighter vocabulary (MSX plan GUI contract): a GUI must enumerate species, coefficients, terms, hydraulic variables, and functions from here rather than hard-coding lists, so vocabulary drift is structural, not disciplinary. The hydraulic-variable and function getters are engine-less statics — usable before any model is open, and there is exactly one copy of the truth (the expression compiler's own tables).

Author: Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright: Copyright (c) 2026 Caleb Buahin. All rights reserved.

License: Apache-2.0

Macro Definition Documentation

◆ SWMM_RXN_FORM_EQUIL

#define SWMM_RXN_FORM_EQUIL 2

◆ SWMM_RXN_FORM_FORMULA

#define SWMM_RXN_FORM_FORMULA 3

◆ SWMM_RXN_FORM_NONE

#define SWMM_RXN_FORM_NONE 0

◆ SWMM_RXN_FORM_RATE

#define SWMM_RXN_FORM_RATE 1

◆ SWMM_RXN_SCOPE_PIPE

#define SWMM_RXN_SCOPE_PIPE 1

◆ SWMM_RXN_SCOPE_SUBCATCHMENT

#define SWMM_RXN_SCOPE_SUBCATCHMENT 4

Wet non-LID subcatchment pool.

◆ SWMM_RXN_SCOPE_SUBSURFACE

#define SWMM_RXN_SCOPE_SUBSURFACE 3

Explicit aquifer expression validation.

◆ SWMM_RXN_SCOPE_TANK

#define SWMM_RXN_SCOPE_TANK 2

◆ SWMM_RXN_SCOPE_TERM

#define SWMM_RXN_SCOPE_TERM 0

Function Documentation

◆ swmm_reaction_coeff_add()

SWMM_ENGINE_API int swmm_reaction_coeff_add	(	SWMM_Engine	engine,
		const char *	name,
		int	is_param,
		double	value )

Append a coefficient without recompiling unchanged expression indices.

Appending preserves existing coefficient indices; does not automatically mark/activate a complete reaction transport profile.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	name	Non-null, nonempty copied name; duplicate coefficient/species/term names are refused.
[in]	is_param	0=CONSTANT, any nonzero value=PARAMETER.
[in]	value	Stored coefficient value, with expression-specific units; assigned without finite/range validation.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_coeff_count()

SWMM_ENGINE_API int swmm_reaction_coeff_count ( SWMM_Engine engine )

Count declared coefficients.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative stored row count, or -1 for null engine.

◆ swmm_reaction_coeff_get()

SWMM_ENGINE_API int swmm_reaction_coeff_get	(	SWMM_Engine	engine,
		int	idx,
		char *	name,
		int	name_len,
		int *	is_param,
		double *	value )

Read one reaction coefficient declaration.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	idx	Zero-based coefficient index.
[out]	name	Non-null caller-owned name buffer, NUL-terminated and silently truncated to name_len-1 bytes.
[in]	name_len	Positive name-buffer capacity in bytes including NUL.
[out]	is_param	Non-null destination: 1=PARAMETER, 0=CONSTANT.
[out]	value	Non-null destination for the stored coefficient value; units are those assumed by its expressions.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_reaction_coeff_remove()

SWMM_ENGINE_API int swmm_reaction_coeff_remove	(	SWMM_Engine	engine,
		int	idx )

Remove a coefficient only when no compiled expression/override uses it.

Referenced coefficients or parameter-override bindings return BADPARAM. Later coefficient/override indices shift; the system is recompiled and reaction/registry snapshots restored on compile refusal.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	idx	Zero-based coefficient index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_coeff_set_value()

SWMM_ENGINE_API int swmm_reaction_coeff_set_value	(	SWMM_Engine	engine,
		int	idx,
		double	value )

Replace one coefficient value without changing its identity or compiled index.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	idx	Zero-based coefficient index.
[in]	value	New raw coefficient value; no finite/range validation is imposed.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_expr_get()

SWMM_ENGINE_API int swmm_reaction_expr_get	(	SWMM_Engine	engine,
		int	scope,
		int	species_idx,
		int *	form,
		char *	expr,
		int	expr_len )

Read a species reaction form and source text in one supported domain.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	scope	SWMM_RXN_SCOPE_PIPE, TANK or SUBCATCHMENT only; TERM/SUBSURFACE are not expression-table selectors here.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[out]	form	Non-null SWMM_RXN_FORM_* output; NONE when no expression is configured.
[out]	expr	Non-null caller-owned expression buffer, NUL-terminated and silently truncated to expr_len-1 bytes.
[in]	expr_len	Positive expression-buffer capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_reaction_expr_set()

SWMM_ENGINE_API int swmm_reaction_expr_set	(	SWMM_Engine	engine,
		int	scope,
		int	species_idx,
		int	form,
		const char *	expr )

Set or clear a species reaction expression in one domain.

Recompiles the full system and restores reaction/registry snapshots on refusal. Does not offer a SUBSURFACE-law setter through this per-species expression-table API.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	scope	SWMM_RXN_SCOPE_PIPE, TANK or SUBCATCHMENT; other scopes are refused.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[in]	form	SWMM_RXN_FORM_NONE, RATE, EQUIL or FORMULA.
[in]	expr	Borrowed text copied for non-NONE form; must then be non-null/nonempty. NONE ignores this pointer and clears the source text.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_function_count()

SWMM_ENGINE_API int swmm_reaction_function_count ( void )

Count built-in expression functions.

Returns: Number of function metadata entries in the compiler vocabulary.

Here is the call graph for this function:

◆ swmm_reaction_function_get()

SWMM_ENGINE_API int swmm_reaction_function_get	(	int	idx,
		char *	name,
		int	name_len,
		int *	arity )

Copy a compiler function name and its argument arity.

Parameters

[in]	idx	Zero-based index in [0,swmm_reaction_function_count()).
[out]	name	Non-null caller-owned name buffer, NUL-terminated and silently truncated to name_len-1 bytes.
[in]	name_len	Positive name-buffer capacity in bytes including NUL.
[out]	arity	Non-null integer output for the number of accepted arguments.

Returns: SWMM_OK; SWMM_ERR_BADINDEX for invalid idx or SWMM_ERR_BADPARAM for invalid required outputs.

Here is the call graph for this function:

◆ swmm_reaction_hydvar_count()

SWMM_ENGINE_API int swmm_reaction_hydvar_count ( void )

Count hydraulic identifiers exposed by the expression compiler.

Engine-independent metadata; does not certify that a variable is populated in every reaction scope.

Returns: Number of compiler hydraulic-variable vocabulary entries.

Here is the call graph for this function:

◆ swmm_reaction_hydvar_get()

SWMM_ENGINE_API int swmm_reaction_hydvar_get	(	int	idx,
		char *	name,
		int	name_len,
		char *	description,
		int	desc_len )

Copy one compiler hydraulic-variable name and optional description.

Parameters

[in]	idx	Zero-based index in [0,swmm_reaction_hydvar_count()).
[out]	name	Non-null caller-owned name buffer, NUL-terminated and silently truncated to name_len-1 bytes.
[in]	name_len	Positive name-buffer capacity in bytes including NUL.
[out]	description	Optional caller-owned description buffer, NUL-terminated/truncated when desc_len>0.
[in]	desc_len	Description capacity including NUL; nonpositive suppresses copying.

Returns: SWMM_OK; SWMM_ERR_BADINDEX for invalid idx or SWMM_ERR_BADPARAM for null/nonpositive-capacity name output.

Here is the call graph for this function:

◆ swmm_reaction_init_elem_count()

SWMM_ENGINE_API int swmm_reaction_init_elem_count ( SWMM_Engine engine )

Count declared per-element reaction seed rows.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative stored row count, or -1 for null engine.

◆ swmm_reaction_init_elem_get()

SWMM_ENGINE_API int swmm_reaction_init_elem_get	(	SWMM_Engine	engine,
		int	entry_idx,
		int *	is_link,
		int *	elem_idx,
		int *	species_idx,
		double *	value )

Read a reaction per-element initial concentration row.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	entry_idx	Zero-based initial-row index.
[out]	is_link	Non-null destination: 0=node, 1=link.
[out]	elem_idx	Non-null stored element-index destination.
[out]	species_idx	Non-null reaction-species-index destination.
[out]	value	Non-null stored concentration destination, in the declared species units.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_reaction_init_elem_remove()

SWMM_ENGINE_API int swmm_reaction_init_elem_remove	(	SWMM_Engine	engine,
		int	entry_idx )

Remove one per-element reaction seed row and shift later indices down.

Removes the reaction seed arrays directly; does not delete an independent [INITIAL_QUALITY] authoring row through this wrapper.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	entry_idx	Zero-based existing initial-row index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_init_elem_set()

SWMM_ENGINE_API int swmm_reaction_init_elem_set	(	SWMM_Engine	engine,
		int	is_link,
		int	elem_idx,
		int	species_idx,
		double	value )

Upsert a reaction per-element initial concentration.

Updates an existing (kind,element,species) row in place or appends. Seeds initial state rather than modifying running concentrations; this wrapper updates reaction seed arrays directly and does not mirror a general [INITIAL_QUALITY] authoring row.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	is_link	0 selects node; any nonzero value selects link.
[in]	elem_idx	Zero-based existing element index in the selected table.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[in]	value	Concentration in declared species units; negative values are refused. Caller must provide a finite value (no separate finiteness guard).

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_init_global_get()

SWMM_ENGINE_API int swmm_reaction_init_global_get	(	SWMM_Engine	engine,
		int	species_idx,
		double *	value )

Read a species global initial concentration.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[out]	value	Non-null concentration output in declared species units; zero when the aligned optional array has no entry.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_reaction_init_global_set()

SWMM_ENGINE_API int swmm_reaction_init_global_set	(	SWMM_Engine	engine,
		int	species_idx,
		double	value )

Assign a species global initial concentration before initialization.

Grows the aligned source/seed array with zero defaults if needed. The negative comparison guard does not independently reject NaN/infinity.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[in]	value	Nonnegative concentration in declared species units; caller must provide a finite value.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_option_get()

SWMM_ENGINE_API int swmm_reaction_option_get	(	SWMM_Engine	engine,
		const char *	key,
		char *	value,
		int	value_len )

Format a reaction option as its canonical token or numeric string.

Temperature is degrees C, reaction timesteps follow their configured option convention, and numeric formatting uses the implementation standard decimal formatting; a truncated result still succeeds.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	key	Non-null case-insensitive SOLVER, COUPLING, RATE_UNITS, WALL_GEOMETRY, AREA_UNITS, PATTERN_TIMESTEP, TIMESTEP, ATOL, RTOL or TEMPERATURE.
[out]	value	Non-null caller-owned result buffer, NUL-terminated/truncated to value_len-1 bytes.
[in]	value_len	Positive byte capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_reaction_option_set()

SWMM_ENGINE_API int swmm_reaction_option_set	(	SWMM_Engine	engine,
		const char *	key,
		const char *	value )

Parse and assign one reaction option before initialization.

SOLVER accepts EUL/RK5/ROS2/BDF2, COUPLING NONE/FULL, RATE_UNITS SEC/MIN/HR/DAY, AREA_UNITS FT2/M2/CM2, WALL_GEOMETRY YES/NO. PATTERN_TIMESTEP requires finite >0; TIMESTEP checks >=0; ATOL/RTOL check >0; TEMPERATURE requires finite degrees C. Supply finite numbers even where only comparison guards exist. WALL_GEOMETRY recompiles with rollback; the other assignments do not recompile the full system.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	key	Non-null case-insensitive option key accepted by swmm_reaction_option_get().
[in]	value	Non-null input token/string. Enum values are case-insensitive; numeric strings must parse completely.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_rain_conc_get()

SWMM_ENGINE_API int swmm_reaction_rain_conc_get	(	SWMM_Engine	engine,
		int	species_idx,
		double *	value )

Read a species rainfall concentration.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[out]	value	Non-null concentration output in declared species units; zero when the aligned optional array has no entry.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_reaction_rain_conc_set()

SWMM_ENGINE_API int swmm_reaction_rain_conc_set	(	SWMM_Engine	engine,
		int	species_idx,
		double	value )

Assign a species rainfall concentration before initialization.

Grows the aligned source/seed array with zero defaults if needed. The >=0 guard rejects NaN but does not independently reject positive infinity.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	species_idx	Zero-based reaction-species index, not a pollutant or unified registry index.
[in]	value	Nonnegative concentration in declared species units; caller must provide a finite value.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_species_add()

SWMM_ENGINE_API int swmm_reaction_species_add	(	SWMM_Engine	engine,
		const char *	name,
		int	is_wall,
		const char *	units,
		double	atol,
		double	rtol )

Append a species and rebuild its unified registry block.

Appends empty PIPE/TANK/SUBCATCHMENT forms and zero global/rain concentrations, preserves the reserved registry tail, then recompiles. Reaction/registry snapshots are restored on compile refusal; success marks reactions configured.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	name	Non-null, nonempty copied name; collisions with registry species, coefficients or terms are refused.
[in]	is_wall	0=BULK; any nonzero value=WALL.
[in]	units	Non-null copied species unit label; this API does not perform unit dimensional analysis.
[in]	atol	Nonnegative species absolute tolerance; 0 uses global. Caller must provide a finite value.
[in]	rtol	Nonnegative species relative tolerance; 0 uses global. Caller must provide a finite value.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_species_count()

SWMM_ENGINE_API int swmm_reaction_species_count ( SWMM_Engine engine )

Count declared reaction species.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative stored row count, or -1 for null engine.

◆ swmm_reaction_species_get()

SWMM_ENGINE_API int swmm_reaction_species_get	(	SWMM_Engine	engine,
		int	idx,
		char *	name,
		int	name_len,
		int *	is_wall,
		char *	units,
		int	units_len,
		double *	atol,
		double *	rtol )

Read one reaction-species declaration.

Returns declaration metadata without initializing runtime transport. Every listed output is required.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	idx	Zero-based reaction-species index.
[out]	name	Non-null caller-owned name buffer, NUL-terminated and silently truncated to name_len-1 bytes.
[in]	name_len	Positive name-buffer capacity in bytes including NUL.
[out]	is_wall	Non-null destination: 0=BULK, 1=WALL.
[out]	units	Non-null caller-owned declared unit-label buffer, NUL-terminated/truncated.
[in]	units_len	Positive unit-label capacity including NUL.
[out]	atol	Non-null stored species absolute tolerance; 0 means use the global tolerance.
[out]	rtol	Non-null stored species relative tolerance; 0 means use the global tolerance.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

Here is the call graph for this function:

◆ swmm_reaction_species_remove()

SWMM_ENGINE_API int swmm_reaction_species_remove	(	SWMM_Engine	engine,
		int	idx )

Remove an unreferenced species and renumber dependent reaction indices.

Refuses a species referenced by compiled expressions, subsurface laws or source rows. Removes its expression/init/law rows, prunes matching [INITIAL_QUALITY] species rows, shifts later species indices and rebuilds the registry. Recompilation restores reaction/registry snapshots on refusal; the [INITIAL_QUALITY] pruning is performed separately by this implementation and is not part of those snapshots.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	idx	Zero-based existing reaction-species index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_term_add()

SWMM_ENGINE_API int swmm_reaction_term_add	(	SWMM_Engine	engine,
		const char *	name,
		const char *	expr )

Append a copied intermediate term and eagerly compile the system.

Restores reaction/registry snapshots on compilation refusal. Later terms may reference this term after successful append.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	name	Non-null, nonempty copied unique term name; collision with a term/species/coefficient is refused.
[in]	expr	Non-null copied expression. Term references must obey declaration ordering when recompiling the full system.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

Here is the call graph for this function:

◆ swmm_reaction_term_count()

SWMM_ENGINE_API int swmm_reaction_term_count ( SWMM_Engine engine )

Count declared intermediate terms.

Parameters

[in] engine Non-null live engine with exclusive caller access.

Returns: Nonnegative stored row count, or -1 for null engine.

◆ swmm_reaction_term_get()

SWMM_ENGINE_API int swmm_reaction_term_get	(	SWMM_Engine	engine,
		int	idx,
		char *	name,
		int	name_len,
		char *	expr,
		int	expr_len )

Read an intermediate term name and source expression.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	idx	Zero-based term index in declaration order.
[out]	name	Non-null caller-owned name buffer, NUL-terminated and silently truncated to name_len-1 bytes.
[in]	name_len	Positive name-buffer capacity in bytes including NUL.
[out]	expr	Non-null caller-owned expression buffer, NUL-terminated and silently truncated to expr_len-1 bytes.
[in]	expr_len	Positive expression-buffer capacity including NUL.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments.

◆ swmm_reaction_term_remove()

SWMM_ENGINE_API int swmm_reaction_term_remove	(	SWMM_Engine	engine,
		int	idx )

Remove an intermediate term that has no compiled references.

Compiled references return BADPARAM. Later term indices shift; recompilation derives new indices and restores reaction/registry snapshots on refusal.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	idx	Zero-based existing term index.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_term_set_expr()

SWMM_ENGINE_API int swmm_reaction_term_set_expr	(	SWMM_Engine	engine,
		int	idx,
		const char *	expr )

Replace a term source expression and recompile dependent expressions.

Restores reaction/registry snapshots on compilation refusal, keeping the old compiled expression system.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	idx	Zero-based existing term index.
[in]	expr	Non-null copied expression text; full-system ordering/context rules apply.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reaction_validate_expression()

SWMM_ENGINE_API int swmm_reaction_validate_expression	(	SWMM_Engine	engine,
		int	scope,
		const char *	expr,
		char *	errbuf,
		int	buflen,
		int *	col_out )

Compile an expression against the current reaction/model vocabulary without changing state.

TERM validation accepts references to all currently declared terms; it does not validate forward-only file ordering, which is enforced during whole-system compilation. Uses disposable token/span storage and applies populated-hydraulic-variable context checks.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	scope	SWMM_RXN_SCOPE_TERM, PIPE, TANK, SUBSURFACE or SUBCATCHMENT; selects context-specific availability checks.
[in]	expr	Non-null borrowed NUL-terminated expression text.
[out]	errbuf	Optional caller-owned diagnostic buffer; NUL-terminated/truncated when buflen>0, cleared before substantive validation.
[in]	buflen	Diagnostic capacity in bytes including NUL; nonpositive suppresses diagnostic copying.
[out]	col_out	Optional 1-based error column; initialized to -1 when no precise location is available.

Returns: SWMM_OK if expression/context compilation succeeds; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null text, invalid scope or a compile/context refusal.

Here is the call graph for this function:

◆ swmm_reactions_apply_text()

SWMM_ENGINE_API int swmm_reactions_apply_text	(	SWMM_Engine	engine,
		const char *	text,
		char *	errbuf,
		int	buflen )

Replace the reaction system and its registry block from complete component text.

Replaces the current reaction registry block while preserving the reserved-species tail. On parser/application refusal, restores the backed-up reaction system and registry and returns the first diagnostic. Does not write a component file or update its bound path automatically.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	text	Non-null, nonempty borrowed .rxn text; parsed/compiled before retaining the replacement.
[out]	errbuf	Optional caller-owned diagnostic buffer; NUL-terminated/truncated when buflen>0, cleared before substantive validation.
[in]	buflen	Diagnostic capacity in bytes including NUL; nonpositive suppresses diagnostic copying.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reactions_check_text()

SWMM_ENGINE_API int swmm_reactions_check_text	(	SWMM_Engine	engine,
		const char *	text,
		char *	errbuf,
		int	buflen )

Parse and compile complete reaction text without retaining the staged system.

Stages through the live reaction/registry context and restores both after validation; exclusive editable-state access is therefore required. Returns the first parser/application diagnostic on refusal and leaves stored reaction/registry state unchanged on normal success/refusal paths.

Parameters

[in]	engine	Non-null engine in BUILDING or OPENED; mutation is refused after initialization.
[in]	text	Non-null, nonempty borrowed component-format .rxn text.
[out]	errbuf	Optional caller-owned diagnostic buffer; NUL-terminated/truncated when buflen>0, cleared before substantive validation.
[in]	buflen	Diagnostic capacity in bytes including NUL; nonpositive suppresses diagnostic copying.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid row/species/element index, or SWMM_ERR_BADPARAM for invalid required arguments. SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

◆ swmm_reactions_save()

SWMM_ENGINE_API int swmm_reactions_save	(	SWMM_Engine	engine,
		const char *	path_or_null )

Write canonical reaction text to an explicit or bound config path.

No lifecycle guard. Opens binary output with truncation, does not provide atomic publication, and does not update registration path metadata. An explicit path overrides the bound path only for this call.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[in]	path_or_null	Optional NUL-terminated UTF-8 destination. NULL/empty uses the reactions component binding, preferring its resolved path to the authored token.

Returns: SWMM_OK after a good stream write; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM when no path is available or open/write fails.

Here is the call graph for this function:

◆ swmm_reactions_serialize()

SWMM_ENGINE_API int swmm_reactions_serialize	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen,
		int *	needed_len )

Serialize the current reaction system into complete NUL-terminated canonical text.

Does not change authoring or write a file; the canonical writer determines section ordering and numeric spelling.

Parameters

[in]	engine	Non-null live engine with exclusive caller access.
[out]	buf	Caller-owned text destination, or NULL to query size regardless of buflen. Short non-null buffers receive no bytes.
[in]	buflen	Destination capacity in bytes including NUL; must cover needed_len when buf is non-null.
[out]	needed_len	Non-null required byte count INCLUDING NUL, written before short-buffer refusal.

Returns: SWMM_OK after sizing/full copy; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null needed_len/insufficient non-null buffer.

Here is the call graph for this function:

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ SWMM_RXN_FORM_EQUIL

◆ SWMM_RXN_FORM_FORMULA

◆ SWMM_RXN_FORM_NONE

◆ SWMM_RXN_FORM_RATE

◆ SWMM_RXN_SCOPE_PIPE

◆ SWMM_RXN_SCOPE_SUBCATCHMENT

◆ SWMM_RXN_SCOPE_SUBSURFACE

◆ SWMM_RXN_SCOPE_TANK

◆ SWMM_RXN_SCOPE_TERM

Function Documentation

◆ swmm_reaction_coeff_add()

◆ swmm_reaction_coeff_count()

◆ swmm_reaction_coeff_get()

◆ swmm_reaction_coeff_remove()

◆ swmm_reaction_coeff_set_value()

◆ swmm_reaction_expr_get()

◆ swmm_reaction_expr_set()

◆ swmm_reaction_function_count()

◆ swmm_reaction_function_get()

◆ swmm_reaction_hydvar_count()

◆ swmm_reaction_hydvar_get()

◆ swmm_reaction_init_elem_count()

◆ swmm_reaction_init_elem_get()

◆ swmm_reaction_init_elem_remove()

◆ swmm_reaction_init_elem_set()

◆ swmm_reaction_init_global_get()

◆ swmm_reaction_init_global_set()

◆ swmm_reaction_option_get()

◆ swmm_reaction_option_set()

◆ swmm_reaction_rain_conc_get()

◆ swmm_reaction_rain_conc_set()

◆ swmm_reaction_species_add()

◆ swmm_reaction_species_count()

◆ swmm_reaction_species_get()

◆ swmm_reaction_species_remove()

◆ swmm_reaction_term_add()

◆ swmm_reaction_term_count()

◆ swmm_reaction_term_get()

◆ swmm_reaction_term_remove()

◆ swmm_reaction_term_set_expr()

◆ swmm_reaction_validate_expression()

◆ swmm_reactions_apply_text()

◆ swmm_reactions_check_text()

◆ swmm_reactions_save()

◆ swmm_reactions_serialize()