openswmm_reactions.h File Reference

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:

Go to the source code of this file.

Macros
#define	SWMM_RXN_SCOPE_TERM   0
#define	SWMM_RXN_SCOPE_PIPE   1
#define	SWMM_RXN_SCOPE_TANK   2
#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-only validation of a reaction expression against the model's live vocabulary (species, coefficients, terms, pollutants, hydraulic variables). No state change.
SWMM_ENGINE_API int	swmm_reaction_species_count (SWMM_Engine engine)
	Number of declared MSX species (0 when no reactions configured).
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 species: name, BULK(0)/WALL(1), units, tolerances.
SWMM_ENGINE_API int	swmm_reaction_coeff_count (SWMM_Engine engine)
	Number of [REACTION_COEFFICIENTS] entries.
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 coefficient: name, PARAMETER(1)/CONSTANT(0), value.
SWMM_ENGINE_API int	swmm_reaction_term_count (SWMM_Engine engine)
	Number of [REACTION_TERMS] entries.
SWMM_ENGINE_API int	swmm_reaction_term_get (SWMM_Engine engine, int idx, char *name, int name_len, char *expr, int expr_len)
	Read one term: name and its 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' expression in one scope (PIPE or TANK).
SWMM_ENGINE_API int	swmm_reaction_option_get (SWMM_Engine engine, const char *key, char *value, int value_len)
	Read a [REACTION_OPTIONS] value as its canonical token.
SWMM_ENGINE_API int	swmm_reaction_species_add (SWMM_Engine engine, const char *name, int is_wall, const char *units, double atol, double rtol)
	Declare a species (is_wall: 0 BULK, 1 WALL; atol/rtol 0 = global).
SWMM_ENGINE_API int	swmm_reaction_species_remove (SWMM_Engine engine, int idx)
	Remove species idx. Refused while any expression references it.
SWMM_ENGINE_API int	swmm_reaction_coeff_add (SWMM_Engine engine, const char *name, int is_param, double value)
	Add a coefficient (is_param: 1 PARAMETER, 0 CONSTANT).
SWMM_ENGINE_API int	swmm_reaction_coeff_set_value (SWMM_Engine engine, int idx, double value)
	Change a coefficient's value.
SWMM_ENGINE_API int	swmm_reaction_coeff_remove (SWMM_Engine engine, int idx)
	Remove coefficient idx. Refused while referenced.
SWMM_ENGINE_API int	swmm_reaction_term_add (SWMM_Engine engine, const char *name, const char *expr)
	Add an intermediate term (referencable by later terms only).
SWMM_ENGINE_API int	swmm_reaction_term_set_expr (SWMM_Engine engine, int idx, const char *expr)
	Replace term idx's expression.
SWMM_ENGINE_API int	swmm_reaction_term_remove (SWMM_Engine engine, int idx)
	Remove term idx. Refused while referenced.
SWMM_ENGINE_API int	swmm_reaction_expr_set (SWMM_Engine engine, int scope, int species_idx, int form, const char *expr)
	Set (or clear, with SWMM_RXN_FORM_NONE) a species' expression in one scope (PIPE or TANK).
SWMM_ENGINE_API int	swmm_reaction_option_set (SWMM_Engine engine, const char *key, const char *value)
	Set a [REACTION_OPTIONS] value from its canonical token.
SWMM_ENGINE_API int	swmm_reaction_init_global_get (SWMM_Engine engine, int species_idx, double *value)
SWMM_ENGINE_API int	swmm_reaction_init_global_set (SWMM_Engine engine, int species_idx, double value)
SWMM_ENGINE_API int	swmm_reaction_init_elem_count (SWMM_Engine engine)
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)
SWMM_ENGINE_API int	swmm_reaction_init_elem_set (SWMM_Engine engine, int is_link, int elem_idx, int species_idx, double value)
	Upsert on (is_link, elem_idx, species_idx). Value must be >= 0.
SWMM_ENGINE_API int	swmm_reaction_init_elem_remove (SWMM_Engine engine, int entry_idx)
SWMM_ENGINE_API int	swmm_reactions_serialize (SWMM_Engine engine, char *buf, int buflen, int *needed_len)
	Canonical .rxn text from engine state.
SWMM_ENGINE_API int	swmm_reactions_check_text (SWMM_Engine engine, const char *text, char *errbuf, int buflen)
	Dry-run full-file parse+compile of .rxn TEXT against this model. Zero state change, success or failure.
SWMM_ENGINE_API int	swmm_reactions_apply_text (SWMM_Engine engine, const char *text, char *errbuf, int buflen)
	Transactional replace of the whole reaction system from .rxn TEXT.
SWMM_ENGINE_API int	swmm_reactions_save (SWMM_Engine engine, const char *path_or_null)
	Serialize to the bound component config path (or path_or_null when given). SWMM_ERR_BADPARAM when neither names a path.
SWMM_ENGINE_API int	swmm_reaction_hydvar_count (void)
	Number of built-in hydraulic variables (D Q U RE US FF AV HRT DT TEMP).
SWMM_ENGINE_API int	swmm_reaction_hydvar_get (int idx, char *name, int name_len, char *description, int desc_len)
	Read one hydraulic variable's name and description.
SWMM_ENGINE_API int	swmm_reaction_function_count (void)
	Number of built-in functions (EXP … TAN arity 1; MIN MAX POW 2).
SWMM_ENGINE_API int	swmm_reaction_function_get (int idx, char *name, int name_len, int *arity)
	Read one function's name and 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\n 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_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 )

Add a coefficient (is_param: 1 PARAMETER, 0 CONSTANT).

Here is the call graph for this function:

swmm_reaction_coeff_count()

SWMM_ENGINE_API int swmm_reaction_coeff_count

(

SWMM_Engine

engine

)

Number of [REACTION_COEFFICIENTS] entries.

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 coefficient: name, PARAMETER(1)/CONSTANT(0), value.

swmm_reaction_coeff_remove()

SWMM_ENGINE_API int swmm_reaction_coeff_remove	(	SWMM_Engine	engine,
		int	idx )

Remove coefficient idx. Refused while referenced.

swmm_reaction_coeff_set_value()

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

Change a coefficient's value.

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' expression in one scope (PIPE or TANK).

Parameters

form	[out] SWMM_RXN_FORM_* (NONE when the species has none).

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, with SWMM_RXN_FORM_NONE) a species' expression in one scope (PIPE or TANK).

Here is the call graph for this function:

swmm_reaction_function_count()

SWMM_ENGINE_API int swmm_reaction_function_count

(

void

)

Number of built-in functions (EXP … TAN arity 1; MIN MAX POW 2).

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 )

Read one function's name and arity.

Here is the call graph for this function:

swmm_reaction_hydvar_count()

SWMM_ENGINE_API int swmm_reaction_hydvar_count

(

void

)

Number of built-in hydraulic variables (D Q U RE US FF AV HRT DT TEMP).

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 )

Read one hydraulic variable's name and description.

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

)

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 )

swmm_reaction_init_elem_remove()

SWMM_ENGINE_API int swmm_reaction_init_elem_remove	(	SWMM_Engine	engine,
		int	entry_idx )

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 on (is_link, elem_idx, species_idx). Value must be >= 0.

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 )

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 )

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 )

Read a [REACTION_OPTIONS] value as its canonical token.

Parameters

key	SOLVER, COUPLING, RATE_UNITS, AREA_UNITS, TIMESTEP, ATOL, RTOL, TEMPERATURE (degC fallback for the TEMP expression variable).

swmm_reaction_option_set()

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

Set a [REACTION_OPTIONS] value from its canonical token.

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 )

Declare a species (is_wall: 0 BULK, 1 WALL; atol/rtol 0 = global).

Here is the call graph for this function:

swmm_reaction_species_count()

SWMM_ENGINE_API int swmm_reaction_species_count

(

SWMM_Engine

engine

)

Number of declared MSX species (0 when no reactions configured).

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 species: name, BULK(0)/WALL(1), units, tolerances.

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 species idx. Refused while any expression references it.

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 )

Add an intermediate term (referencable by later terms only).

Here is the call graph for this function:

swmm_reaction_term_count()

SWMM_ENGINE_API int swmm_reaction_term_count

(

SWMM_Engine

engine

)

Number of [REACTION_TERMS] entries.

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 one term: name and its source expression.

swmm_reaction_term_remove()

SWMM_ENGINE_API int swmm_reaction_term_remove	(	SWMM_Engine	engine,
		int	idx )

Remove term idx. Refused while referenced.

swmm_reaction_term_set_expr()

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

Replace term idx's expression.

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-only validation of a reaction expression against the model's live vocabulary (species, coefficients, terms, pollutants, hydraulic variables). No state change.

Scope selects the identifier-resolution vocabulary. For SWMM_RXN_SCOPE_TERM, references to ALL terms are accepted — the forward-only ordering rule stays enforced at file-apply time, where ordinal position exists (D-RC1): validation answers "is this well-formed against the vocabulary," not "is the file orderable."

Parameters

engine	Engine handle.
scope	SWMM_RXN_SCOPE_*.
expr	Expression text.
errbuf	[out, optional] Diagnostic (NUL-terminated).
buflen	Size of errbuf in bytes.
col_out	[out, optional] 1-based error column; -1 when not attributable.

Returns

SWMM_OK if the expression compiles; SWMM_ERR_BADPARAM otherwise.

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 )

Transactional replace of the whole reaction system from .rxn TEXT.

BUILDING/OPENED only. Staged: on ANY error the previous system — reaction state and registry block — is byte-identical to before the call (today's clear-on-error is fine at open where there is nothing to lose; on a live model it would be destructive).

swmm_reactions_check_text()

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

Dry-run full-file parse+compile of .rxn TEXT against this model. Zero state change, success or failure.

Returns

SWMM_OK when the text would apply; SWMM_ERR_BADPARAM with the first diagnostic in errbuf otherwise.

swmm_reactions_save()

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

Serialize to the bound component config path (or path_or_null when given). SWMM_ERR_BADPARAM when neither names a path.

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 )

Canonical .rxn text from engine state.

Parameters

buf	Caller buffer (may be NULL to size).
buflen	Size of buf in bytes.
needed_len	[out] Required size INCLUDING the NUL — always set.

Returns

SWMM_OK when written; SWMM_ERR_BADPARAM when buf is too small (needed_len still tells the caller how much to allocate).

Here is the call graph for this function: