E6 — the ARD transport configuration surface ([TRANSPORT_OPTIONS], [TRANSPORT_BOUNDARIES], [TRANSPORT_SOURCES]). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_transport.h:

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

Go to the source code of this file.

Typedefs
typedef enum SWMM_TransportDispersionMode	SWMM_TransportDispersionMode
	`[TRANSPORT_OPTIONS] DISPERSION` mode.

Enumerations
enum	SWMM_TransportDispersionMode { SWMM_DISPERSION_OFF = 0 , SWMM_DISPERSION_FISCHER = 1 , SWMM_DISPERSION_VALUE = 2 }
	`[TRANSPORT_OPTIONS] DISPERSION` mode. More...

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 — the ARD transport configuration surface ([TRANSPORT_OPTIONS], [TRANSPORT_BOUNDARIES], [TRANSPORT_SOURCES]).

The last quality subsystem with no C API of its own: heat, reactions, water age and the pollutant tables all have theirs, and G7g (the dispersion/boundary property editors) was gated on this header existing. Follows openswmm_water_age.h's conventions: values cross the boundary in the CONFIG FILE'S units, the engine's internal units stay internal, and setters mark the config configured so a save renders it.

Boundary/source authoring calls require BUILDING or OPENED. During BUILDING references may remain unresolved; OPENED edits resolve names immediately and restore the prior configuration on failure. The original dispersion/spacing option setters predate these lifecycle checks; each function documents its actual restriction.

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

Typedef Documentation

◆ SWMM_TransportDispersionMode

typedef enum SWMM_TransportDispersionMode SWMM_TransportDispersionMode

[TRANSPORT_OPTIONS] DISPERSION mode.

Enumeration Type Documentation

◆ SWMM_TransportDispersionMode

enum SWMM_TransportDispersionMode

[TRANSPORT_OPTIONS] DISPERSION mode.

Enumerator
SWMM_DISPERSION_OFF	No global dispersion (per-conduit overrides still apply).
SWMM_DISPERSION_FISCHER	Fischer et al. (1979) closure from the local hydraulics.
SWMM_DISPERSION_VALUE	One user coefficient, display len²/s.

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.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_TransportDispersionMode

Enumeration Type Documentation

◆ SWMM_TransportDispersionMode

Function Documentation

◆ swmm_transport_boundary_count()

◆ swmm_transport_conduit_disp_count()

◆ swmm_transport_get_boundary()

◆ swmm_transport_get_conduit_disp()

◆ swmm_transport_get_configured()

◆ swmm_transport_get_detailed_output()

◆ swmm_transport_get_dispersion_mode()

◆ swmm_transport_get_dispersion_value()

◆ swmm_transport_get_source()

◆ swmm_transport_get_target_dx()

◆ swmm_transport_remove_boundary()

◆ swmm_transport_remove_conduit_disp()

◆ swmm_transport_remove_source()

◆ swmm_transport_set_boundary()

◆ swmm_transport_set_conduit_disp()

◆ swmm_transport_set_detailed_output()

◆ swmm_transport_set_dispersion_mode()

◆ swmm_transport_set_dispersion_value()

◆ swmm_transport_set_source()

◆ swmm_transport_set_target_dx()

◆ swmm_transport_source_count()