Water-age source-table CRUD (subplan X5 = water-age plan A6, the minimal GUI-facing subset; TRANSPORT_QUALITY_GUI_PLAN §6 prereq 5). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_water_age.h:

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

Go to the source code of this file.

Typedefs
typedef enum SWMM_WaterAgeSource	SWMM_WaterAgeSource
	Source pathways (mirrors the engine's WaterAgeSource order — the values are the storage indices, do not renumber).

Enumerations
enum	SWMM_WaterAgeSource { SWMM_AGE_SRC_RAINFALL = 0 , SWMM_AGE_SRC_DWF = 1 , SWMM_AGE_SRC_GW = 2 , SWMM_AGE_SRC_RDII = 3 , SWMM_AGE_SRC_EXTERNAL_INFLOW = 4 , SWMM_AGE_SRC_IFACE = 5 , SWMM_AGE_SRC_INITIAL_STATE = 6 , SWMM_AGE_SRC_COUNT = 7 }
	Source pathways (mirrors the engine's WaterAgeSource order — the values are the storage indices, do not renumber). More...

Functions
SWMM_ENGINE_API int	swmm_water_age_get_enabled (SWMM_Engine engine, int *enabled)
	Read the model WATER_AGE option without changing it.

SWMM_ENGINE_API int	swmm_water_age_get_global_source (SWMM_Engine engine, int source, double *hours)
	Read one global pathway source age in hours.

SWMM_ENGINE_API int	swmm_water_age_set_global_source (SWMM_Engine engine, int source, double hours)
	Assign a global pathway source age in hours.

SWMM_ENGINE_API int	swmm_water_age_override_count (SWMM_Engine engine, int *count)
	Count stored per-node source-age override rows.

SWMM_ENGINE_API int	swmm_water_age_get_override (SWMM_Engine engine, int index, int source, int node_index, double *hours)
	Read a per-node source-age override by row index.

SWMM_ENGINE_API int	swmm_water_age_set_override (SWMM_Engine engine, int source, int node_index, double hours)
	Insert or update a source/node age override.

SWMM_ENGINE_API int	swmm_water_age_remove_override (SWMM_Engine engine, int source, int node_index)
	Remove one source/node override and shift later row indices down.

SWMM_ENGINE_API int	swmm_water_age_save (SWMM_Engine engine, const char *path)
	Serialize the current source-age table to a component file.

Detailed Description

Water-age source-table CRUD (subplan X5 = water-age plan A6, the minimal GUI-facing subset; TRANSPORT_QUALITY_GUI_PLAN §6 prereq 5).

The [WATER_AGE_SOURCES] configuration (waterage component, model.age) as a keyed table: a GLOBAL age per source pathway, plus per-NODE overrides for the DWF and EXTERNAL_INFLOW pathways (the A1a scope rule — other pathways refuse NODE scope, exactly like the parser). Values are HOURS, the config file's unit; negative values are legal — a negative source age EXTRACTS age-volume, clamped so age never goes below zero (D-NS1, subplan §3.1). Edits mutate live engine state (the loaders re-read the table every step, so mid-simulation edits take effect on the next routing step); swmm_water_age_save persists the table to a component file.

The full A6 surface (Python/MCP bindings, node/link age state getters) is deferred — this header is exactly what the GUI's Water Age Sources editor (G3g) binds to.

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_WaterAgeSource

typedef enum SWMM_WaterAgeSource SWMM_WaterAgeSource

Source pathways (mirrors the engine's WaterAgeSource order — the values are the storage indices, do not renumber).

Enumeration Type Documentation

◆ SWMM_WaterAgeSource

enum SWMM_WaterAgeSource

Source pathways (mirrors the engine's WaterAgeSource order — the values are the storage indices, do not renumber).

Enumerator
SWMM_AGE_SRC_RAINFALL
SWMM_AGE_SRC_DWF
SWMM_AGE_SRC_GW
SWMM_AGE_SRC_RDII
SWMM_AGE_SRC_EXTERNAL_INFLOW
SWMM_AGE_SRC_IFACE
SWMM_AGE_SRC_INITIAL_STATE
SWMM_AGE_SRC_COUNT

Function Documentation

◆ swmm_water_age_get_enabled()

SWMM_ENGINE_API int swmm_water_age_get_enabled	(	SWMM_Engine	engine,
		int *	enabled )

Read the model WATER_AGE option without changing it.

Reports configuration, not whether every transport domain has initialized age storage.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[out]	enabled	Non-null destination: 1 when configured ON, otherwise 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null output.

◆ swmm_water_age_get_global_source()

SWMM_ENGINE_API int swmm_water_age_get_global_source	(	SWMM_Engine	engine,
		int	source,
		double *	hours )

Read one global pathway source age in hours.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	source	SWMM_WaterAgeSource in [SWMM_AGE_SRC_RAINFALL,SWMM_AGE_SRC_COUNT); invalid source codes return BADINDEX.
[out]	hours	Non-null destination for the stored signed age in hours (internal seconds divided by 3600).

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null hours, or SWMM_ERR_BADINDEX for invalid source.

◆ swmm_water_age_get_override()

SWMM_ENGINE_API int swmm_water_age_get_override	(	SWMM_Engine	engine,
		int	index,
		int *	source,
		int *	node_index,
		double *	hours )

Read a per-node source-age override by row index.

All outputs may be NULL. Updating an existing key keeps its row position; removing a row shifts later indices down.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	index	Zero-based override index in [0,override count).
[out]	source	Optional destination for the SWMM_WaterAgeSource code.
[out]	node_index	Optional destination for the zero-based node index.
[out]	hours	Optional destination for signed source age in hours.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid row.

◆ swmm_water_age_override_count()

SWMM_ENGINE_API int swmm_water_age_override_count	(	SWMM_Engine	engine,
		int *	count )

Count stored per-node source-age override rows.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[out]	count	Non-null destination for the row count.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADPARAM for null count.

◆ swmm_water_age_remove_override()

SWMM_ENGINE_API int swmm_water_age_remove_override	(	SWMM_Engine	engine,
		int	source,
		int	node_index )

Remove one source/node override and shift later row indices down.

Not idempotent for missing rows. Retains the global pathway setting and configured flag.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	source	Source code used as part of the stored key; this call locates the pair without a separate scope check.
[in]	node_index	Node index used as the second stored key.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX when the key is absent.

◆ swmm_water_age_save()

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

Serialize the current source-age table to a component file.

Uses the component serializer with hours in the output and read-back precision. An unconfigured table still writes an empty [WATER_AGE_SOURCES] header. This wrapper does not inspect fwrite/fclose results, update component path authoring, or provide atomic publication.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	path	Non-null, nonempty NUL-terminated UTF-8 destination path; opened for text writing, truncating existing contents.

Returns: SWMM_OK after writing/closing; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADPARAM for null/empty path, or SWMM_ERR_IO when the destination cannot be opened.

Here is the call graph for this function:

◆ swmm_water_age_set_global_source()

SWMM_ENGINE_API int swmm_water_age_set_global_source	(	SWMM_Engine	engine,
		int	source,
		double	hours )

Assign a global pathway source age in hours.

Marks the source configuration present but does not turn WATER_AGE on. Runtime loaders reread the table; negative extraction is clamped at consumption so available age-volume cannot become negative.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	source	SWMM_WaterAgeSource in [SWMM_AGE_SRC_RAINFALL,SWMM_AGE_SRC_COUNT); invalid source codes return BADINDEX.
[in]	hours	Signed source age in hours, converted to internal seconds. Negative values request age-volume extraction; caller must provide a finite value because this setter does not validate it.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine or SWMM_ERR_BADINDEX for invalid source.

◆ swmm_water_age_set_override()

SWMM_ENGINE_API int swmm_water_age_set_override	(	SWMM_Engine	engine,
		int	source,
		int	node_index,
		double	hours )

Insert or update a source/node age override.

Only SWMM_AGE_SRC_DWF and SWMM_AGE_SRC_EXTERNAL_INFLOW allow NODE scope. Existing (source,node) rows update in place; new keys append. Marks configuration present without enabling WATER_AGE; runtime changes are consumed on the next routing step.

Parameters

[in]	engine	Non-null live engine; caller provides exclusive access. Setters update the live source table without a lifecycle guard.
[in]	source	SWMM_WaterAgeSource in [SWMM_AGE_SRC_RAINFALL,SWMM_AGE_SRC_COUNT); invalid source codes return BADINDEX.
[in]	node_index	Zero-based existing node index; invalid indices return BADINDEX.
[in]	hours	Signed hours, converted to internal seconds without finite-value validation. Negative values extract available age-volume at consumption.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for null engine, SWMM_ERR_BADINDEX for invalid source/node, or SWMM_ERR_BADPARAM for a pathway that does not allow NODE scope.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_WaterAgeSource

Enumeration Type Documentation

◆ SWMM_WaterAgeSource

Function Documentation

◆ swmm_water_age_get_enabled()

◆ swmm_water_age_get_global_source()

◆ swmm_water_age_get_override()

◆ swmm_water_age_override_count()

◆ swmm_water_age_remove_override()

◆ swmm_water_age_save()

◆ swmm_water_age_set_global_source()

◆ swmm_water_age_set_override()