openswmm_heat_impl.cpp File Reference

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

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_heat.h"

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.

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

Function Documentation

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.

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.

swmm_heat_get_cloud()

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

Read one [CLOUD_COVER] parameter.

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?

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.

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.

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.

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.

Here is the call graph for this function:

swmm_heat_get_enabled()

SWMM_ENGINE_API int swmm_heat_get_enabled	(	SWMM_Engine	engine,
		int *	enabled )

Is [OPTIONS] HEAT_TRANSPORT on?

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.

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.

swmm_heat_get_radiative()

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

Read one [RADIATIVE_FLUXES] parameter.

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

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.

swmm_heat_get_solar()

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

Read one [SOLAR_RADIATION] parameter.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.