openswmm_transport_impl.cpp File Reference

E6 — ARD transport configuration surface. See the header for the read-only-rows decision and its reason. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_transport.h"
#include "../transport/components/EulerianArdComponent/ArdConfig.hpp"
#include <cmath>
#include <cstring>
#include <utility>
#include <string>
#include <vector>

Include dependency graph for openswmm_transport_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_transport_get_configured (SWMM_Engine engine, int *configured)
	Read whether an ARD transport component is authored.
SWMM_ENGINE_API int	swmm_transport_get_dispersion_mode (SWMM_Engine engine, int *mode)
	Read the global longitudinal-dispersion mode.
SWMM_ENGINE_API int	swmm_transport_set_dispersion_mode (SWMM_Engine engine, int mode)
	Assign the global dispersion mode and mark transport configuration present.
SWMM_ENGINE_API int	swmm_transport_get_dispersion_value (SWMM_Engine engine, double *value)
	Read the fixed dispersion coefficient.
SWMM_ENGINE_API int	swmm_transport_set_dispersion_value (SWMM_Engine engine, double value)
	Assign the fixed dispersion coefficient and mark transport configuration present.
SWMM_ENGINE_API int	swmm_transport_get_target_dx (SWMM_Engine engine, double *dx)
	Read the requested transport-cell spacing.
SWMM_ENGINE_API int	swmm_transport_set_target_dx (SWMM_Engine engine, double dx)
	Assign the requested transport-cell spacing and mark transport configuration present.
SWMM_ENGINE_API int	swmm_transport_conduit_disp_count (SWMM_Engine engine, int *count)
	Count authored per-conduit dispersion override rows.
SWMM_ENGINE_API int	swmm_transport_get_conduit_disp (SWMM_Engine engine, int index, int *link_index, double *value)
	Read one authored conduit-dispersion override.
SWMM_ENGINE_API int	swmm_transport_boundary_count (SWMM_Engine engine, int *count)
	Count authored transport boundary rows.
SWMM_ENGINE_API int	swmm_transport_get_boundary (SWMM_Engine engine, int index, char *element, int elem_len, char *species, int spec_len, int *is_ts, double *value, char *ts_name, int ts_len)
	Copy an authored transport boundary row with optional output fields.
SWMM_ENGINE_API int	swmm_transport_source_count (SWMM_Engine engine, int *count)
	Count authored transport source rows.
SWMM_ENGINE_API int	swmm_transport_get_source (SWMM_Engine engine, int index, char *element, int elem_len, char *species, int spec_len, int *is_ts, double *value, char *ts_name, int ts_len)
	Copy an authored transport source row with optional output fields.
SWMM_ENGINE_API int	swmm_transport_get_detailed_output (SWMM_Engine engine, char *buf, int buflen)
	Read the configured detailed transport CSV sidecar path.
SWMM_ENGINE_API int	swmm_transport_set_detailed_output (SWMM_Engine engine, const char *path)
	Store a detailed transport CSV sidecar path and mark configuration present.
SWMM_ENGINE_API int	swmm_transport_set_conduit_disp (SWMM_Engine engine, int link_index, double value)
	Add or replace the dispersion coefficient for one conduit.
SWMM_ENGINE_API int	swmm_transport_remove_conduit_disp (SWMM_Engine engine, int index)
	Remove an authored conduit dispersion row by index.
SWMM_ENGINE_API int	swmm_transport_set_boundary (SWMM_Engine engine, const char *element, const char *species, int is_ts, double value, const char *ts_name)
	Upsert a transport boundary keyed by element and species names.
SWMM_ENGINE_API int	swmm_transport_remove_boundary (SWMM_Engine engine, int index)
	Remove an authored boundary row by index.
SWMM_ENGINE_API int	swmm_transport_set_source (SWMM_Engine engine, const char *element, const char *species, int is_ts, double value, const char *ts_name)
	Upsert a transport source keyed by element and species names.
SWMM_ENGINE_API int	swmm_transport_remove_source (SWMM_Engine engine, int index)
	Remove an authored source row by index.

Detailed Description

E6 — ARD transport configuration surface. See the header for the read-only-rows decision and its reason.

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_transport_boundary_count()

SWMM_ENGINE_API int swmm_transport_boundary_count	(	SWMM_Engine	engine,
		int *	count )

Count authored transport boundary rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned nonnegative row count.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Counts raw configuration rows, including rows awaiting BUILDING-state resolution.

swmm_transport_conduit_disp_count()

SWMM_ENGINE_API int swmm_transport_conduit_disp_count	(	SWMM_Engine	engine,
		int *	count )

Count authored per-conduit dispersion override rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned nonnegative row count.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Counts raw configuration rows, including rows awaiting BUILDING-state resolution.

swmm_transport_get_boundary()

SWMM_ENGINE_API int swmm_transport_get_boundary	(	SWMM_Engine	engine,
		int	index,
		char *	element,
		int	elem_len,
		char *	species,
		int	spec_len,
		int *	is_ts,
		double *	value,
		char *	ts_name,
		int	ts_len )

Copy an authored transport boundary row with optional output fields.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based raw row index, below its count function.
[out]	element	Optional writable node-name buffer; NULL skips copying.
[in]	elem_len	Element-buffer byte capacity; <= 0 skips copying, positive capacity truncates safely to len - 1 bytes and appends NUL.
[out]	species	Optional species-name buffer.
[in]	spec_len	Species-buffer byte capacity; same skip/truncation convention.
[out]	is_ts	Optional slot: 1 time-series mode, 0 constant-value mode.
[out]	value	Optional constant field in species concentration units.
[out]	ts_name	Optional time-series-name buffer; empty for constant mode.
[in]	ts_len	Series-buffer byte capacity; same skip/truncation convention.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE or SWMM_ERR_BADINDEX.

Note

All output pointers may be NULL. Names/values are raw authored fields, not sampled series values; no storage is retained.

swmm_transport_get_conduit_disp()

SWMM_ENGINE_API int swmm_transport_get_conduit_disp	(	SWMM_Engine	engine,
		int	index,
		int *	link_index,
		double *	value )

Read one authored conduit-dispersion override.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based override row index, below swmm_transport_conduit_disp_count().
[out]	link_index	Optional output slot for the global link index; NULL skips it.
[out]	value	Optional output slot for the authored ft2/s or m2/s coefficient.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE or SWMM_ERR_BADINDEX for an invalid row.

Note

Both output pointers may be NULL; no storage is retained.

swmm_transport_get_configured()

SWMM_ENGINE_API int swmm_transport_get_configured	(	SWMM_Engine	engine,
		int *	configured )

Read whether an ARD transport component is authored.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	configured	Non-null caller-owned slot for 0 absent or 1 configured.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Reads authored configuration; no transport runtime is advanced.

swmm_transport_get_detailed_output()

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

Read the configured detailed transport CSV sidecar path.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	buf	Non-null writable string buffer; empty when detailed output is disabled.
[in]	buflen	Positive byte capacity including terminator; long paths are safely truncated.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Returns stored text without resolving or opening the destination.

swmm_transport_get_dispersion_mode()

SWMM_ENGINE_API int swmm_transport_get_dispersion_mode	(	SWMM_Engine	engine,
		int *	mode )

Read the global longitudinal-dispersion mode.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	mode	Non-null caller-owned slot for SWMM_TransportDispersionMode value.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Reads authored configuration; no transport runtime is advanced.

swmm_transport_get_dispersion_value()

SWMM_ENGINE_API int swmm_transport_get_dispersion_value	(	SWMM_Engine	engine,
		double *	value )

Read the fixed dispersion coefficient.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	value	Non-null caller-owned slot for authored ft2/s or m2/s, not converted by this getter.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Reads authored configuration; no transport runtime is advanced.

swmm_transport_get_source()

SWMM_ENGINE_API int swmm_transport_get_source	(	SWMM_Engine	engine,
		int	index,
		char *	element,
		int	elem_len,
		char *	species,
		int	spec_len,
		int *	is_ts,
		double *	value,
		char *	ts_name,
		int	ts_len )

Copy an authored transport source row with optional output fields.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based raw row index, below its count function.
[out]	element	Optional writable conduit-name buffer; NULL skips copying.
[in]	elem_len	Element-buffer byte capacity; <= 0 skips copying, positive capacity truncates safely to len - 1 bytes and appends NUL.
[out]	species	Optional species-name buffer.
[in]	spec_len	Species-buffer byte capacity; same skip/truncation convention.
[out]	is_ts	Optional slot: 1 time-series mode, 0 constant-value mode.
[out]	value	Optional constant field in species-native mass units per second; negative values represent extraction.
[out]	ts_name	Optional time-series-name buffer; empty for constant mode.
[in]	ts_len	Series-buffer byte capacity; same skip/truncation convention.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE or SWMM_ERR_BADINDEX.

Note

All output pointers may be NULL. Names/values are raw authored fields, not sampled series values; no storage is retained.

swmm_transport_get_target_dx()

SWMM_ENGINE_API int swmm_transport_get_target_dx	(	SWMM_Engine	engine,
		double *	dx )

Read the requested transport-cell spacing.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	dx	Non-null caller-owned slot for authored feet or meters; zero selects the engine default.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Reads authored configuration; no transport runtime is advanced.

swmm_transport_remove_boundary()

SWMM_ENGINE_API int swmm_transport_remove_boundary	(	SWMM_Engine	engine,
		int	index )

Remove an authored boundary row by index.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; removing a row shifts later indices.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Boundary/source resolution is rerun outside BUILDING; a failed resolution restores the previous configuration and returns SWMM_ERR_BADPARAM.

swmm_transport_remove_conduit_disp()

SWMM_ENGINE_API int swmm_transport_remove_conduit_disp	(	SWMM_Engine	engine,
		int	index )

Remove an authored conduit dispersion row by index.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; removing a row shifts later indices.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Does not clear the component configured flag when the final override is removed.

swmm_transport_remove_source()

SWMM_ENGINE_API int swmm_transport_remove_source	(	SWMM_Engine	engine,
		int	index )

Remove an authored source row by index.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based current row index; removing a row shifts later indices.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Boundary/source resolution is rerun outside BUILDING; a failed resolution restores the previous configuration and returns SWMM_ERR_BADPARAM.

swmm_transport_set_boundary()

SWMM_ENGINE_API int swmm_transport_set_boundary	(	SWMM_Engine	engine,
		const char *	element,
		const char *	species,
		int	is_ts,
		double	value,
		const char *	ts_name )

Upsert a transport boundary keyed by element and species names.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	element	Non-null nonempty node name, copied into the row.
[in]	species	Non-null nonempty reactions-component species name.
[in]	is_ts	Exactly 0 for a constant or 1 for a named time series.
[in]	value	Finite nonnegative concentration in species units when is_ts is zero; ignored and stored as zero otherwise.
[in]	ts_name	Nonempty existing time-series name when is_ts == 1; may be NULL for constant mode and is then stored as empty text.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM for invalid data or failed name resolution, or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

BUILDING keeps unresolved rows so referenced objects can be declared later. OPENED reruns row resolution and restores the prior configuration on failure. Successful edits mark the component configured.

swmm_transport_set_conduit_disp()

SWMM_ENGINE_API int swmm_transport_set_conduit_disp	(	SWMM_Engine	engine,
		int	link_index,
		double	value )

Add or replace the dispersion coefficient for one conduit.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	link_index	Valid global link index identifying a conduit; structures are refused.
[in]	value	Finite nonnegative coefficient in authored ft2/s or m2/s.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADINDEX, SWMM_ERR_BADPARAM for a nonconduit/invalid coefficient, or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Marks transport configuration present; replacement keeps the existing row position.

Here is the call graph for this function:

swmm_transport_set_detailed_output()

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

Store a detailed transport CSV sidecar path and mark configuration present.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	path	Null-terminated path to copy; NULL or empty disables the sidecar.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

Relative API-authored paths are resolved against the process working directory when output is written; component-file parsing resolves paths against its own directory. This call does not open the file.

swmm_transport_set_dispersion_mode()

SWMM_ENGINE_API int swmm_transport_set_dispersion_mode	(	SWMM_Engine	engine,
		int	mode )

Assign the global dispersion mode and mark transport configuration present.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	mode	SWMM_DISPERSION_OFF, SWMM_DISPERSION_FISCHER or SWMM_DISPERSION_VALUE; VALUE preserves the previous coefficient.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

This option setter performs no editable-state check. It changes stored configuration and does not promise to rebuild an initialized transport kernel.

swmm_transport_set_dispersion_value()

SWMM_ENGINE_API int swmm_transport_set_dispersion_value	(	SWMM_Engine	engine,
		double	value )

Assign the fixed dispersion coefficient and mark transport configuration present.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	value	Finite nonnegative authored coefficient in ft2/s or m2/s.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

This option setter performs no editable-state check. It changes stored configuration and does not promise to rebuild an initialized transport kernel.

swmm_transport_set_source()

SWMM_ENGINE_API int swmm_transport_set_source	(	SWMM_Engine	engine,
		const char *	element,
		const char *	species,
		int	is_ts,
		double	value,
		const char *	ts_name )

Upsert a transport source keyed by element and species names.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	element	Non-null nonempty conduit name, copied into the row.
[in]	species	Non-null nonempty reactions-component species name.
[in]	is_ts	Exactly 0 for a constant or 1 for a named time series.
[in]	value	Finite rate in species-native mass units/s; negative is extraction when is_ts is zero; ignored and stored as zero otherwise.
[in]	ts_name	Nonempty existing time-series name when is_ts == 1; may be NULL for constant mode and is then stored as empty text.

Returns

SWMM_OK, SWMM_ERR_BADHANDLE, SWMM_ERR_BADPARAM for invalid data or failed name resolution, or SWMM_ERR_LIFECYCLE.

Note

Requires an editable BUILDING or OPENED model; later states return SWMM_ERR_LIFECYCLE. Input data is copied and no input storage is retained.

BUILDING keeps unresolved rows so referenced objects can be declared later. OPENED reruns row resolution and restores the prior configuration on failure. Successful edits mark the component configured.

swmm_transport_set_target_dx()

SWMM_ENGINE_API int swmm_transport_set_target_dx	(	SWMM_Engine	engine,
		double	dx )

Assign the requested transport-cell spacing and mark transport configuration present.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	dx	Finite nonnegative authored length in feet/meters; zero restores the engine default.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

This option setter performs no editable-state check. It changes stored configuration and does not promise to rebuild an initialized transport kernel.

swmm_transport_source_count()

SWMM_ENGINE_API int swmm_transport_source_count	(	SWMM_Engine	engine,
		int *	count )

Count authored transport source rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Non-null caller-owned nonnegative row count.

Returns

SWMM_OK on success, SWMM_ERR_BADHANDLE for an invalid handle, or SWMM_ERR_BADPARAM for invalid arguments. Output storage is caller-owned.

Note

Counts raw configuration rows, including rows awaiting BUILDING-state resolution.