openswmm_gw_transport.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_GW_TRANSPORT_H
#define OPENSWMM_GW_TRANSPORT_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---- Scopes and zones ---------------------------------------------------- */
 
#define SWMM_GW_SCOPE_GLOBAL 0 
#define SWMM_GW_SCOPE_TAG 1    
#define SWMM_GW_SCOPE_CELL 2   
 
#define SWMM_GW_ZONE_SAT 0
#define SWMM_GW_ZONE_UNSAT 1
#define SWMM_GW_ZONE_LAYER 2 
 
/* =========================================================================
 * [GW_TRANSPORT_OPTIONS]
 * =========================================================================
 * Key/value like swmm_options_get_ext: TRANSPORT_POLLUTANTS, TRANSPORT_MSX,
 * TRANSPORT_AGE, TRANSPORT_TEMPERATURE, DISPERSION, CONDUCTION,
 * SURFACE_THERMAL_BC, DEEP_THERMAL_BC, THERMAL_MIXING, C_DIFF. Values use the
 * section's own spelling; SURFACE_THERMAL_BC / DEEP_THERMAL_BC read back with
 * their argument appended ("FIXED 12.5", "GEOTHERMAL_FLUX 0.065 DEPTH 20").
 * Additive porous-model keys: THERMAL_MODEL WATER_ONLY|POROUS_EQUILIBRIUM,
 * THERMAL_LAYERS (fixed depth cells, 1..128), LATERAL_CONDUCTION (default NO),
 * THERMAL_MAX_STEP (s), WATER_THERMAL_CONDUCTIVITY and AIR_THERMAL_CONDUCTIVITY
 * (W/m/K), SURFACE_THERMAL_RESISTANCE (m2 K/W), SOIL_ET_HEAT
 * LATENT_SURFACE|SENSIBLE_ONLY. WATER_ONLY never activates dormant conduction.
 */

SWMM_ENGINE_API int swmm_gw_transport_option_get(SWMM_Engine engine, const char* key, char* buf,
                                                 int buflen);

SWMM_ENGINE_API int swmm_gw_transport_option_set(SWMM_Engine engine, const char* key,
                                                 const char* value);

SWMM_ENGINE_API int swmm_gw_transport_authored(SWMM_Engine engine);
 
/* =========================================================================
 * [GW_TRANSPORT_PARAMS]
 * ========================================================================= */
 
typedef struct SWMM_GwParams {
    int scope;       
    int cell;        
    double rho_s;    
    double c_s;      
    double lambda_s; 
    double a_s;      
    double alpha_L;  
    double alpha_T;  
    double D_m;      
    double D_v;      
    double geo_flux; 
} SWMM_GwParams;

SWMM_ENGINE_API int swmm_gw_params_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw_params_get(SWMM_Engine engine, int idx, SWMM_GwParams* row,
                                       char* tag_buf, int tag_len);
SWMM_ENGINE_API int swmm_gw_params_set(SWMM_Engine engine, const SWMM_GwParams* row,
                                       const char* tag);
SWMM_ENGINE_API int swmm_gw_params_remove(SWMM_Engine engine, int idx);
 
/* =========================================================================
 * [GW_SORPTION]
 * ========================================================================= */

SWMM_ENGINE_API int swmm_gw_sorption_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw_sorption_get(SWMM_Engine engine, int idx, int* scope, char* tag_buf,
                                         int tag_len, int* cell, char* species_buf, int species_len,
                                         double* kd, double* decay);
SWMM_ENGINE_API int swmm_gw_sorption_set(SWMM_Engine engine, int scope, const char* tag, int cell,
                                         const char* species, double kd, double decay);
SWMM_ENGINE_API int swmm_gw_sorption_remove(SWMM_Engine engine, int idx);
 
/* =========================================================================
 * [GW_INITIAL_QUALITY]
 * ========================================================================= */

SWMM_ENGINE_API int swmm_gw_init_quality_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw_init_quality_get(SWMM_Engine engine, int idx, int* scope, char* tag_buf,
                                             int tag_len, int* cell, int* zone, int* layer,
                                             char* species_buf, int species_len, double* value);
SWMM_ENGINE_API int swmm_gw_init_quality_set(SWMM_Engine engine, int scope, const char* tag,
                                             int cell, int zone, int layer, const char* species,
                                             double value);
SWMM_ENGINE_API int swmm_gw_init_quality_remove(SWMM_Engine engine, int idx);
SWMM_ENGINE_API int swmm_gw_init_quality_file_get(SWMM_Engine engine, char* buf, int buflen);
SWMM_ENGINE_API int swmm_gw_init_quality_file_set(SWMM_Engine engine, const char* path);
 
/* =========================================================================
 * [GW_BOUNDARY_QUALITY]
 * =========================================================================
 * `kind` is "CONC", "TS", "MASSFLUX" or "HEATFLUX". A row carries either a
 * constant value or a series name (never both).
 */

SWMM_ENGINE_API int swmm_gw_boundary_quality_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw_boundary_quality_get(SWMM_Engine engine, int idx, int* cell, int* edge,
                                                 char* species_buf, int species_len, char* kind_buf,
                                                 int kind_len, double* value, char* ts_buf,
                                                 int ts_len);
SWMM_ENGINE_API int swmm_gw_boundary_quality_set(SWMM_Engine engine, int cell, int edge,
                                                 const char* species, const char* kind,
                                                 double value, const char* ts_name);
SWMM_ENGINE_API int swmm_gw_boundary_quality_remove(SWMM_Engine engine, int idx);
 
/* =========================================================================
 * [GW_SOURCES]
 * ========================================================================= */

SWMM_ENGINE_API int swmm_gw_source_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw_source_get(SWMM_Engine engine, int idx, char* name_buf, int name_len,
                                       int* scope, char* tag_buf, int tag_len, int* cell,
                                       double* flow, char* flow_ts_buf, int flow_ts_len);
SWMM_ENGINE_API int swmm_gw_source_set(SWMM_Engine engine, const char* name, int scope,
                                       const char* tag, int cell, double flow, const char* flow_ts);
SWMM_ENGINE_API int swmm_gw_source_scale_get(SWMM_Engine engine, int idx, double* value);
SWMM_ENGINE_API int swmm_gw_source_scale_set(SWMM_Engine engine, int idx, double value);
SWMM_ENGINE_API int swmm_gw_source_remove(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_gw_source_species_count(SWMM_Engine engine, int src_idx);
SWMM_ENGINE_API int swmm_gw_source_species_get(SWMM_Engine engine, int src_idx, int term_idx,
                                               char* species_buf, int species_len, char* kind_buf,
                                               int kind_len, double* value, char* ts_buf,
                                               int ts_len);
SWMM_ENGINE_API int swmm_gw_source_species_set(SWMM_Engine engine, int src_idx, const char* species,
                                               const char* kind, double value, const char* ts_name);
SWMM_ENGINE_API int swmm_gw_source_species_remove(SWMM_Engine engine, int src_idx, int term_idx);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_GW_TRANSPORT_H */