openswmm_initial_quality.h File Reference

C API — [INITIAL_QUALITY] per-element initial concentrations (E-A4). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_initial_quality.h:

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

Go to the source code of this file.

Functions
SWMM_ENGINE_API int	swmm_init_quality_count (SWMM_Engine engine)
	Count stored per-element initial-quality rows.
SWMM_ENGINE_API int	swmm_init_quality_get (SWMM_Engine engine, int entry_idx, int *is_link, int *elem_idx, char *constituent_buf, int constituent_len, double *value)
	Read a stored initial-quality row without applying it.
SWMM_ENGINE_API int	swmm_init_quality_set (SWMM_Engine engine, int is_link, int elem_idx, const char *constituent, double value)
	Upsert initial concentration/age/temperature by element and resolved constituent.
SWMM_ENGINE_API int	swmm_init_quality_remove (SWMM_Engine engine, int entry_idx)
	Remove an initial-quality row and shift later indices down.
SWMM_ENGINE_API int	swmm_init_quality_file_get (SWMM_Engine engine, char *buf, int buflen)
	Copy the authored initial-quality sidecar path token.
SWMM_ENGINE_API int	swmm_init_quality_file_set (SWMM_Engine engine, const char *path)
	Set or clear the authored initial-quality sidecar reference.
SWMM_ENGINE_API int	swmm_init_quality_is_file (SWMM_Engine engine, int entry_idx)
	Read whether an initial-quality row originated in a sidecar.

Detailed Description

C API — [INITIAL_QUALITY] per-element initial concentrations (E-A4).

Row-based surface over the section store, mirroring the swmm_ext_inflow_* family: entries are indexed 0..count-1 in file order, set is an UPSERT keyed on (is_link, elem_idx, constituent), and remove deletes by entry index (subsequent entries shift down by one).

Constituent is a name: a [POLLUTANTS] pollutant, a configured reaction species, or the reserved species "__WATER_AGE__" (value in HOURS, signed) or "__TEMPERATURE__" (value in degC). Pollutant values are concentrations in the pollutant's own units and must be non-negative.

Rows only seed state at initialize(), so mutation is guarded to the editable states (BUILDING/OPENED) — the same contract as swmm_pollutant_set_init_conc.

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

Function Documentation

swmm_init_quality_count()

SWMM_ENGINE_API int swmm_init_quality_count

(

SWMM_Engine

engine

)

Count stored per-element initial-quality rows.

Parameters

[in]

engine

Non-null live engine handle; exclusive access is required.

Returns

Nonnegative row count, or -1 for null engine.

swmm_init_quality_file_get()

SWMM_ENGINE_API int swmm_init_quality_file_get	(	SWMM_Engine	engine,
		char *	buf,
		int	buflen )

Copy the authored initial-quality sidecar path token.

Returns the authored reference rather than resolving or reading the sidecar.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[out]	buf	Non-null caller-owned buffer; empty when absent, NUL-terminated and silently truncated to buflen-1 bytes.
[in]	buflen	Positive capacity in bytes including NUL.

Returns

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

swmm_init_quality_file_set()

SWMM_ENGINE_API int swmm_init_quality_file_set	(	SWMM_Engine	engine,
		const char *	path )

Set or clear the authored initial-quality sidecar reference.

Does not load, clear or rewrite existing rows immediately; the sidecar is read on the next model open. Sidecar-origin rows retain their provenance for serialization.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[in]	path	Borrowed NUL-terminated path token to copy; NULL/empty clears the reference.

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_LIFECYCLE outside BUILDING/OPENED.

swmm_init_quality_get()

SWMM_ENGINE_API int swmm_init_quality_get	(	SWMM_Engine	engine,
		int	entry_idx,
		int *	is_link,
		int *	elem_idx,
		char *	constituent_buf,
		int	constituent_len,
		double *	value )

Read a stored initial-quality row without applying it.

Validates all output pointers/capacity before copying. Does not validate whether a stored unresolved row can initialize the current model.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[in]	entry_idx	Zero-based row index in [0,swmm_init_quality_count(engine)).
[out]	is_link	Non-null destination: 0=node, 1=link.
[out]	elem_idx	Non-null destination for the resolved element index, or -1 when unresolved.
[out]	constituent_buf	Non-null caller-owned constituent buffer; NUL-terminated and silently truncated to constituent_len-1 bytes.
[in]	constituent_len	Positive constituent-buffer byte capacity including NUL.
[out]	value	Non-null raw-value destination: pollutant/species concentration units, age hours or temperature degrees C.

Returns

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

Here is the call graph for this function:

swmm_init_quality_is_file()

SWMM_ENGINE_API int swmm_init_quality_is_file	(	SWMM_Engine	engine,
		int	entry_idx )

Read whether an initial-quality row originated in a sidecar.

This Boolean query does not return BADHANDLE/BADINDEX error codes; 0 is not proof that an arbitrary index exists.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[in]	entry_idx	Zero-based row index in [0,swmm_init_quality_count(engine)).

Returns

1 for a sidecar-origin row, 0 for an inline row, null engine, invalid index or absent provenance flag.

swmm_init_quality_remove()

SWMM_ENGINE_API int swmm_init_quality_remove	(	SWMM_Engine	engine,
		int	entry_idx )

Remove an initial-quality row and shift later indices down.

Removes the corresponding reaction seed entry when applicable; does not remove or change the global default concentration.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[in]	entry_idx	Zero-based row index in [0,swmm_init_quality_count(engine)).

Returns

SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_LIFECYCLE outside BUILDING/OPENED, or SWMM_ERR_BADINDEX for an invalid row.

Here is the call graph for this function:

swmm_init_quality_set()

SWMM_ENGINE_API int swmm_init_quality_set	(	SWMM_Engine	engine,
		int	is_link,
		int	elem_idx,
		const char *	constituent,
		double	value )

Upsert initial concentration/age/temperature by element and resolved constituent.

Rows seed state during initialization; this does not alter running concentrations. Existing rows match resolved constituent kind, not just text spelling; updates keep row order. Reaction-species entries also mirror into the engine reaction seed tables. Does not enable age, heat or reaction transport automatically.

Parameters

[in]	engine	Non-null live engine handle; exclusive access is required.
[in]	is_link	0 selects node; any nonzero value selects link.
[in]	elem_idx	Zero-based existing index within the selected element table.
[in]	constituent	Non-null copied constituent name: a known pollutant, configured reaction species, or exact reserved WATER_AGE/__TEMPERATURE__ token.
[in]	value	Pollutant/reaction-species concentration in its row units (negative refused), reserved age in signed hours or temperature in degrees C. No separate finite-value guard is applied.

Returns

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

Here is the call graph for this function: