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

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_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);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_HEAT_H */