Heat-transport configuration as an editable surface (phase H6a). More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_heat.h:

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

Classes
struct	SWMM_Heat2DStatus

struct	SWMM_GroundHeatStatus

struct	SWMM_ChannelGroundStatus

struct	SWMM_ChannelGroundContact

struct	SWMM_ChannelGroundPreview

Typedefs
typedef enum SWMM_HeatFluxModule	SWMM_HeatFluxModule
	Flux modules of heat plan §2, each independently toggleable.

typedef int(*	SWMM_HydrothermalEdit) (SWMM_Engine engine, void *user)

typedef void *	SWMM_HeatSnapshot

typedef void *	SWMM_ConfigSnapshot

typedef enum SWMM_HeatShortwaveMode	SWMM_HeatShortwaveMode
	Where incoming shortwave comes from (plan §2.5, D-H6a-3).

typedef enum SWMM_HeatRadiativeParam	SWMM_HeatRadiativeParam
	`[RADIATIVE_FLUXES]` scalar parameters.

typedef enum SWMM_HeatSolarParam	SWMM_HeatSolarParam
	`[SOLAR_RADIATION]` parameters (consulted under COMPUTED only).

typedef enum SWMM_HeatCloudParam	SWMM_HeatCloudParam
	`[CLOUD_COVER]` parameters.

typedef enum SWMM_HeatSourceKind	SWMM_HeatSourceKind
	`[HEAT_SOURCES]` water sources. Mirrors `openswmm::HeatSource`.

typedef enum SWMM_HeatSedimentParam	SWMM_HeatSedimentParam
	`[SEDIMENT_EXCHANGE]` GLOBAL parameters (bed zone beneath conduits).

typedef enum SWMM_HeatAttr	SWMM_HeatAttr
	Attributes that take per-element overrides. Mirrors `openswmm::HeatAttr`.

typedef enum SWMM_HeatOverrideScope	SWMM_HeatOverrideScope
	Scope of a per-element override row. GLOBAL values are set with swmm_heat_set_radiative / swmm_heat_set_sediment instead.

typedef struct SWMM_Heat2DStatus	SWMM_Heat2DStatus

typedef enum SWMM_Heat2DValue	SWMM_Heat2DValue

typedef struct SWMM_GroundHeatStatus	SWMM_GroundHeatStatus

typedef enum SWMM_GroundHeatValue	SWMM_GroundHeatValue

typedef enum SWMM_GroundHeatLayerValue	SWMM_GroundHeatLayerValue

typedef struct SWMM_ChannelGroundStatus	SWMM_ChannelGroundStatus

typedef enum SWMM_ChannelGroundValue	SWMM_ChannelGroundValue

typedef struct SWMM_ChannelGroundContact	SWMM_ChannelGroundContact

typedef struct SWMM_ChannelGroundPreview	SWMM_ChannelGroundPreview

Enumerations
enum	SWMM_HeatFluxModule { SWMM_HEAT_SURFACE_EXCHANGE = 0 , SWMM_HEAT_RADIATIVE_EXCHANGE = 1 , SWMM_HEAT_LAYER_CONDUCTION = 2 , SWMM_HEAT_SEDIMENT_EXCHANGE = 3 }
	Flux modules of heat plan §2, each independently toggleable. More...

enum	SWMM_HeatShortwaveMode { SWMM_HEAT_SW_CONSTANT = 0 , SWMM_HEAT_SW_TIMESERIES = 1 , SWMM_HEAT_SW_COMPUTED = 2 }
	Where incoming shortwave comes from (plan §2.5, D-H6a-3). More...

enum	SWMM_HeatRadiativeParam { SWMM_HEAT_RAD_SHORTWAVE = 0 , SWMM_HEAT_RAD_ALBEDO = 1 , SWMM_HEAT_RAD_SHADE_FACTOR = 2 , SWMM_HEAT_RAD_SKY_VIEW = 3 , SWMM_HEAT_RAD_EMISS_WATER = 4 , SWMM_HEAT_RAD_EMISS_LANDCOVER = 5 , SWMM_HEAT_RAD_ATM_EMISS_COEFF = 6 , SWMM_HEAT_RAD_LW_REFLECTION = 7 , SWMM_HEAT_RAD_LANDCOVER_TEMPERATURE = 8 }
	`[RADIATIVE_FLUXES]` scalar parameters. More...

enum	SWMM_HeatSolarParam { SWMM_HEAT_SOLAR_LATITUDE = 0 , SWMM_HEAT_SOLAR_LONGITUDE = 1 , SWMM_HEAT_SOLAR_TIMEZONE = 2 , SWMM_HEAT_SOLAR_ELEVATION = 3 , SWMM_HEAT_SOLAR_TURBIDITY_380 = 4 , SWMM_HEAT_SOLAR_TURBIDITY_500 = 5 , SWMM_HEAT_SOLAR_PRECIP_WATER = 6 , SWMM_HEAT_SOLAR_OZONE = 7 , SWMM_HEAT_SOLAR_GROUND_ALBEDO = 8 }
	`[SOLAR_RADIATION]` parameters (consulted under COMPUTED only). More...

enum	SWMM_HeatCloudParam { SWMM_HEAT_CLOUD_FRACTION = 0 , SWMM_HEAT_CLOUD_SW_ATTEN_K = 1 , SWMM_HEAT_CLOUD_SW_ATTEN_N = 2 , SWMM_HEAT_CLOUD_LW_CLOUD_K = 3 }
	`[CLOUD_COVER]` parameters. More...

enum	SWMM_HeatSourceKind { SWMM_HEAT_SRC_RAINFALL = 0 , SWMM_HEAT_SRC_DWF = 1 , SWMM_HEAT_SRC_GW = 2 , SWMM_HEAT_SRC_RDII = 3 , SWMM_HEAT_SRC_EXTERNAL_INFLOW = 4 , SWMM_HEAT_SRC_IFACE = 5 , SWMM_HEAT_SRC_INITIAL_STATE = 6 }
	`[HEAT_SOURCES]` water sources. Mirrors `openswmm::HeatSource`. More...

enum	SWMM_HeatSedimentParam { SWMM_HEAT_SED_THERMAL_DIFFUSIVITY = 0 , SWMM_HEAT_SED_SOLUTE_DIFFUSIVITY = 1 , SWMM_HEAT_SED_BED_THICKNESS = 2 , SWMM_HEAT_SED_GROUND_DEPTH = 3 , SWMM_HEAT_SED_GROUND_TEMPERATURE = 4 , SWMM_HEAT_SED_HYPORHEIC_VELOCITY = 5 , SWMM_HEAT_SED_DENSITY = 6 , SWMM_HEAT_SED_SPECIFIC_HEAT = 7 , SWMM_HEAT_SED_INITIAL_TEMPERATURE = 8 , SWMM_HEAT_SED_MESH_POROSITY = 9 , SWMM_HEAT_SED_GROUND_SOURCE }
	`[SEDIMENT_EXCHANGE]` GLOBAL parameters (bed zone beneath conduits). More...

enum	SWMM_HeatAttr { SWMM_HEAT_ATTR_ALBEDO = 0 , SWMM_HEAT_ATTR_SHADE_FACTOR = 1 , SWMM_HEAT_ATTR_SKY_VIEW = 2 , SWMM_HEAT_ATTR_EMISS_WATER = 3 , SWMM_HEAT_ATTR_EMISS_LANDCOVER = 4 , SWMM_HEAT_ATTR_LANDCOVER_TEMPERATURE = 5 , SWMM_HEAT_ATTR_THERMAL_DIFFUSIVITY = 6 , SWMM_HEAT_ATTR_SOLUTE_DIFFUSIVITY = 7 , SWMM_HEAT_ATTR_BED_THICKNESS = 8 , SWMM_HEAT_ATTR_GROUND_DEPTH = 9 , SWMM_HEAT_ATTR_GROUND_TEMPERATURE = 10 , SWMM_HEAT_ATTR_HYPORHEIC_VELOCITY = 11 , SWMM_HEAT_ATTR_SEDIMENT_DENSITY = 12 , SWMM_HEAT_ATTR_SEDIMENT_SPECIFIC_HEAT = 13 , SWMM_HEAT_ATTR_MESH_POROSITY = 14 , SWMM_HEAT_ATTR_GROUND_SOURCE = 15 }
	Attributes that take per-element overrides. Mirrors `openswmm::HeatAttr`. More...

enum	SWMM_HeatOverrideScope { SWMM_HEAT_SCOPE_TAG = 1 , SWMM_HEAT_SCOPE_NODE = 2 , SWMM_HEAT_SCOPE_LINK = 3 , SWMM_HEAT_SCOPE_CELL2D = 6 , SWMM_HEAT_SCOPE_MESH_TAG = 7 }
	Scope of a per-element override row. GLOBAL values are set with swmm_heat_set_radiative / swmm_heat_set_sediment instead. More...

enum	SWMM_Heat2DValue { SWMM_HEAT_2D_WATER_TEMPERATURE = 0 , SWMM_HEAT_2D_BED_TEMPERATURE = 1 , SWMM_HEAT_2D_BED_ENERGY = 2 , SWMM_HEAT_2D_BED_CAPACITY = 3 , SWMM_HEAT_2D_ATMOSPHERIC_ENERGY = 4 , SWMM_HEAT_2D_RADIATIVE_ENERGY = 5 , SWMM_HEAT_2D_SENSIBLE_ENERGY = 6 , SWMM_HEAT_2D_LATENT_ENERGY = 7 , SWMM_HEAT_2D_DEEP_ENERGY = 8 , SWMM_HEAT_2D_WATER_TO_BED_ENERGY = 9 , SWMM_HEAT_2D_WATER_THERMAL_INCREMENT = 10 , SWMM_HEAT_2D_ACCEPTED_EVAPORATION = 11 , SWMM_HEAT_2D_THERMAL_RESIDUAL = 12 }

enum	SWMM_GroundHeatValue { SWMM_GROUND_HEAT_ENERGY = 0 , SWMM_GROUND_HEAT_CAPACITY = 1 , SWMM_GROUND_HEAT_TEMPERATURE = 2 , SWMM_GROUND_HEAT_INITIAL_ENERGY = 3 , SWMM_GROUND_HEAT_ADVECTIVE_ENERGY = 4 , SWMM_GROUND_HEAT_SOURCE_ENERGY = 5 , SWMM_GROUND_HEAT_SURFACE_ENERGY = 6 , SWMM_GROUND_HEAT_DEEP_ENERGY = 7 , SWMM_GROUND_HEAT_LATENT_ENERGY = 8 , SWMM_GROUND_HEAT_LATERAL_ENERGY = 9 , SWMM_GROUND_HEAT_WATER_CONTACT_ENERGY = 10 , SWMM_GROUND_HEAT_RESIDUAL = 11 , SWMM_GROUND_HEAT_NORMALIZED_RESIDUAL = 12 , SWMM_GROUND_HEAT_PENDING_LATERAL , SWMM_GROUND_HEAT_CHANNEL_CONTACT = 14 , SWMM_GROUND_HEAT_LID_CONTACT = 15 }

enum	SWMM_GroundHeatLayerValue { SWMM_GROUND_LAYER_TOP = 0 , SWMM_GROUND_LAYER_BOTTOM = 1 , SWMM_GROUND_LAYER_TEMPERATURE = 2 , SWMM_GROUND_LAYER_ENERGY = 3 , SWMM_GROUND_LAYER_CAPACITY = 4 , SWMM_GROUND_LAYER_MOISTURE = 5 , SWMM_GROUND_LAYER_CONDUCTIVITY = 6 , SWMM_GROUND_LAYER_SATURATED_WATER = 7 }

enum	SWMM_ChannelGroundValue { SWMM_CHANNEL_GROUND_BED_TEMPERATURE = 0 , SWMM_CHANNEL_GROUND_ATMOSPHERIC_ENERGY = 1 , SWMM_CHANNEL_GROUND_TO_SOIL_ENERGY = 2 , SWMM_CHANNEL_GROUND_WATER_INCREMENT = 3 , SWMM_CHANNEL_GROUND_INTERVAL_COUNT = 4 }

enum	{ SWMM_HEAT_PREVIEW_STAGE_MESH = 1 , SWMM_HEAT_PREVIEW_STAGE_MAPPING = 2 }

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

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 snapshot)
	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_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_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_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_heat_get_2d_status (SWMM_Engine engine, SWMM_Heat2DStatus *status)
	Read requested and initialized coupled surface-heat status.

SWMM_ENGINE_API int	swmm_heat_get_2d_values (SWMM_Engine engine, int kind, int first_cell, int count, double *values)
	Read a contiguous range of accepted surface-heat runtime values.

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_ground_status (SWMM_Engine engine, SWMM_GroundHeatStatus *status)
	Read canonical ground thermal ownership and runtime status.

SWMM_ENGINE_API int	swmm_heat_get_ground_values (SWMM_Engine engine, int kind, int first_cell, int count, double *values)
	Read a contiguous cell range of canonical soil thermal values.

SWMM_ENGINE_API int	swmm_heat_get_ground_layers (SWMM_Engine engine, int cell, int kind, int first_layer, int count, double *values)
	Zero-based cell/layer ranges. Invalid ranges leave all output untouched.

SWMM_ENGINE_API int	swmm_heat_get_channel_ground_status (SWMM_Engine engine, SWMM_ChannelGroundStatus *status)
	Read requested and measured channel-to-ground contact status.

SWMM_ENGINE_API int	swmm_heat_get_channel_ground_values (SWMM_Engine engine, int kind, int first_link, int count, double *values)
	Read a contiguous link range of accepted channel-ground values.

SWMM_ENGINE_API int	swmm_heat_get_channel_ground_contact (SWMM_Engine engine, int index, SWMM_ChannelGroundContact *contact)
	Read one initialized channel-to-ground contact interval.

SWMM_ENGINE_API int	swmm_heat_preview_channel_ground_map (SWMM_Engine engine, int link, SWMM_ChannelGroundPreview out, SWMM_ChannelGroundContact contacts, int capacity, int *required)
	Preview complete channel XY coverage on a private mesh copy.

SWMM_ENGINE_API int	swmm_heat_preview_channel_ground_map_with_progress (SWMM_Engine engine, int link, SWMM_ChannelGroundPreview out, SWMM_ChannelGroundContact contacts, int capacity, int required, SWMM_CancelCallback callback, void user_data)
	Cancellable variant of the read-only channel-contact preview. The callback may be invoked during mesh indexing and channel mapping. If it returns nonzero, the function returns SWMM_ERR_CANCELLED and leaves `out`, `contacts`, and `required` unchanged.

SWMM_ENGINE_API int	swmm_heat_preview_channel_ground_map_page (SWMM_Engine engine, int link, SWMM_ChannelGroundPreview out, int first, SWMM_ChannelGroundContact contacts, int capacity, int required, SWMM_CancelCallback callback, void user_data)
	Bounded, cancellable contact page. `first` is a zero-based interval offset; at most `capacity` rows are copied while `required` reports the total count. The summary counts describe the complete mapping. On cancellation, all output arguments remain unchanged.

Detailed Description

Heat-transport configuration as an editable surface (phase H6a).

The model.heat component configuration — flux-module toggles, [RADIATIVE_FLUXES] parameters, and H6a's [SOLAR_RADIATION] and [CLOUD_COVER] sections — reachable from C. This is the header UNIFIED_PLAN_STATUS_2026-08-29.md §6 names as the blocker on GUI task G4g (heat configuration editor).

[HEAT_SOURCES]: The inlet-temperature table was the one section H6a left without an API; step 3 (2026-08-30) added it below — discovery + CRUD in openswmm_reactions.h's count/get/add shape, refusing exactly what the parser refuses.

Edits are live: Setters mutate engine state; the flux modules re-read the config every step, so a mid-run edit takes effect on the next routing step. This is the same contract openswmm_water_age.h documents. New finite mesh/soil stores require model selection, initial state and capacity-defining parameters before initialization. Weather and flux inputs retain their live-update behavior.

Warning: swmm_heat_set_shortwave_mode with SWMM_HEAT_SW_COMPUTED returns SWMM_ERR_BADPARAM unless BOTH latitude and longitude have been set. The engine will not fall back on the [TEMPERATURE] SNOWMELT latitude: that field defaults to 0, so borrowing it would silently model equatorial noon (heat plan §2.5).

See also: plans/transport/HEAT_TRANSPORT_PLAN.md §2.5, §5, §6 H6a

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_ChannelGroundContact

typedef struct SWMM_ChannelGroundContact SWMM_ChannelGroundContact

One initialized contact interval. Fractions refer to the full polyline; share divides legitimate common-edge ownership, never an entire reach. Invert is its representative elevation in metres SI.

◆ SWMM_ChannelGroundPreview

typedef struct SWMM_ChannelGroundPreview SWMM_ChannelGroundPreview

Pre-run, read-only XY coverage preview for one routed channel. Contact intervals use whole-polyline fractions, have layer=-1, and may be returned even when valid is false so uncovered geometry remains visible. A valid result means the complete polyline lies in the mesh; soil-profile, invert, bed-thickness and thermal-owner checks still run at initialization. Initialize struct_size and pass contacts=null/capacity=0 to query the required interval count. If capacity is too small, status and required are returned but the contact array is left untouched. Only OPENED/BUILDING engines with a parsed mesh are accepted.

◆ SWMM_ChannelGroundStatus

typedef struct SWMM_ChannelGroundStatus SWMM_ChannelGroundStatus

Routed-channel contact configuration and initialized mapping counts. Initialize struct_size. Counts describe the measured topology, even when a live parent switch pauses its exchange. All new physics is experimental.

◆ SWMM_ChannelGroundValue

typedef enum SWMM_ChannelGroundValue SWMM_ChannelGroundValue

Zero-based link ranges; unmapped links return NaN. Bed temperature is a capacity-weighted view of the actual soil under the bed, available dry or wet. It adds no reservoir and must not be counted as extra soil energy.

◆ SWMM_ConfigSnapshot

typedef void* SWMM_ConfigSnapshot

Exact pre-run authoring memento spanning simulation options, monthly climate adjustments, climate/snow/UEB, heat (including 2D thermal/GW authoring), shared site state and process-component registrations. It owns no engine; restore requires the same editable engine used to create it. The snapshot is reusable for Undo and Redo.

◆ SWMM_GroundHeatLayerValue

typedef enum SWMM_GroundHeatLayerValue SWMM_GroundHeatLayerValue

Fixed thermal depth grid, independent of hydraulic sigma layers.

◆ SWMM_GroundHeatStatus

typedef struct SWMM_GroundHeatStatus SWMM_GroundHeatStatus

Soil state is canonical solid-plus-water energy, not a second copy of the transported water-temperature row. Initialize struct_size before reading.

◆ SWMM_GroundHeatValue

typedef enum SWMM_GroundHeatValue SWMM_GroundHeatValue

Per-cell canonical fields. Positive receipts enter soil. Unmodeled cells return NaN; an entirely inactive model returns SWMM_ERR_LIFECYCLE. All energies are J relative to 0 degC, accumulated since initialization.

◆ SWMM_Heat2DStatus

typedef struct SWMM_Heat2DStatus SWMM_Heat2DStatus

Requested configuration and measured 2D runtime activation are distinct. Initialize struct_size before calling. Values apply to the mesh domain. New coupled physics remains experimental until its restart/owner matrix is qualified; the reason field states this explicitly.

◆ SWMM_Heat2DValue

typedef enum SWMM_Heat2DValue SWMM_Heat2DValue

SI runtime fields, cumulative since initialization. Positive J enters the named store; WATER_TO_BED is positive water -> bed. Cell indices are zero based at this bulk API. Bed-only fields are unavailable without a bed.

◆ SWMM_HeatAttr

typedef enum SWMM_HeatAttr SWMM_HeatAttr

Attributes that take per-element overrides. Mirrors openswmm::HeatAttr.

◆ SWMM_HeatCloudParam

typedef enum SWMM_HeatCloudParam SWMM_HeatCloudParam

[CLOUD_COVER] parameters.

◆ SWMM_HeatFluxModule

typedef enum SWMM_HeatFluxModule SWMM_HeatFluxModule

Flux modules of heat plan §2, each independently toggleable.

◆ SWMM_HeatOverrideScope

typedef enum SWMM_HeatOverrideScope SWMM_HeatOverrideScope

Scope of a per-element override row. GLOBAL values are set with swmm_heat_set_radiative / swmm_heat_set_sediment instead.

◆ SWMM_HeatRadiativeParam

typedef enum SWMM_HeatRadiativeParam SWMM_HeatRadiativeParam

[RADIATIVE_FLUXES] scalar parameters.

◆ SWMM_HeatSedimentParam

typedef enum SWMM_HeatSedimentParam SWMM_HeatSedimentParam

[SEDIMENT_EXCHANGE] GLOBAL parameters (bed zone beneath conduits).

◆ SWMM_HeatShortwaveMode

typedef enum SWMM_HeatShortwaveMode SWMM_HeatShortwaveMode

Where incoming shortwave comes from (plan §2.5, D-H6a-3).

The three are MUTUALLY EXCLUSIVE in EFFECT — exactly one is read, and there is no precedence ladder behind them.

Switching modes does NOT erase the other modes' settings: a constant stays stored while a timeseries is active, and vice versa, so a GUI can offer three radio buttons without destroying what the user typed under the other two. Only the selected one reaches the model. (A deck cannot express that ambiguity at all — the parser refuses a second SHORTWAVE row outright.)

◆ SWMM_HeatSnapshot

typedef void* SWMM_HeatSnapshot

◆ SWMM_HeatSolarParam

typedef enum SWMM_HeatSolarParam SWMM_HeatSolarParam

[SOLAR_RADIATION] parameters (consulted under COMPUTED only).

◆ SWMM_HeatSourceKind

typedef enum SWMM_HeatSourceKind SWMM_HeatSourceKind

[HEAT_SOURCES] water sources. Mirrors openswmm::HeatSource.

◆ SWMM_HydrothermalEdit

typedef int(* SWMM_HydrothermalEdit) (SWMM_Engine engine, void *user)

Pre-run climate/snow/heat transaction. The callback may use only climate, snow configuration, heat configuration (including 2D heat and GW/aquifer authoring), HEAT_TRANSPORT, component registrations and climate-file path setters. Returning an error restores values and provenance. The callback must not change topology, destroy the engine, run, or nest transactions.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
SWMM_HEAT_PREVIEW_STAGE_MESH
SWMM_HEAT_PREVIEW_STAGE_MAPPING

◆ SWMM_ChannelGroundValue

enum SWMM_ChannelGroundValue

Zero-based link ranges; unmapped links return NaN. Bed temperature is a capacity-weighted view of the actual soil under the bed, available dry or wet. It adds no reservoir and must not be counted as extra soil energy.

Enumerator
SWMM_CHANNEL_GROUND_BED_TEMPERATURE	degC.
SWMM_CHANNEL_GROUND_ATMOSPHERIC_ENERGY	J, atmosphere -> channel.
SWMM_CHANNEL_GROUND_TO_SOIL_ENERGY	J, channel -> soil.
SWMM_CHANNEL_GROUND_WATER_INCREMENT	J, channel thermal change excluding advection.
SWMM_CHANNEL_GROUND_INTERVAL_COUNT	dimensionless, mapped chainage/layer intervals.

◆ SWMM_GroundHeatLayerValue

enum SWMM_GroundHeatLayerValue

Fixed thermal depth grid, independent of hydraulic sigma layers.

Enumerator
SWMM_GROUND_LAYER_TOP	depth below terrain, m.
SWMM_GROUND_LAYER_BOTTOM	depth below terrain, m.
SWMM_GROUND_LAYER_TEMPERATURE	degC.
SWMM_GROUND_LAYER_ENERGY	J relative to 0 degC.
SWMM_GROUND_LAYER_CAPACITY	J/K.
SWMM_GROUND_LAYER_MOISTURE	m3 water per m3 bulk soil.
SWMM_GROUND_LAYER_CONDUCTIVITY	W/(m K).
SWMM_GROUND_LAYER_SATURATED_WATER	m3.

◆ SWMM_GroundHeatValue

enum SWMM_GroundHeatValue

Per-cell canonical fields. Positive receipts enter soil. Unmodeled cells return NaN; an entirely inactive model returns SWMM_ERR_LIFECYCLE. All energies are J relative to 0 degC, accumulated since initialization.

Enumerator
SWMM_GROUND_HEAT_ENERGY
SWMM_GROUND_HEAT_CAPACITY	J/K.
SWMM_GROUND_HEAT_TEMPERATURE	capacity-weighted degC.
SWMM_GROUND_HEAT_INITIAL_ENERGY
SWMM_GROUND_HEAT_ADVECTIVE_ENERGY
SWMM_GROUND_HEAT_SOURCE_ENERGY
SWMM_GROUND_HEAT_SURFACE_ENERGY
SWMM_GROUND_HEAT_DEEP_ENERGY
SWMM_GROUND_HEAT_LATENT_ENERGY
SWMM_GROUND_HEAT_LATERAL_ENERGY
SWMM_GROUND_HEAT_WATER_CONTACT_ENERGY
SWMM_GROUND_HEAT_RESIDUAL
SWMM_GROUND_HEAT_NORMALIZED_RESIDUAL	dimensionless, absolute-energy scaled.
SWMM_GROUND_HEAT_PENDING_LATERAL	J awaiting this cell's LTS gather; add to stored energy for domain totals.
SWMM_GROUND_HEAT_CHANNEL_CONTACT	J, routed channel water -> soil.
SWMM_GROUND_HEAT_LID_CONTACT	J, mesh-connected LID -> soil.

◆ SWMM_Heat2DValue

enum SWMM_Heat2DValue

SI runtime fields, cumulative since initialization. Positive J enters the named store; WATER_TO_BED is positive water -> bed. Cell indices are zero based at this bulk API. Bed-only fields are unavailable without a bed.

Enumerator
SWMM_HEAT_2D_WATER_TEMPERATURE	degC; dry reporting policy only.
SWMM_HEAT_2D_BED_TEMPERATURE	degC.
SWMM_HEAT_2D_BED_ENERGY	J relative to 0 degC.
SWMM_HEAT_2D_BED_CAPACITY	J/K.
SWMM_HEAT_2D_ATMOSPHERIC_ENERGY
SWMM_HEAT_2D_RADIATIVE_ENERGY
SWMM_HEAT_2D_SENSIBLE_ENERGY
SWMM_HEAT_2D_LATENT_ENERGY
SWMM_HEAT_2D_DEEP_ENERGY
SWMM_HEAT_2D_WATER_TO_BED_ENERGY
SWMM_HEAT_2D_WATER_THERMAL_INCREMENT	J; excludes water advection.
SWMM_HEAT_2D_ACCEPTED_EVAPORATION	m3.
SWMM_HEAT_2D_THERMAL_RESIDUAL	J; bed change + water increment - external heat.

◆ SWMM_HeatAttr

enum SWMM_HeatAttr

Attributes that take per-element overrides. Mirrors openswmm::HeatAttr.

Enumerator
SWMM_HEAT_ATTR_ALBEDO	`[RADIATIVE_FLUXES]`, [0,1].
SWMM_HEAT_ATTR_SHADE_FACTOR	[0,1].
SWMM_HEAT_ATTR_SKY_VIEW	[0,1].
SWMM_HEAT_ATTR_EMISS_WATER	[0,1].
SWMM_HEAT_ATTR_EMISS_LANDCOVER	[0,1].
SWMM_HEAT_ATTR_LANDCOVER_TEMPERATURE	°C.
SWMM_HEAT_ATTR_THERMAL_DIFFUSIVITY	`[SEDIMENT_EXCHANGE]`, > 0.
SWMM_HEAT_ATTR_SOLUTE_DIFFUSIVITY	>= 0.
SWMM_HEAT_ATTR_BED_THICKNESS
SWMM_HEAT_ATTR_GROUND_DEPTH
SWMM_HEAT_ATTR_GROUND_TEMPERATURE	°C.
SWMM_HEAT_ATTR_HYPORHEIC_VELOCITY	>= 0.
SWMM_HEAT_ATTR_SEDIMENT_DENSITY
SWMM_HEAT_ATTR_SEDIMENT_SPECIFIC_HEAT
SWMM_HEAT_ATTR_MESH_POROSITY	[0,1], new mesh bed only.
SWMM_HEAT_ATTR_GROUND_SOURCE	0 PRESCRIBED, 1 MESH_CONTACTS; GLOBAL/TAG/LINK only.

◆ SWMM_HeatCloudParam

enum SWMM_HeatCloudParam

[CLOUD_COVER] parameters.

Enumerator
SWMM_HEAT_CLOUD_FRACTION	C [0,1], constant spelling.
SWMM_HEAT_CLOUD_SW_ATTEN_K	Kasten–Czeplak k.
SWMM_HEAT_CLOUD_SW_ATTEN_N	Kasten–Czeplak n.
SWMM_HEAT_CLOUD_LW_CLOUD_K	Bolz k_lw.

◆ SWMM_HeatFluxModule

enum SWMM_HeatFluxModule

Flux modules of heat plan §2, each independently toggleable.

Enumerator
SWMM_HEAT_SURFACE_EXCHANGE	Latent + sensible (H2).
SWMM_HEAT_RADIATIVE_EXCHANGE	Shortwave + longwave (H3).
SWMM_HEAT_LAYER_CONDUCTION	LID vertical conduction (H5b).
SWMM_HEAT_SEDIMENT_EXCHANGE	Channel bed conduction and hyporheic exchange.

◆ SWMM_HeatOverrideScope

enum SWMM_HeatOverrideScope

Scope of a per-element override row. GLOBAL values are set with swmm_heat_set_radiative / swmm_heat_set_sediment instead.

Enumerator
SWMM_HEAT_SCOPE_TAG	every element carrying the tag.
SWMM_HEAT_SCOPE_NODE	one node (radiative attributes only).
SWMM_HEAT_SCOPE_LINK	one link.
SWMM_HEAT_SCOPE_CELL2D	one mesh cell; name is its 1-based file ID.
SWMM_HEAT_SCOPE_MESH_TAG	mesh region tag, independent of network TAG.

◆ SWMM_HeatRadiativeParam

enum SWMM_HeatRadiativeParam

[RADIATIVE_FLUXES] scalar parameters.

Enumerator
SWMM_HEAT_RAD_SHORTWAVE	W/m², CONSTANT mode only.
SWMM_HEAT_RAD_ALBEDO	Water reflectance Rs [0,1].
SWMM_HEAT_RAD_SHADE_FACTOR	fs [0,1].
SWMM_HEAT_RAD_SKY_VIEW	fsky [0,1].
SWMM_HEAT_RAD_EMISS_WATER	εw [0,1].
SWMM_HEAT_RAD_EMISS_LANDCOVER	εlc [0,1].
SWMM_HEAT_RAD_ATM_EMISS_COEFF	Brunt Aa [0,1].
SWMM_HEAT_RAD_LW_REFLECTION	RL [0,1].
SWMM_HEAT_RAD_LANDCOVER_TEMPERATURE	°C; NaN restores air-temperature inheritance.

◆ SWMM_HeatSedimentParam

enum SWMM_HeatSedimentParam

[SEDIMENT_EXCHANGE] GLOBAL parameters (bed zone beneath conduits).

Enumerator
SWMM_HEAT_SED_THERMAL_DIFFUSIVITY	m²/s, > 0.
SWMM_HEAT_SED_SOLUTE_DIFFUSIVITY	m²/s, >= 0 (0 = advection-only storage).
SWMM_HEAT_SED_BED_THICKNESS	m, > 0.
SWMM_HEAT_SED_GROUND_DEPTH	m, > 0.
SWMM_HEAT_SED_GROUND_TEMPERATURE	°C, constant spelling; setting it replaces a ground timeseries.
SWMM_HEAT_SED_HYPORHEIC_VELOCITY	m/s, >= 0.
SWMM_HEAT_SED_DENSITY	kg/m³, > 0.
SWMM_HEAT_SED_SPECIFIC_HEAT	J/kg/K, > 0.
SWMM_HEAT_SED_INITIAL_TEMPERATURE	°C; unset = start at ground temperature.
SWMM_HEAT_SED_MESH_POROSITY	[0,1], new mesh bed only.
SWMM_HEAT_SED_GROUND_SOURCE	0 PRESCRIBED, 1 MESH_CONTACTS; routed channels only, pre-run.

◆ SWMM_HeatShortwaveMode

enum SWMM_HeatShortwaveMode

Where incoming shortwave comes from (plan §2.5, D-H6a-3).

The three are MUTUALLY EXCLUSIVE in EFFECT — exactly one is read, and there is no precedence ladder behind them.

Switching modes does NOT erase the other modes' settings: a constant stays stored while a timeseries is active, and vice versa, so a GUI can offer three radio buttons without destroying what the user typed under the other two. Only the selected one reaches the model. (A deck cannot express that ambiguity at all — the parser refuses a second SHORTWAVE row outright.)

Enumerator
SWMM_HEAT_SW_CONSTANT	Fixed W/m².
SWMM_HEAT_SW_TIMESERIES	Measured record.
SWMM_HEAT_SW_COMPUTED	Solar position + Bird clear-sky.

◆ SWMM_HeatSolarParam

enum SWMM_HeatSolarParam

[SOLAR_RADIATION] parameters (consulted under COMPUTED only).

Enumerator
SWMM_HEAT_SOLAR_LATITUDE	Degrees, +N, [-90, 90].
SWMM_HEAT_SOLAR_LONGITUDE	Degrees, +E, [-180, 180].
SWMM_HEAT_SOLAR_TIMEZONE	Hours from UTC, +E.
SWMM_HEAT_SOLAR_ELEVATION	Metres, [-500, 9000]. Below sea level is legal. Never written = take the climate state's elev.
SWMM_HEAT_SOLAR_TURBIDITY_380	Bird AOD at 380 nm.
SWMM_HEAT_SOLAR_TURBIDITY_500	Bird AOD at 500 nm.
SWMM_HEAT_SOLAR_PRECIP_WATER	Precipitable water, cm.
SWMM_HEAT_SOLAR_OZONE	Ozone column, cm.
SWMM_HEAT_SOLAR_GROUND_ALBEDO	LAND albedo [0,1] — NOT the water's SWMM_HEAT_RAD_ALBEDO.

◆ SWMM_HeatSourceKind

enum SWMM_HeatSourceKind

[HEAT_SOURCES] water sources. Mirrors openswmm::HeatSource.

Enumerator
SWMM_HEAT_SRC_RAINFALL	washoff runoff.
SWMM_HEAT_SRC_DWF	dry-weather flow.
SWMM_HEAT_SRC_GW	groundwater.
SWMM_HEAT_SRC_RDII	rainfall-derived infiltration.
SWMM_HEAT_SRC_EXTERNAL_INFLOW	`[INFLOWS]`.
SWMM_HEAT_SRC_IFACE	interface file.
SWMM_HEAT_SRC_INITIAL_STATE	water present at t = 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_2d_status()

SWMM_ENGINE_API int swmm_heat_get_2d_status	(	SWMM_Engine	engine,
		SWMM_Heat2DStatus *	status )

Read requested and initialized coupled surface-heat status.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in,out]	status	Required caller-owned record with struct_size at least sizeof(SWMM_Heat2DStatus).

Note: Available before initialization; reports requested and measured state separately. Builds without 2D return success with inactive fields and an explanatory reason. Invalid handle/record leaves the output unchanged.

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

SWMM_ENGINE_API int swmm_heat_get_2d_values	(	SWMM_Engine	engine,
		int	kind,
		int	first_cell,
		int	count,
		double *	values )

Read a contiguous range of accepted surface-heat runtime values.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	kind	SWMM_Heat2DValue selector; units/signs follow the enum member.
[in]	first_cell	Nonnegative zero-based starting cell index.
[in]	count	Nonnegative number of consecutive values to copy; span must fit the model.
[out]	values	Caller-owned count-double destination; may be NULL only when count == 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists.

Here is the call graph for this function:

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

SWMM_ENGINE_API int swmm_heat_get_channel_ground_contact	(	SWMM_Engine	engine,
		int	index,
		SWMM_ChannelGroundContact *	contact )

Read one initialized channel-to-ground contact interval.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	index	Zero-based initialized contact-interval index.
[in,out]	contact	Required record with struct_size at least sizeof(SWMM_ChannelGroundContact).

Note: Output remains unchanged on failure; reads accepted runtime contact geometry.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists.

Here is the call graph for this function:

◆ swmm_heat_get_channel_ground_status()

SWMM_ENGINE_API int swmm_heat_get_channel_ground_status	(	SWMM_Engine	engine,
		SWMM_ChannelGroundStatus *	status )

Read requested and measured channel-to-ground contact status.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in,out]	status	Required caller-owned record with struct_size at least sizeof(SWMM_ChannelGroundStatus).

Note: Available before initialization; reports requested and measured state separately. Builds without 2D return success with inactive fields and an explanatory reason. Invalid handle/record leaves the output unchanged.

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

SWMM_ENGINE_API int swmm_heat_get_channel_ground_values	(	SWMM_Engine	engine,
		int	kind,
		int	first_link,
		int	count,
		double *	values )

Read a contiguous link range of accepted channel-ground values.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	kind	SWMM_ChannelGroundValue selector; units/signs follow the enum member.
[in]	first_link	Nonnegative zero-based starting link index.
[in]	count	Nonnegative number of consecutive values to copy; span must fit the model.
[out]	values	Caller-owned count-double destination; may be NULL only when count == 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists.

Here is the call graph for this function:

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

SWMM_ENGINE_API int swmm_heat_get_ground_layers	(	SWMM_Engine	engine,
		int	cell,
		int	kind,
		int	first_layer,
		int	count,
		double *	values )

Zero-based cell/layer ranges. Invalid ranges leave all output untouched.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	cell	Zero-based mesh cell with an initialized thermal column.
[in]	kind	SWMM_GroundHeatLayerValue selector; units follow the enum.
[in]	first_layer	Nonnegative zero-based starting thermal layer, surface first.
[in]	count	Nonnegative layer count; the complete span must fit the column.
[out]	values	Caller-owned count-double destination; NULL only when count == 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists.

Here is the call graph for this function:

◆ swmm_heat_get_ground_status()

SWMM_ENGINE_API int swmm_heat_get_ground_status	(	SWMM_Engine	engine,
		SWMM_GroundHeatStatus *	status )

Read canonical ground thermal ownership and runtime status.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in,out]	status	Required caller-owned record with struct_size at least sizeof(SWMM_GroundHeatStatus).

Note: Available before initialization; reports requested and measured state separately. Builds without 2D return success with inactive fields and an explanatory reason. Invalid handle/record leaves the output unchanged.

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

SWMM_ENGINE_API int swmm_heat_get_ground_values	(	SWMM_Engine	engine,
		int	kind,
		int	first_cell,
		int	count,
		double *	values )

Read a contiguous cell range of canonical soil thermal values.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	kind	SWMM_GroundHeatValue selector; units/signs follow the enum member.
[in]	first_cell	Nonnegative zero-based starting cell index.
[in]	count	Nonnegative number of consecutive values to copy; span must fit the model.
[out]	values	Caller-owned count-double destination; may be NULL only when count == 0.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists.

Here is the call graph for this function:

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

SWMM_ENGINE_API int swmm_heat_preview_channel_ground_map	(	SWMM_Engine	engine,
		int	link,
		SWMM_ChannelGroundPreview *	out,
		SWMM_ChannelGroundContact *	contacts,
		int	capacity,
		int *	required )

Preview complete channel XY coverage on a private mesh copy.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	link	Zero-based existing routed-channel link index.
[in,out]	out	Required summary with struct_size at least sizeof(SWMM_ChannelGroundPreview).
[out]	contacts	Caller-owned array of capacity contact records; NULL only when capacity == 0.
[in]	capacity	Nonnegative contact-record capacity; zero permits a size query.
[out]	required	Required destination for the complete mapping's interval count.

Note: Requires BUILDING/OPENED and works on a private geometry copy. Missing mesh or ineligible geometry produces SWMM_OK with out->valid == 0 and a reason. No hydraulic or thermal model state is initialized. Cancellation leaves all outputs untouched; a short nonpaged buffer publishes summary/required only.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists. Progress variants additionally return SWMM_ERR_CANCELLED.

◆ swmm_heat_preview_channel_ground_map_page()

SWMM_ENGINE_API int swmm_heat_preview_channel_ground_map_page	(	SWMM_Engine	engine,
		int	link,
		SWMM_ChannelGroundPreview *	out,
		int	first,
		SWMM_ChannelGroundContact *	contacts,
		int	capacity,
		int *	required,
		SWMM_CancelCallback	callback,
		void *	user_data )

Bounded, cancellable contact page. first is a zero-based interval offset; at most capacity rows are copied while required reports the total count. The summary counts describe the complete mapping. On cancellation, all output arguments remain unchanged.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	link	Zero-based existing routed-channel link index.
[in,out]	out	Required summary with struct_size at least sizeof(SWMM_ChannelGroundPreview).
[out]	contacts	Caller-owned array of capacity contact records; NULL only when capacity == 0.
[in]	capacity	Nonnegative contact-record capacity; zero permits a size query.
[out]	required	Required destination for the complete mapping's interval count.
[in]	first	Zero-based interval offset, at most the complete interval count.
[in]	callback	Optional synchronous cancellation/progress callback; receives engine, stage SWMM_HEAT_PREVIEW_STAGE_*, percentage [0,100], and user_data. Nonzero cancels.
[in,out]	user_data	Opaque caller-owned callback context; may be NULL and is not retained.

Note: Requires BUILDING/OPENED and works on a private geometry copy. Missing mesh or ineligible geometry produces SWMM_OK with out->valid == 0 and a reason. No hydraulic or thermal model state is initialized. Cancellation leaves all outputs untouched; a short nonpaged buffer publishes summary/required only.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists. Progress variants additionally return SWMM_ERR_CANCELLED.

◆ swmm_heat_preview_channel_ground_map_with_progress()

SWMM_ENGINE_API int swmm_heat_preview_channel_ground_map_with_progress	(	SWMM_Engine	engine,
		int	link,
		SWMM_ChannelGroundPreview *	out,
		SWMM_ChannelGroundContact *	contacts,
		int	capacity,
		int *	required,
		SWMM_CancelCallback	callback,
		void *	user_data )

Cancellable variant of the read-only channel-contact preview. The callback may be invoked during mesh indexing and channel mapping. If it returns nonzero, the function returns SWMM_ERR_CANCELLED and leaves out, contacts, and required unchanged.

Parameters

[in]	engine	Borrowed live engine handle; not retained by this call.
[in]	link	Zero-based existing routed-channel link index.
[in,out]	out	Required summary with struct_size at least sizeof(SWMM_ChannelGroundPreview).
[out]	contacts	Caller-owned array of capacity contact records; NULL only when capacity == 0.
[in]	capacity	Nonnegative contact-record capacity; zero permits a size query.
[out]	required	Required destination for the complete mapping's interval count.
[in]	callback	Optional synchronous cancellation/progress callback; receives engine, stage SWMM_HEAT_PREVIEW_STAGE_*, percentage [0,100], and user_data. Nonzero cancels.
[in,out]	user_data	Opaque caller-owned callback context; may be NULL and is not retained.

Note: Requires BUILDING/OPENED and works on a private geometry copy. Missing mesh or ineligible geometry produces SWMM_OK with out->valid == 0 and a reason. No hydraulic or thermal model state is initialized. Cancellation leaves all outputs untouched; a short nonpaged buffer publishes summary/required only.

Returns: SWMM_OK; SWMM_ERR_BADHANDLE for a null engine; SWMM_ERR_BADPARAM for invalid selector/count/storage; SWMM_ERR_BADINDEX for an out-of-range span; SWMM_ERR_LIFECYCLE for unavailable runtime; or SWMM_ERR_PLUGIN without 2D.

Note: Accepted spans are validated before writing. Runtime reads remain available after ENDED/REPORTED when the corresponding stored thermal owner exists. Progress variants additionally return SWMM_ERR_CANCELLED.

◆ 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:

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ SWMM_ChannelGroundContact

◆ SWMM_ChannelGroundPreview

◆ SWMM_ChannelGroundStatus

◆ SWMM_ChannelGroundValue

◆ SWMM_ConfigSnapshot

◆ SWMM_GroundHeatLayerValue

◆ SWMM_GroundHeatStatus

◆ SWMM_GroundHeatValue

◆ SWMM_Heat2DStatus

◆ SWMM_Heat2DValue

◆ SWMM_HeatAttr

◆ SWMM_HeatCloudParam

◆ SWMM_HeatFluxModule

◆ SWMM_HeatOverrideScope

◆ SWMM_HeatRadiativeParam

◆ SWMM_HeatSedimentParam

◆ SWMM_HeatShortwaveMode

◆ SWMM_HeatSnapshot

◆ SWMM_HeatSolarParam

◆ SWMM_HeatSourceKind

◆ SWMM_HydrothermalEdit

Enumeration Type Documentation

◆ anonymous enum

◆ SWMM_ChannelGroundValue

◆ SWMM_GroundHeatLayerValue

◆ SWMM_GroundHeatValue

◆ SWMM_Heat2DValue

◆ SWMM_HeatAttr

◆ SWMM_HeatCloudParam

◆ SWMM_HeatFluxModule

◆ SWMM_HeatOverrideScope

◆ SWMM_HeatRadiativeParam

◆ SWMM_HeatSedimentParam

◆ SWMM_HeatShortwaveMode

◆ SWMM_HeatSolarParam

◆ SWMM_HeatSourceKind

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

◆ swmm_heat_get_2d_values()

◆ swmm_heat_get_authoring_flags()

◆ swmm_heat_get_channel_ground_contact()

◆ swmm_heat_get_channel_ground_status()

◆ swmm_heat_get_channel_ground_values()

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

◆ swmm_heat_get_ground_status()

◆ swmm_heat_get_ground_values()

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