openswmm_heat.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_HEAT_H
#define OPENSWMM_HEAT_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif

typedef enum SWMM_HeatFluxModule {
    SWMM_HEAT_SURFACE_EXCHANGE = 0,   
    SWMM_HEAT_RADIATIVE_EXCHANGE = 1, 
    SWMM_HEAT_LAYER_CONDUCTION = 2,   
    SWMM_HEAT_SEDIMENT_EXCHANGE = 3   
} SWMM_HeatFluxModule;

typedef int (*SWMM_HydrothermalEdit)(SWMM_Engine engine, void* user);
SWMM_ENGINE_API int swmm_hydrothermal_edit_atomic(SWMM_Engine engine, SWMM_HydrothermalEdit edit,
                                                  void* user);
SWMM_ENGINE_API int swmm_heat_get_dry_policy(SWMM_Engine engine, int* policy);
SWMM_ENGINE_API int swmm_heat_set_dry_policy(SWMM_Engine engine, int policy);
SWMM_ENGINE_API int swmm_heat_get_lid_material(SWMM_Engine engine, double values[4]);
SWMM_ENGINE_API int swmm_heat_clear_solar_site(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_heat_get_authoring_flags(SWMM_Engine engine, unsigned* flags);
typedef void* SWMM_HeatSnapshot;
SWMM_ENGINE_API SWMM_HeatSnapshot swmm_heat_snapshot_create(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_heat_snapshot_restore(SWMM_Engine engine, SWMM_HeatSnapshot snapshot);
SWMM_ENGINE_API void swmm_heat_snapshot_destroy(SWMM_HeatSnapshot snapshot);

typedef void* SWMM_ConfigSnapshot;
SWMM_ENGINE_API SWMM_ConfigSnapshot swmm_config_snapshot_create(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_config_snapshot_restore(SWMM_Engine engine, SWMM_ConfigSnapshot snapshot);
SWMM_ENGINE_API void swmm_config_snapshot_destroy(SWMM_ConfigSnapshot snapshot);

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

typedef enum SWMM_HeatShortwaveMode {
    SWMM_HEAT_SW_CONSTANT = 0,   
    SWMM_HEAT_SW_TIMESERIES = 1, 
    SWMM_HEAT_SW_COMPUTED = 2    
} SWMM_HeatShortwaveMode;

typedef 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 
} SWMM_HeatRadiativeParam;

typedef 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  
} SWMM_HeatSolarParam;

typedef 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  
} SWMM_HeatCloudParam;
 
/* ---------------------------------------------------------------- toggles */

SWMM_ENGINE_API int swmm_heat_get_enabled(SWMM_Engine engine, int* enabled);

SWMM_ENGINE_API int swmm_heat_get_module(SWMM_Engine engine, int module, int* on);
SWMM_ENGINE_API int swmm_heat_set_module(SWMM_Engine engine, int module, int on);
 
/* ------------------------------------------------------------- radiative */

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

SWMM_ENGINE_API int swmm_heat_get_shortwave_mode(SWMM_Engine engine, int* mode);
SWMM_ENGINE_API int swmm_heat_set_shortwave_mode(SWMM_Engine engine, int mode);

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

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

SWMM_ENGINE_API int swmm_heat_get_current_shortwave(SWMM_Engine engine, double* wm2);
 
/* ----------------------------------------------------------------- solar */

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

SWMM_ENGINE_API int swmm_heat_get_solar_sited(SWMM_Engine engine, int* sited);
 
/* ----------------------------------------------------------------- cloud */

SWMM_ENGINE_API int swmm_heat_get_cloud_configured(SWMM_Engine engine, int* configured);

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

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

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

SWMM_ENGINE_API int swmm_heat_clear_cloud(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_heat_get_current_cloud(SWMM_Engine engine, double* fraction);
 
/* -------------------------------------------------------- [HEAT_SOURCES]
 *
 * The per-source inlet temperature table: a GLOBAL °C for each of the seven
 * water sources, plus NODE-scope overrides. Added for the G4g editor, which
 * cannot round-trip a table the API cannot read.
 *
 * Every refusal below mirrors `HeatComponent.cpp`'s parser exactly, so a
 * value the deck rejects is a value this API rejects, and the two cannot
 * disagree about what a model contains. Values are REFUSED, never clamped.
 */

typedef 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    
} SWMM_HeatSourceKind;

SWMM_ENGINE_API int swmm_heat_source_count(SWMM_Engine engine, int* count);

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

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

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

SWMM_ENGINE_API int swmm_heat_clear_source_temp(SWMM_Engine engine, int source);

SWMM_ENGINE_API int swmm_heat_node_override_count(SWMM_Engine engine, int* count);

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

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

SWMM_ENGINE_API int swmm_heat_remove_node_override(SWMM_Engine engine, int index);

SWMM_ENGINE_API int swmm_heat_get_effective_source_temp(SWMM_Engine engine, int source, int node,
                                                        double* temp_c);
 
/* =========================================================================
 * [SEDIMENT_EXCHANGE] and per-element attribute overrides
 * (closed C-API gaps 2026-10-11)
 *
 * Values are REFUSED, never clamped, by the same rules as the parser
 * (HeatComponent.cpp). Edits persist: the heat serializer writes the
 * configuration and the override rows back to the component file on save.
 * ========================================================================= */

typedef 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 =
        10 
} SWMM_HeatSedimentParam;

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

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

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

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

typedef 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 
} SWMM_HeatAttr;

typedef 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 
} SWMM_HeatOverrideScope;

SWMM_ENGINE_API int swmm_heat_element_override_count(SWMM_Engine engine, int* count);

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

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

SWMM_ENGINE_API int swmm_heat_remove_element_override(SWMM_Engine engine, int 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);

typedef struct SWMM_Heat2DStatus {
    unsigned int struct_size;
    int requested, initialized, surface_active, radiative_active, bed_active;
    int bed_model; 
    int experimental;
    double water_heat_capacity; 
    char reason[256];
} SWMM_Heat2DStatus;

SWMM_ENGINE_API int swmm_heat_get_2d_status(SWMM_Engine engine, SWMM_Heat2DStatus* status);

typedef 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 
} SWMM_Heat2DValue;

SWMM_ENGINE_API int swmm_heat_get_2d_values(SWMM_Engine engine, int kind, int first_cell, int count,
                                            double* values);
SWMM_ENGINE_API int swmm_heat_ground_source_configured(SWMM_Engine engine, int* configured);
SWMM_ENGINE_API int swmm_heat_clear_ground_source(SWMM_Engine engine);

typedef struct SWMM_GroundHeatStatus {
    unsigned int struct_size;
    int requested, initialized, aquifer_cells, standalone_cells, thermal_layers;
    int conduction_active, lateral_active, experimental;
    double water_heat_capacity; 
    char reason[256];
} SWMM_GroundHeatStatus;

SWMM_ENGINE_API int swmm_heat_get_ground_status(SWMM_Engine engine, SWMM_GroundHeatStatus* status);
typedef 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 =
        13, 
    SWMM_GROUND_HEAT_CHANNEL_CONTACT = 14, 
    SWMM_GROUND_HEAT_LID_CONTACT = 15      
} SWMM_GroundHeatValue;

SWMM_ENGINE_API int swmm_heat_get_ground_values(SWMM_Engine engine, int kind, int first_cell,
                                                int count, double* values);
typedef 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 
} SWMM_GroundHeatLayerValue;

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

typedef struct SWMM_ChannelGroundStatus {
    unsigned int struct_size;
    int requested, initialized, exchange_active, mapped_links, contact_cells, contact_intervals,
        experimental;
    char reason[256];
} SWMM_ChannelGroundStatus;

SWMM_ENGINE_API int swmm_heat_get_channel_ground_status(SWMM_Engine engine,
                                                        SWMM_ChannelGroundStatus* status);
typedef 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   
} SWMM_ChannelGroundValue;

SWMM_ENGINE_API int swmm_heat_get_channel_ground_values(SWMM_Engine engine, int kind,
                                                        int first_link, int count, double* values);
typedef struct SWMM_ChannelGroundContact {
    unsigned int struct_size;
    int link, cell, layer; 
    double begin_fraction, end_fraction, share, invert_m;
} SWMM_ChannelGroundContact;

SWMM_ENGINE_API int swmm_heat_get_channel_ground_contact(SWMM_Engine engine, int index,
                                                         SWMM_ChannelGroundContact* contact);
typedef struct SWMM_ChannelGroundPreview {
    unsigned int struct_size;
    int link, valid, contact_cells, contact_intervals;
    double length_m, covered_length_m, uncovered_length_m;
    char reason[256];
} SWMM_ChannelGroundPreview;

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);
enum { SWMM_HEAT_PREVIEW_STAGE_MESH = 1, SWMM_HEAT_PREVIEW_STAGE_MAPPING = 2 };
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);
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);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_HEAT_H */