Water-age source-table CRUD implementation (subplan X5). More...

#include "openswmm_api_common.hpp"
#include "core/FileIO.hpp"
#include "../../../include/openswmm/engine/openswmm_water_age.h"
#include "../transport/components/WaterAgeModule/WaterAgeComponent.hpp"
#include <cstdio>
#include <string>

Include dependency graph for openswmm_water_age_impl.cpp:

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 implementation (subplan X5).

Values cross the boundary in HOURS (the config file's unit); the engine stores SECONDS. Negative values are legal and pass straight through — a negative source age extracts age-volume (D-NS1), clamped at consumption by the engines. There is no ucf conversion here: hours are hours in every unit system.

See also: include/openswmm/engine/openswmm_water_age.h

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_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.

Functions

Detailed Description

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