Heat-configuration C API (phase H6a). More...

#include "openswmm_api_common.hpp"
#include <cmath>
#include <charconv>
#include <array>
#include <optional>
#include <utility>
#include <string>
#include <vector>
#include "../../../include/openswmm/engine/openswmm_heat.h"
#include "../transport/components/HeatModule/HeatComponent.hpp"
#include "../transport/components/HeatFluxModules/HeatOverrides.hpp"

Include dependency graph for openswmm_heat_impl.cpp:

Functions
SWMM_ENGINE_API int	swmm_heat_get_enabled (SWMM_Engine engine, int *enabled)
	Is `[OPTIONS] HEAT_TRANSPORT` on?

SWMM_ENGINE_API int	swmm_heat_get_module (SWMM_Engine engine, int module, int *on)
	Read one `[HEAT_FLUXES]` module toggle.

SWMM_ENGINE_API int	swmm_heat_set_module (SWMM_Engine engine, int module, int on)
	Write one `[HEAT_FLUXES]` module toggle.

SWMM_ENGINE_API int	swmm_heat_get_radiative (SWMM_Engine engine, int param, double *value)
	Read one `[RADIATIVE_FLUXES]` parameter.

SWMM_ENGINE_API int	swmm_heat_set_radiative (SWMM_Engine engine, int param, double value)
	Write one `[RADIATIVE_FLUXES]` parameter.

SWMM_ENGINE_API int	swmm_heat_get_shortwave_mode (SWMM_Engine engine, int *mode)
	Read the incoming-shortwave mode (SWMM_HeatShortwaveMode).

SWMM_ENGINE_API int	swmm_heat_set_shortwave_mode (SWMM_Engine engine, int mode)
	Set the incoming-shortwave mode.

SWMM_ENGINE_API int	swmm_heat_set_shortwave_timeseries (SWMM_Engine engine, const char *name)
	Bind a `[TIMESERIES]` (by name) as the shortwave record and switch the mode to SWMM_HEAT_SW_TIMESERIES.

SWMM_ENGINE_API int	swmm_heat_get_shortwave_timeseries (SWMM_Engine engine, char *buf, int buflen)
	Name of the `[TIMESERIES]` bound as the shortwave record, or "" when none is bound. NUL-terminated, truncated to `buflen`.

SWMM_ENGINE_API int	swmm_heat_get_current_shortwave (SWMM_Engine engine, double *wm2)
	Resolved incoming shortwave at the CURRENT step, W/m², cloud already applied. Read-only: this is state, not configuration. 0 before the first step, and whenever radiative exchange is off.

SWMM_ENGINE_API int	swmm_heat_get_solar (SWMM_Engine engine, int param, double *value)
	Read one `[SOLAR_RADIATION]` parameter.

SWMM_ENGINE_API int	swmm_heat_set_solar (SWMM_Engine engine, int param, double value)
	Write one `[SOLAR_RADIATION]` parameter.

SWMM_ENGINE_API int	swmm_heat_get_solar_sited (SWMM_Engine engine, int *sited)
	Have latitude AND longitude both been explicitly set?

SWMM_ENGINE_API int	swmm_heat_get_cloud_configured (SWMM_Engine engine, int *configured)
	Is a `[CLOUD_COVER]` section in effect?

SWMM_ENGINE_API int	swmm_heat_get_cloud (SWMM_Engine engine, int param, double *value)
	Read one `[CLOUD_COVER]` parameter.

SWMM_ENGINE_API int	swmm_heat_set_cloud (SWMM_Engine engine, int param, double value)
	Write one `[CLOUD_COVER]` parameter. Writing any of them marks cloud cover as configured.

SWMM_ENGINE_API int	swmm_heat_set_cloud_timeseries (SWMM_Engine engine, const char *name)
	Bind a `[TIMESERIES]` (by name) as the cloud-fraction record.

SWMM_ENGINE_API int	swmm_heat_get_cloud_timeseries (SWMM_Engine engine, char *buf, int buflen)
	Name of the `[TIMESERIES]` bound as the cloud-fraction record, or "" when none is bound. NUL-terminated, truncated to `buflen`.

SWMM_ENGINE_API int	swmm_heat_clear_cloud (SWMM_Engine engine)
	Clear `[CLOUD_COVER]` entirely — back to clear sky.

SWMM_ENGINE_API int	swmm_heat_get_current_cloud (SWMM_Engine engine, double *fraction)
	Cloud fraction in effect at the CURRENT step, [0,1]. Read-only.

SWMM_ENGINE_API int	swmm_heat_source_count (SWMM_Engine engine, int *count)
	Number of sources the table carries (7). Never fails on a model with no heat configured — the table is a fixed enum extent, not a parsed list.

SWMM_ENGINE_API int	swmm_heat_get_source_temp (SWMM_Engine engine, int source, double *temp_c)
	Read one source's GLOBAL inlet temperature (°C).

SWMM_ENGINE_API int	swmm_heat_set_source_temp (SWMM_Engine engine, int source, double temp_c)
	Write one source's GLOBAL inlet temperature (°C).

SWMM_ENGINE_API int	swmm_heat_get_source_configured (SWMM_Engine engine, int source, int *configured)
	Did the model set this source explicitly, or is it taking the default? The editor needs the distinction to avoid writing rows a user never asked for.

SWMM_ENGINE_API int	swmm_heat_clear_source_temp (SWMM_Engine engine, int source)
	Return a source to the 20 °C default and mark it unconfigured, so the writer emits no row for it. NODE overrides are untouched — they are separate rows and removing them silently would delete model the caller did not name.

SWMM_ENGINE_API int	swmm_heat_node_override_count (SWMM_Engine engine, int *count)
	Number of NODE-scope override rows.

SWMM_ENGINE_API int	swmm_heat_get_node_override (SWMM_Engine engine, int index, int source, int node, double *temp_c)
	Read one NODE override by row index. Any out-pointer may be NULL.

SWMM_ENGINE_API int	swmm_heat_set_node_override (SWMM_Engine engine, int source, int node, double temp_c)
	Add or update the NODE override for (`source`, `node`).

SWMM_ENGINE_API int	swmm_heat_remove_node_override (SWMM_Engine engine, int index)
	Remove one NODE override by row index. Later rows shift down, so a caller iterating by index must re-read the count after removing.

SWMM_ENGINE_API int	swmm_heat_get_effective_source_temp (SWMM_Engine engine, int source, int node, double *temp_c)
	The temperature `source` water actually enters `node` at (°C) — the NODE override when one exists, else the GLOBAL value. This is `HeatConfigData::source_temp`, exposed so a caller reads the same resolution the engine uses rather than re-deriving the precedence and drifting from it.

SWMM_ENGINE_API int	swmm_heat_ground_source_configured (SWMM_Engine engine, int *configured)
	Exact authoring state for the new channel ground selector. Clear restores the absent/default PRESCRIBED choice; both operations are pre-run only.

SWMM_ENGINE_API int	swmm_heat_clear_ground_source (SWMM_Engine engine)
	Restore the absent/default prescribed channel ground-source choice.

SWMM_ENGINE_API int	swmm_heat_get_sediment (SWMM_Engine engine, int param, double *value)
	Read a `[SEDIMENT_EXCHANGE]` GLOBAL parameter.

SWMM_ENGINE_API int	swmm_heat_set_sediment (SWMM_Engine engine, int param, double value)
	Write a `[SEDIMENT_EXCHANGE]` GLOBAL parameter.

SWMM_ENGINE_API int	swmm_heat_get_sediment_ground_timeseries (SWMM_Engine engine, char *buf, int buflen)
	Ground-temperature timeseries name; empty when the constant spelling is in force.

SWMM_ENGINE_API int	swmm_heat_set_sediment_ground_timeseries (SWMM_Engine engine, const char *name)
	Drive the ground temperature from a `[TIMESERIES]`; NULL or "" returns to the constant value.

SWMM_ENGINE_API int	swmm_heat_element_override_count (SWMM_Engine engine, int *count)
	Number of per-element override rows (radiative and sediment).

SWMM_ENGINE_API int	swmm_heat_get_element_override (SWMM_Engine engine, int index, int attr, int scope, char name, int name_len, double value)
	Read one override row. Any out-pointer may be NULL.

SWMM_ENGINE_API int	swmm_heat_set_element_override (SWMM_Engine engine, int attr, int scope, const char *name, double value)
	Add or update the override for (`attr`, `scope`, `name`).

SWMM_ENGINE_API int	swmm_heat_remove_element_override (SWMM_Engine engine, int index)
	Remove one override row by index.

SWMM_ENGINE_API int	swmm_heat_get_effective_element (SWMM_Engine engine, int attr, int scope, const char name, double value, int source, char source_name, int source_name_len)
	Read the effective property for a named NODE, LINK or CELL2D. Source is GLOBAL=0, TAG=1, NODE=2, LINK=3, air temperature=4, ground series=5, CELL2D=6 or MESH_TAG=7. CELL2D names use one-based native cell IDs. Dynamic temperatures return NaN; source_name identifies the tag/series. This reports configuration precedence, independent of process activation.

SWMM_ENGINE_API int	swmm_hydrothermal_edit_atomic (SWMM_Engine engine, SWMM_HydrothermalEdit edit, void *user)
	Apply one synchronous hydrothermal configuration transaction with rollback.

SWMM_ENGINE_API int	swmm_heat_get_dry_policy (SWMM_Engine engine, int *policy)
	Dry policy: HOLD=0, AIR=1, DEFAULT=2.

SWMM_ENGINE_API int	swmm_heat_set_dry_policy (SWMM_Engine engine, int policy)
	Select the reported temperature policy for dry water elements.

SWMM_ENGINE_API int	swmm_heat_sediment_temperature_configured (SWMM_Engine engine, int param, int *configured)
	Authored status and reset for ground/initial bed temperature.

SWMM_ENGINE_API int	swmm_heat_clear_sediment_temperature (SWMM_Engine engine, int param)
	Reset one authored sediment temperature to inherited/default behavior.

SWMM_ENGINE_API int	swmm_heat_get_lid_material (SWMM_Engine engine, double values[4])
	Read-only LID material assumptions: water conductivity, soil conductivity, soil density, soil specific heat, all SI.

SWMM_ENGINE_API int	swmm_heat_clear_solar_site (SWMM_Engine engine)
	Remove explicit shared solar coordinates and their provenance.

SWMM_ENGINE_API SWMM_HeatSnapshot	swmm_heat_snapshot_create (SWMM_Engine engine)
	Allocate a reusable heat authoring snapshot for an editable engine.

SWMM_ENGINE_API int	swmm_heat_snapshot_restore (SWMM_Engine engine, SWMM_HeatSnapshot snapshot)
	Restore a reusable heat authoring snapshot to its original engine.

SWMM_ENGINE_API void	swmm_heat_snapshot_destroy (SWMM_HeatSnapshot snapshot)
	Release a heat authoring snapshot.

SWMM_ENGINE_API SWMM_ConfigSnapshot	swmm_config_snapshot_create (SWMM_Engine engine)
	Allocate a reusable complete hydrothermal authoring snapshot.

SWMM_ENGINE_API int	swmm_config_snapshot_restore (SWMM_Engine engine, SWMM_ConfigSnapshot opaque)
	Restore complete hydrothermal authoring configuration atomically.

SWMM_ENGINE_API void	swmm_config_snapshot_destroy (SWMM_ConfigSnapshot snapshot)
	Release a config authoring snapshot.

SWMM_ENGINE_API int	swmm_heat_get_authoring_flags (SWMM_Engine engine, unsigned *flags)
	Authoring provenance bits: configured=1, shared site=2, explicit latitude/longitude/timezone/elevation=4/8/16/32.

Detailed Description

Heat-configuration C API (phase H6a).

Every setter here enforces the SAME range rule the model.heat parser does, and enforces it the same way: refuse, do not clamp. Two entry points into one configuration that disagree about what is legal is how a deck and a GUI come to describe different models, and the parser's rule is the older one.

See also: include/openswmm/engine/openswmm_heat.h; plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §5

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

SWMM_ENGINE_API SWMM_ConfigSnapshot swmm_config_snapshot_create ( SWMM_Engine engine )

Allocate a reusable complete hydrothermal authoring snapshot.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Note: Requires BUILDING/OPENED. Caller owns the returned reusable snapshot and releases it exactly once using the matching destroy function. It captures configuration and selected caches, with no ownership of the engine or runtime state.

Returns: Newly allocated SWMM_ConfigSnapshot; NULL for a null handle, noneditable state, or any allocation/copy failure.

◆ swmm_config_snapshot_destroy()

SWMM_ENGINE_API void swmm_config_snapshot_destroy ( SWMM_ConfigSnapshot snapshot )

Release a config authoring snapshot.

Parameters

[in] snapshot Owned snapshot of the matching type; NULL is safe.

Note: May be called after the engine is closed. Invalid, foreign or previously freed snapshot pointers are unsupported. Does not close or destroy an engine.

◆ swmm_config_snapshot_restore()

SWMM_ENGINE_API int swmm_config_snapshot_restore	(	SWMM_Engine	engine,
		SWMM_ConfigSnapshot	snapshot )

Restore complete hydrothermal authoring configuration atomically.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	snapshot	Required live snapshot produced by swmm_config_snapshot_create() for this exact engine identity. The snapshot remains valid and reusable after restore.

Note: Caller must ensure the original engine is still live. Captured storage is copied before publication; this call does not consume the snapshot.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

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

Here is the call graph for this function:

◆ swmm_heat_clear_cloud()

SWMM_ENGINE_API int swmm_heat_clear_cloud ( SWMM_Engine engine )

Clear [CLOUD_COVER] entirely — back to clear sky.

Restores the exact H3 longwave path, not an approximation of it: the cloud factor becomes a literal 1.0 that atmosphericEmissivity short-circuits.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Note: Also clears current cloud and invalidates the resolved shortwave cache.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_clear_ground_source()

SWMM_ENGINE_API int swmm_heat_clear_ground_source ( SWMM_Engine engine )

Restore the absent/default prescribed channel ground-source choice.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Note: Restores absent/default PRESCRIBED selection and re-resolves overrides. Refused resolution restores the prior config; allocation failure returns SWMM_ERR_NOMEM and other exceptions return SWMM_ERR_INTERNAL.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

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

◆ swmm_heat_clear_sediment_temperature()

SWMM_ENGINE_API int swmm_heat_clear_sediment_temperature	(	SWMM_Engine	engine,
		int	param )

Reset one authored sediment temperature to inherited/default behavior.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HEAT_SED_GROUND_TEMPERATURE or SWMM_HEAT_SED_INITIAL_TEMPERATURE.

Note: Clearing initial temperature requires editable state when an enabled 2D bed model captures it at initialization; clearing ground temperature also removes its series.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_heat_clear_solar_site()

SWMM_ENGINE_API int swmm_heat_clear_solar_site ( SWMM_Engine engine )

Remove explicit shared solar coordinates and their provenance.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Note: Refused while COMPUTED shortwave is selected. Removes the shared site and explicit heat-coordinate flags without resetting numeric field values.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

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

◆ swmm_heat_clear_source_temp()

SWMM_ENGINE_API int swmm_heat_clear_source_temp	(	SWMM_Engine	engine,
		int	source )

Return a source to the 20 °C default and mark it unconfigured, so the writer emits no row for it. NODE overrides are untouched — they are separate rows and removing them silently would delete model the caller did not name.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	SWMM_HeatSourceKind code, in [0,6].

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_element_override_count()

SWMM_ENGINE_API int swmm_heat_element_override_count	(	SWMM_Engine	engine,
		int *	count )

Number of per-element override rows (radiative and sediment).

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current override-row count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_authoring_flags()

SWMM_ENGINE_API int swmm_heat_get_authoring_flags	(	SWMM_Engine	engine,
		unsigned *	flags )

Authoring provenance bits: configured=1, shared site=2, explicit latitude/longitude/timezone/elevation=4/8/16/32.

Exact pre-run memento for heat settings, 2D heat/GW/aquifer authoring, their shared site and component registrations. Callers must check their authoring identity before Undo. It owns no engine; the caller must ensure the original engine is still open before restoring. Destroy is safe after closing the engine.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	flags	Required result destination: bitwise provenance flags listed above.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_cloud()

SWMM_ENGINE_API int swmm_heat_get_cloud	(	SWMM_Engine	engine,
		int	param,
		double *	value )

Read one [CLOUD_COVER] parameter.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatCloudParam selector.
[out]	value	Required destination; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_cloud_configured()

SWMM_ENGINE_API int swmm_heat_get_cloud_configured	(	SWMM_Engine	engine,
		int *	configured )

Is a [CLOUD_COVER] section in effect?

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	configured	Required result destination: 1 for authored cloud cover, otherwise 0.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_cloud_timeseries()

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

Name of the [TIMESERIES] bound as the cloud-fraction record, or "" when none is bound. NUL-terminated, truncated to buflen.

The shortwave getter's sibling — see swmm_heat_get_shortwave_timeseries.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	buf	Required writable string destination, safely truncated with a trailing NUL.
[in]	buflen	Positive capacity in bytes including the terminator.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_current_cloud()

SWMM_ENGINE_API int swmm_heat_get_current_cloud	(	SWMM_Engine	engine,
		double *	fraction )

Cloud fraction in effect at the CURRENT step, [0,1]. Read-only.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	fraction	Required result destination: last resolved dimensionless cloud fraction in [0,1].

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_current_shortwave()

SWMM_ENGINE_API int swmm_heat_get_current_shortwave	(	SWMM_Engine	engine,
		double *	wm2 )

Resolved incoming shortwave at the CURRENT step, W/m², cloud already applied. Read-only: this is state, not configuration. 0 before the first step, and whenever radiative exchange is off.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	wm2	Required result destination: last resolved incoming shortwave in W/m2.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_dry_policy()

SWMM_ENGINE_API int swmm_heat_get_dry_policy	(	SWMM_Engine	engine,
		int *	policy )

Dry policy: HOLD=0, AIR=1, DEFAULT=2.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	policy	Required result destination: HOLD=0, AIR=1 or DEFAULT=2.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_effective_element()

SWMM_ENGINE_API int swmm_heat_get_effective_element	(	SWMM_Engine	engine,
		int	attr,
		int	scope,
		const char *	name,
		double *	value,
		int *	source,
		char *	source_name,
		int	source_name_len )

Read the effective property for a named NODE, LINK or CELL2D. Source is GLOBAL=0, TAG=1, NODE=2, LINK=3, air temperature=4, ground series=5, CELL2D=6 or MESH_TAG=7. CELL2D names use one-based native cell IDs. Dynamic temperatures return NaN; source_name identifies the tag/series. This reports configuration precedence, independent of process activation.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	attr	SWMM_HeatAttr selector; sediment attributes cannot use NODE scope.
[in]	scope	NODE, LINK or CELL2D.
[in]	name	Required existing element identifier; CELL2D uses a decimal one-based ID.
[out]	value	Required effective-value destination; units follow the attribute.
[out]	source	Required origin code destination from the list above.
[out]	source_name	Optional source description, copied only when capacity is positive.
[in]	source_name_len	Source-name byte capacity; positive capacity safely truncates with NUL.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX. CELL2D reads return SWMM_ERR_PLUGIN in builds without 2D.

Here is the call graph for this function:

◆ swmm_heat_get_effective_source_temp()

SWMM_ENGINE_API int swmm_heat_get_effective_source_temp	(	SWMM_Engine	engine,
		int	source,
		int	node,
		double *	temp_c )

The temperature source water actually enters node at (°C) — the NODE override when one exists, else the GLOBAL value. This is HeatConfigData::source_temp, exposed so a caller reads the same resolution the engine uses rather than re-deriving the precedence and drifting from it.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	SWMM_HeatSourceKind code [0,6].
[in]	node	Zero-based existing node index.
[out]	temp_c	Required resolved-temperature destination in degrees Celsius.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_heat_get_element_override()

SWMM_ENGINE_API int swmm_heat_get_element_override	(	SWMM_Engine	engine,
		int	index,
		int *	attr,
		int *	scope,
		char *	name,
		int	name_len,
		double *	value )

Read one override row. Any out-pointer may be NULL.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based element-override row index.
[out]	attr	Optional SWMM_HeatAttr destination.
[out]	scope	Optional SWMM_HeatOverrideScope destination.
[out]	name	Optional name destination; copied only for positive name_len, safely truncated with NUL.
[in]	name_len	Capacity in bytes; nonpositive capacity skips the string.
[out]	value	Optional authored value, with units from its attribute.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_enabled()

SWMM_ENGINE_API int swmm_heat_get_enabled	(	SWMM_Engine	engine,
		int *	enabled )

Is [OPTIONS] HEAT_TRANSPORT on?

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	enabled	Required result destination: 1 when HEAT_TRANSPORT is enabled, otherwise 0.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_lid_material()

SWMM_ENGINE_API int swmm_heat_get_lid_material	(	SWMM_Engine	engine,
		double	values[4] )

Read-only LID material assumptions: water conductivity, soil conductivity, soil density, soil specific heat, all SI.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	values	Required array of four doubles: water conductivity W/(m K), soil conductivity W/(m K), soil density kg/m3, and soil specific heat J/(kg K).

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_module()

SWMM_ENGINE_API int swmm_heat_get_module	(	SWMM_Engine	engine,
		int	module,
		int *	on )

Read one [HEAT_FLUXES] module toggle.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	module	SWMM_HeatFluxModule selector.
[out]	on	Required destination; zero disables, nonzero enables.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_node_override()

SWMM_ENGINE_API int swmm_heat_get_node_override	(	SWMM_Engine	engine,
		int	index,
		int *	source,
		int *	node,
		double *	temp_c )

Read one NODE override by row index. Any out-pointer may be NULL.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based NODE override row index.
[out]	source	Optional source-kind destination.
[out]	node	Optional zero-based node-index destination.
[out]	temp_c	Optional temperature destination in degrees Celsius.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_radiative()

SWMM_ENGINE_API int swmm_heat_get_radiative	(	SWMM_Engine	engine,
		int	param,
		double *	value )

Read one [RADIATIVE_FLUXES] parameter.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatRadiativeParam selector.
[out]	value	Required destination; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the caller graph for this function:

◆ swmm_heat_get_sediment()

SWMM_ENGINE_API int swmm_heat_get_sediment	(	SWMM_Engine	engine,
		int	param,
		double *	value )

Read a [SEDIMENT_EXCHANGE] GLOBAL parameter.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatSedimentParam selector.
[out]	value	Required destination; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the caller graph for this function:

◆ swmm_heat_get_sediment_ground_timeseries()

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

Ground-temperature timeseries name; empty when the constant spelling is in force.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	buf	Required writable string destination, safely truncated with a trailing NUL.
[in]	buflen	Positive capacity in bytes including the terminator.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

Here is the caller graph for this function:

◆ swmm_heat_get_shortwave_mode()

SWMM_ENGINE_API int swmm_heat_get_shortwave_mode	(	SWMM_Engine	engine,
		int *	mode )

Read the incoming-shortwave mode (SWMM_HeatShortwaveMode).

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	mode	Required result destination: SWMM_HeatShortwaveMode code.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_shortwave_timeseries()

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

Name of the [TIMESERIES] bound as the shortwave record, or "" when none is bound. NUL-terminated, truncated to buflen.

The read half swmm_heat_set_shortwave_timeseries never had — an editor could rebind a series but only display "(keep current series)" for the one already bound (the G4g gap, recorded 2026-08-31). Valid in every mode: the binding survives a switch to CONSTANT or COMPUTED, exactly as the parser's does.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	buf	Required writable string destination, safely truncated with a trailing NUL.
[in]	buflen	Positive capacity in bytes including the terminator.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_solar()

SWMM_ENGINE_API int swmm_heat_get_solar	(	SWMM_Engine	engine,
		int	param,
		double *	value )

Read one [SOLAR_RADIATION] parameter.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatSolarParam selector.
[out]	value	Required destination; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_solar_sited()

SWMM_ENGINE_API int swmm_heat_get_solar_sited	(	SWMM_Engine	engine,
		int *	sited )

Have latitude AND longitude both been explicitly set?

The precondition for SWMM_HEAT_SW_COMPUTED. A GUI should gate the COMPUTED radio button on this rather than discovering the refusal after the fact.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	sited	Required result destination: 1 for a shared explicit site or both explicit heat latitude/longitude, otherwise 0.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_get_source_configured()

SWMM_ENGINE_API int swmm_heat_get_source_configured	(	SWMM_Engine	engine,
		int	source,
		int *	configured )

Did the model set this source explicitly, or is it taking the default? The editor needs the distinction to avoid writing rows a user never asked for.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	SWMM_HeatSourceKind code, in [0,6].
[out]	configured	Required result, 1 for an authored global row or 0 for its default.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_get_source_temp()

SWMM_ENGINE_API int swmm_heat_get_source_temp	(	SWMM_Engine	engine,
		int	source,
		double *	temp_c )

Read one source's GLOBAL inlet temperature (°C).

Returns: SWMM_ERR_BADINDEX for a source outside the enum. A source with no row reads the 20 °C default — use swmm_heat_get_source_configured to tell the two apart.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	SWMM_HeatSourceKind code, in [0,6].
[out]	temp_c	Required temperature destination in degrees Celsius.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_ground_source_configured()

SWMM_ENGINE_API int swmm_heat_ground_source_configured	(	SWMM_Engine	engine,
		int *	configured )

Exact authoring state for the new channel ground selector. Clear restores the absent/default PRESCRIBED choice; both operations are pre-run only.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	configured	Required result destination: 1 for an explicit channel ground-source selection, otherwise 0.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_node_override_count()

SWMM_ENGINE_API int swmm_heat_node_override_count	(	SWMM_Engine	engine,
		int *	count )

Number of NODE-scope override rows.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current override-row count.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_remove_element_override()

SWMM_ENGINE_API int swmm_heat_remove_element_override	(	SWMM_Engine	engine,
		int	index )

Remove one override row by index.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based override row to erase; later rows shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

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

◆ swmm_heat_remove_node_override()

SWMM_ENGINE_API int swmm_heat_remove_node_override	(	SWMM_Engine	engine,
		int	index )

Remove one NODE override by row index. Later rows shift down, so a caller iterating by index must re-read the count after removing.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based override row to erase; later rows shift down.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_sediment_temperature_configured()

SWMM_ENGINE_API int swmm_heat_sediment_temperature_configured	(	SWMM_Engine	engine,
		int	param,
		int *	configured )

Authored status and reset for ground/initial bed temperature.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HEAT_SED_GROUND_TEMPERATURE or SWMM_HEAT_SED_INITIAL_TEMPERATURE.
[out]	configured	Required result, 1 for explicitly authored temperature or 0 for inheritance.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_cloud()

SWMM_ENGINE_API int swmm_heat_set_cloud	(	SWMM_Engine	engine,
		int	param,
		double	value )

Write one [CLOUD_COVER] parameter. Writing any of them marks cloud cover as configured.

Returns: SWMM_ERR_BADPARAM if FRACTION is outside [0,1] (it is a fraction, not a percent) or a coefficient is negative.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatCloudParam selector.
[in]	value	New value; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_cloud_timeseries()

SWMM_ENGINE_API int swmm_heat_set_cloud_timeseries	(	SWMM_Engine	engine,
		const char *	name )

Bind a [TIMESERIES] (by name) as the cloud-fraction record.

Returns: SWMM_ERR_BADPARAM if no timeseries of that name exists.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	name	Required nonempty existing model time-series name; resolved during this call.

Note: No input string storage is retained.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

Here is the call graph for this function:

◆ swmm_heat_set_dry_policy()

SWMM_ENGINE_API int swmm_heat_set_dry_policy	(	SWMM_Engine	engine,
		int	policy )

Select the reported temperature policy for dry water elements.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	policy	HOLD=0, AIR=1 or DEFAULT=2; other values are refused.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_heat_set_element_override()

SWMM_ENGINE_API int swmm_heat_set_element_override	(	SWMM_Engine	engine,
		int	attr,
		int	scope,
		const char *	name,
		double	value )

Add or update the override for (attr, scope, name).

Returns: SWMM_ERR_BADPARAM for a refused value, a sediment attribute at NODE scope (the bed exists beneath conduits only), or a name that resolves to no element/tag (the configuration is then left unchanged); SWMM_ERR_LIFECYCLE once the run is initialized.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	attr	SWMM_HeatAttr selector.
[in]	scope	TAG, NODE, LINK, CELL2D or MESH_TAG; GROUND_SOURCE permits TAG/LINK only.
[in]	name	Required nonempty copied identifier/tag; CELL2D is a one-based native cell ID.
[in]	value	New value with the selected attribute's units/range.

Note: Failed name/override resolution restores the previous configuration.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

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

Here is the call graph for this function:

◆ swmm_heat_set_module()

SWMM_ENGINE_API int swmm_heat_set_module	(	SWMM_Engine	engine,
		int	module,
		int	on )

Write one [HEAT_FLUXES] module toggle.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	module	SWMM_HeatFluxModule selector.
[in]	on	New value; zero disables, nonzero enables.

Note: Runtime toggles are accepted except enabling previously unmapped channel mesh-contact sediment exchange, which requires BUILDING/OPENED.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_node_override()

SWMM_ENGINE_API int swmm_heat_set_node_override	(	SWMM_Engine	engine,
		int	source,
		int	node,
		double	temp_c )

Add or update the NODE override for (source, node).

Returns: SWMM_ERR_BADPARAM if source is not DWF or EXTERNAL_INFLOW — the H1 scope rule, refused rather than deferred silently, the same answer the deck gets; if node is out of range; or if temp_c is outside [-50, 100].

Note: An existing (source, node) pair is UPDATED rather than duplicated. The parser refuses a duplicate row because a deck cannot mean two temperatures at once; through an API, setting the same pair twice is an edit, and refusing it would make the editor unable to change a value it just wrote. Same invariant — one row per pair — reached the way each caller means it.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	DWF or EXTERNAL_INFLOW source code.
[in]	node	Zero-based existing node index.
[in]	temp_c	Finite new value in [-50,100] in degrees Celsius.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_heat_set_radiative()

SWMM_ENGINE_API int swmm_heat_set_radiative	(	SWMM_Engine	engine,
		int	param,
		double	value )

Write one [RADIATIVE_FLUXES] parameter.

Returns: SWMM_ERR_BADPARAM if a fraction is outside [0,1]; if SHORTWAVE is negative; or if SHORTWAVE is written while the mode is not SWMM_HEAT_SW_CONSTANT — a constant is not read in the other two modes, and storing one there would look configured while changing nothing. Switch the mode first.

Values are REFUSED, not clamped — the parser's rule, so the API and the deck agree. A refused write does not take effect.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatRadiativeParam selector.
[in]	value	New value; units and allowed range follow the selected enum member.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_sediment()

SWMM_ENGINE_API int swmm_heat_set_sediment	(	SWMM_Engine	engine,
		int	param,
		double	value )

Write a [SEDIMENT_EXCHANGE] GLOBAL parameter.

Returns: SWMM_ERR_BADPARAM for a value the parser refuses (not finite, not positive where required, negative diffusivity/velocity); SWMM_ERR_BADINDEX for an unknown param. Temperatures mark the value as stated so the writer keeps it.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatSedimentParam selector.
[in]	value	New value; units and allowed range follow the selected enum member.

Note: Ground-source changes require BUILDING/OPENED. Bed thickness with channel contacts, and material/initial-state properties used by an enabled 2D bed model, also require editable state; other scalar changes are accepted at runtime.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

Here is the call graph for this function:

◆ swmm_heat_set_sediment_ground_timeseries()

SWMM_ENGINE_API int swmm_heat_set_sediment_ground_timeseries	(	SWMM_Engine	engine,
		const char *	name )

Drive the ground temperature from a [TIMESERIES]; NULL or "" returns to the constant value.

Returns: SWMM_ERR_BADPARAM if name is not a timeseries of the model.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	name	Optional copied series name; NULL or empty clears the binding.

Note: No input string storage is retained.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

Here is the call graph for this function:

◆ swmm_heat_set_shortwave_mode()

SWMM_ENGINE_API int swmm_heat_set_shortwave_mode	(	SWMM_Engine	engine,
		int	mode )

Set the incoming-shortwave mode.

Returns: SWMM_ERR_BADPARAM for SWMM_HEAT_SW_COMPUTED when latitude or longitude is unset, and for SWMM_HEAT_SW_TIMESERIES when no series has been bound by swmm_heat_set_shortwave_timeseries.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	mode	SWMM_HEAT_SW_CONSTANT, SWMM_HEAT_SW_TIMESERIES or SWMM_HEAT_SW_COMPUTED.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_shortwave_timeseries()

SWMM_ENGINE_API int swmm_heat_set_shortwave_timeseries	(	SWMM_Engine	engine,
		const char *	name )

Bind a [TIMESERIES] (by name) as the shortwave record and switch the mode to SWMM_HEAT_SW_TIMESERIES.

Returns: SWMM_ERR_BADPARAM if no timeseries of that name exists.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	name	Required nonempty existing model time-series name; resolved during this call.

Note: No input string storage is retained.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

Here is the call graph for this function:

◆ swmm_heat_set_solar()

SWMM_ENGINE_API int swmm_heat_set_solar	(	SWMM_Engine	engine,
		int	param,
		double	value )

Write one [SOLAR_RADIATION] parameter.

Returns: SWMM_ERR_BADPARAM if out of range. Setting LATITUDE or LONGITUDE also marks it as explicitly provided, which is what SWMM_HEAT_SW_COMPUTED checks for.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	param	SWMM_HeatSolarParam selector.
[in]	value	New value; units and allowed range follow the selected enum member.

Note: Requires finite values: timezone [-14,14] hours, latitude [-90,90], longitude [-180,180], elevation [-500,9000] m, nonnegative optical depths, water/ozone columns, and ground albedo [0,1]. Updates a shared site if present.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_set_source_temp()

SWMM_ENGINE_API int swmm_heat_set_source_temp	(	SWMM_Engine	engine,
		int	source,
		double	temp_c )

Write one source's GLOBAL inlet temperature (°C).

Returns: SWMM_ERR_BADPARAM outside [-50, 100] — the parser's own range (HeatComponent.cpp parse_celsius). REFUSED, not clamped, and a refused write does not take effect. Marks the source configured.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	source	SWMM_HeatSourceKind code, in [0,6].
[in]	temp_c	Finite source temperature in [-50,100] degrees Celsius.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value. Invalid selector or row indices return SWMM_ERR_BADINDEX.

◆ swmm_heat_snapshot_create()

SWMM_ENGINE_API SWMM_HeatSnapshot swmm_heat_snapshot_create ( SWMM_Engine engine )

Allocate a reusable heat authoring snapshot for an editable engine.

Parameters

[in] engine Borrowed live engine handle; not retained by this call.

Note: Requires BUILDING/OPENED. Caller owns the returned reusable snapshot and releases it exactly once using the matching destroy function. It captures configuration and selected caches, with no ownership of the engine or runtime state.

Returns: Newly allocated SWMM_HeatSnapshot; NULL for a null handle, noneditable state, or any allocation/copy failure.

◆ swmm_heat_snapshot_destroy()

SWMM_ENGINE_API void swmm_heat_snapshot_destroy ( SWMM_HeatSnapshot snapshot )

Release a heat authoring snapshot.

Parameters

[in] snapshot Owned snapshot of the matching type; NULL is safe.

Note: May be called after the engine is closed. Invalid, foreign or previously freed snapshot pointers are unsupported. Does not close or destroy an engine.

◆ swmm_heat_snapshot_restore()

SWMM_ENGINE_API int swmm_heat_snapshot_restore	(	SWMM_Engine	engine,
		SWMM_HeatSnapshot	snapshot )

Restore a reusable heat authoring snapshot to its original engine.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	snapshot	Required live snapshot produced by swmm_heat_snapshot_create() for this exact engine identity. The snapshot remains valid and reusable after restore.

Note: Caller must ensure the original engine is still live. Captured storage is copied before publication; this call does not consume the snapshot.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

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

◆ swmm_heat_source_count()

SWMM_ENGINE_API int swmm_heat_source_count	(	SWMM_Engine	engine,
		int *	count )

Number of sources the table carries (7). Never fails on a model with no heat configured — the table is a fixed enum extent, not a parsed list.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[out]	count	Required destination for the current fixed seven-source extent.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

◆ swmm_hydrothermal_edit_atomic()

SWMM_ENGINE_API int swmm_hydrothermal_edit_atomic	(	SWMM_Engine	engine,
		SWMM_HydrothermalEdit	edit,
		void *	user )

Apply one synchronous hydrothermal configuration transaction with rollback.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	edit	Required synchronous callback, called once with engine and user; return SWMM_OK to commit, another status to restore the captured configuration.
[in,out]	user	Opaque caller-owned context forwarded unchanged; may be NULL.

Note: Callback storage is not retained. Transactions may not nest on the same thread, even across different engines. Serialize all access to the engine. Callback exceptions produce SWMM_ERR_BADPARAM and rollback; allocation failure returns SWMM_ERR_NOMEM. Only the documented configuration domains are captured.

Returns: SWMM_OK, SWMM_ERR_BADHANDLE for a null engine, or SWMM_ERR_BADPARAM for invalid required storage/value.

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

Here is the caller graph for this function:

Functions

Detailed Description

Function Documentation

◆ swmm_config_snapshot_create()

◆ swmm_config_snapshot_destroy()

◆ swmm_config_snapshot_restore()

◆ swmm_heat_clear_cloud()

◆ swmm_heat_clear_ground_source()

◆ swmm_heat_clear_sediment_temperature()

◆ swmm_heat_clear_solar_site()

◆ swmm_heat_clear_source_temp()

◆ swmm_heat_element_override_count()

◆ swmm_heat_get_authoring_flags()

◆ swmm_heat_get_cloud()

◆ swmm_heat_get_cloud_configured()

◆ swmm_heat_get_cloud_timeseries()

◆ swmm_heat_get_current_cloud()

◆ swmm_heat_get_current_shortwave()

◆ swmm_heat_get_dry_policy()

◆ swmm_heat_get_effective_element()

◆ swmm_heat_get_effective_source_temp()

◆ swmm_heat_get_element_override()

◆ swmm_heat_get_enabled()

◆ swmm_heat_get_lid_material()

◆ swmm_heat_get_module()

◆ swmm_heat_get_node_override()

◆ swmm_heat_get_radiative()

◆ swmm_heat_get_sediment()

◆ swmm_heat_get_sediment_ground_timeseries()

◆ swmm_heat_get_shortwave_mode()

◆ swmm_heat_get_shortwave_timeseries()

◆ swmm_heat_get_solar()

◆ swmm_heat_get_solar_sited()

◆ swmm_heat_get_source_configured()

◆ swmm_heat_get_source_temp()

◆ swmm_heat_ground_source_configured()

◆ swmm_heat_node_override_count()

◆ swmm_heat_remove_element_override()

◆ swmm_heat_remove_node_override()

◆ swmm_heat_sediment_temperature_configured()

◆ swmm_heat_set_cloud()

◆ swmm_heat_set_cloud_timeseries()

◆ swmm_heat_set_dry_policy()

◆ swmm_heat_set_element_override()

◆ swmm_heat_set_module()

◆ swmm_heat_set_node_override()

◆ swmm_heat_set_radiative()

◆ swmm_heat_set_sediment()

◆ swmm_heat_set_sediment_ground_timeseries()

◆ swmm_heat_set_shortwave_mode()

◆ swmm_heat_set_shortwave_timeseries()

◆ swmm_heat_set_solar()

◆ swmm_heat_set_source_temp()

◆ swmm_heat_snapshot_create()

◆ swmm_heat_snapshot_destroy()

◆ swmm_heat_snapshot_restore()

◆ swmm_heat_source_count()

◆ swmm_hydrothermal_edit_atomic()