openswmm_mesh_heat_impl.cpp File Reference

Public C API implementation for mesh thermal configuration. More...

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

Include dependency graph for openswmm_mesh_heat_impl.cpp:

Functions
int	swmm_heat_get_channel_ground_status (SWMM_Engine engine, SWMM_ChannelGroundStatus *out)
	Read requested and measured channel-to-ground contact status.
int	swmm_heat_get_channel_ground_values (SWMM_Engine engine, int kind, int first, int count, double *out)
	Read a contiguous link range of accepted channel-ground values.
int	swmm_heat_get_channel_ground_contact (SWMM_Engine engine, int index, SWMM_ChannelGroundContact *out)
	Read one initialized channel-to-ground contact interval.
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.
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.
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.
int	swmm_heat_get_2d_status (SWMM_Engine engine, SWMM_Heat2DStatus *out)
	Read requested and initialized coupled surface-heat status.
int	swmm_heat_get_2d_values (SWMM_Engine engine, int kind, int first, int count, double *out)
	Read a contiguous range of accepted surface-heat runtime values.
int	swmm_heat_get_ground_status (SWMM_Engine engine, SWMM_GroundHeatStatus *out)
	Read canonical ground thermal ownership and runtime status.
int	swmm_heat_get_ground_values (SWMM_Engine engine, int kind, int first, int count, double *out)
	Read a contiguous cell range of canonical soil thermal values.
int	swmm_heat_get_ground_layers (SWMM_Engine engine, int cell, int kind, int first, int count, double *out)
	Zero-based cell/layer ranges. Invalid ranges leave all output untouched.

Detailed Description

Public C API implementation for mesh thermal configuration.

Author

Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License

Apache-2.0

Function Documentation

swmm_heat_get_2d_status()

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

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

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

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

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

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

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

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

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

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

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.