openswmm_gw2d.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_GW2D_H
#define OPENSWMM_GW2D_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* ---- Scopes (same encoding as the [GW_*] transport API) ------------------ */
 
#define SWMM_GW2D_SCOPE_GLOBAL 0 
#define SWMM_GW2D_SCOPE_TAG 1    
#define SWMM_GW2D_SCOPE_CELL 2   
 
/* ---- Soil-characteristic laws ------------------------------------------- */
 
#define SWMM_GW2D_SOIL_RUSSO 0
#define SWMM_GW2D_SOIL_GARDNER 1
#define SWMM_GW2D_SOIL_BROOKS_COREY 2
#define SWMM_GW2D_SOIL_VAN_GENUCHTEN 3
 
/* ---- Unsaturated-zone closures ------------------------------------------ */
 
#define SWMM_GW2D_CLOSURE_AUTO (-1)
#define SWMM_GW2D_CLOSURE_CLOSED_FORM 0
#define SWMM_GW2D_CLOSURE_ENSLAVED 1
#define SWMM_GW2D_CLOSURE_SIGMA 2
 
/* ---- Exterior hydraulic boundaries ------------------------------------- */
#define SWMM_GW2D_BOUNDARY_HEAD 0
#define SWMM_GW2D_BOUNDARY_FLOW 1
typedef struct SWMM_GwBoundary {
    int cell, edge, kind;
    double value;
} SWMM_GwBoundary;

SWMM_ENGINE_API int swmm_gw2d_boundary_count(SWMM_Engine engine);
SWMM_ENGINE_API int swmm_gw2d_boundary_get(SWMM_Engine engine, int index, SWMM_GwBoundary* row,
                                           char* series, int series_len);
SWMM_ENGINE_API int swmm_gw2d_boundary_set(SWMM_Engine engine, const SWMM_GwBoundary* row,
                                           const char* series);
SWMM_ENGINE_API int swmm_gw2d_boundary_remove(SWMM_Engine engine, int index);
SWMM_ENGINE_API int swmm_gw2d_boundary_water(SWMM_Engine engine, int index, double* requested_in,
                                             double* requested_out, double* applied_in,
                                             double* applied_out);
SWMM_ENGINE_API int swmm_gw2d_boundary_species(SWMM_Engine engine, int index, int species,
                                               double* advective_in, double* advective_out,
                                               double* imposed_in, double* imposed_out);
 
/* ---- Per-cell state selectors ------------------------------------------- */
 
#define SWMM_GW2D_VAR_HG 0       
#define SWMM_GW2D_VAR_HU 1       
#define SWMM_GW2D_VAR_TABLE_EL 2 
#define SWMM_GW2D_VAR_Q0 3       
#define SWMM_GW2D_VAR_QLAT 4     
#define SWMM_GW2D_VAR_QNODE 5    
#define SWMM_GW2D_VAR_QDEEP 6    
#define SWMM_GW2D_VAR_QET 7      
#define SWMM_GW2D_VAR_DUNNE 8    
#define SWMM_GW2D_VAR_QPLUS 9    
#define SWMM_GW2D_VAR_DT_CELL 10 
#define SWMM_GW2D_VAR_TIER 11    
#define SWMM_GW2D_VAR_CLOSURE 12 
#define SWMM_GW2D_VAR_QLINK 13   
 
#define SWMM_GW2D_VAR_INFIL_CAPACITY 14 
#define SWMM_GW2D_VAR_INFIL_REMAINING                                                              \
    15 
#define SWMM_GW2D_VAR_INFIL_REFRESH 16 
#define SWMM_GW2D_VAR_INFIL_PENDING 17 
#define SWMM_GW2D_VAR_REJECT 18 
#define SWMM_GW2D_VAR_REJECT_CUM 19 
#define SWMM_GW2D_VAR_DUNNE_CUM 20  
#define SWMM_GW2D_VAR_ET_PENDING                                                                   \
    21 
#define SWMM_GW2D_VAR_ET_POTENTIAL_CUM                                                             \
    22 
#define SWMM_GW2D_VAR_ET_SURFACE_CUM 23 
#define SWMM_GW2D_VAR_ET_SOIL_CUM 24    
#define SWMM_GW2D_VAR_ET_UNUSED_CUM 25  
#define SWMM_GW2D_VAR_ET_SURFACE                                                                   \
    26 
#define SWMM_GW2D_VAR_ET_POTENTIAL 27 
#define SWMM_GW2D_VAR_ET_STRESS 28    
#define SWMM_GW2D_VAR_ET_REFRESH 29   
 
/* ---- Ledger selectors (m3, cumulative) ---------------------------------- */
 
#define SWMM_GW2D_LED_RECHARGE 0
#define SWMM_GW2D_LED_LATERAL 1
#define SWMM_GW2D_LED_DEEP 2
#define SWMM_GW2D_LED_NODE 3
#define SWMM_GW2D_LED_REJECT 13 
#define SWMM_GW2D_LED_DUNNE 4
#define SWMM_GW2D_LED_CAPRISE 5
#define SWMM_GW2D_LED_ET 6
#define SWMM_GW2D_LED_INFIL_IN 7
#define SWMM_GW2D_LED_INIT_STORAGE 8
#define SWMM_GW2D_LED_STORAGE 9       
#define SWMM_GW2D_LED_SOURCE_IN 11    
#define SWMM_GW2D_LED_BOUNDARY_IN 14  
#define SWMM_GW2D_LED_BOUNDARY_OUT 15 
#define SWMM_GW2D_LED_SOURCE_OUT 12   
#define SWMM_GW2D_LED_LINK 10         
 
/* ---- T7.5: the transported tuple (read-only results) --------------------- */

#define SWMM_GW2D_ZONE_SAT 0   
#define SWMM_GW2D_ZONE_UNSAT 1 

#define SWMM_GW2D_SPL_INIT 0
#define SWMM_GW2D_SPL_STORAGE 1 
#define SWMM_GW2D_SPL_INFIL_IN 2
#define SWMM_GW2D_SPL_NODE_IN 3
#define SWMM_GW2D_SPL_LINK_IN 4
#define SWMM_GW2D_SPL_LATERAL_NET 5
#define SWMM_GW2D_SPL_DEEP_OUT 6
#define SWMM_GW2D_SPL_NODE_OUT 7
#define SWMM_GW2D_SPL_LINK_OUT 8
#define SWMM_GW2D_SPL_DUNNE_OUT 9
#define SWMM_GW2D_SPL_ET_OUT 10
#define SWMM_GW2D_SPL_REACTED 11
#define SWMM_GW2D_SPL_SOURCE_IN 13  
#define SWMM_GW2D_SPL_SOURCE_OUT 14 
#define SWMM_GW2D_SPL_BOUNDARY_IN 15
#define SWMM_GW2D_SPL_BOUNDARY_OUT 16
#define SWMM_GW2D_SPL_BOUNDARY_FLUX_IN 17
#define SWMM_GW2D_SPL_BOUNDARY_FLUX_OUT 18
#define SWMM_GW2D_SPL_AGE_GENERATED 19
#define SWMM_GW2D_SPL_RESIDUAL 12 

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

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

SWMM_ENGINE_API int swmm_gw2d_get_cell_conc(SWMM_Engine engine, int zone, int species, double* out,
                                            int len, int* written);

SWMM_ENGINE_API int swmm_gw2d_get_layer_quality(SWMM_Engine engine, int cell, int layer,
                                                int species, double* water, double* mass,
                                                double* concentration);

SWMM_ENGINE_API int swmm_gw2d_get_species_ledger(SWMM_Engine engine, int species, int term,
                                                 double* value);
 
/* =========================================================================
 * [2D_AQUIFER_OPTIONS]
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_gw2d_process_options_set(SWMM_Engine engine, const char* et,
                                                  const char* link, const char* wilting,
                                                  int authored);

SWMM_ENGINE_API int swmm_gw2d_option_set(SWMM_Engine engine, const char* key, const char* value);
 
/* =========================================================================
 * [2D_AQUIFER] rows
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_gw2d_row_add(SWMM_Engine engine, int scope, const char* tag, int cell,
                                      double ks, double zs, double theta_s, double theta_r,
                                      double alpha);

SWMM_ENGINE_API int swmm_gw2d_row_get(SWMM_Engine engine, int index, int* scope, char* tag,
                                      int taglen, int* cell, double* ks, double* zs,
                                      double* theta_s, double* theta_r, double* alpha);

SWMM_ENGINE_API int swmm_gw2d_row_set_property(SWMM_Engine engine, int index, const char* key,
                                               double value);

SWMM_ENGINE_API int swmm_gw2d_row_get_property(SWMM_Engine engine, int index, const char* key,
                                               double* value);

SWMM_ENGINE_API int swmm_gw2d_row_remove(SWMM_Engine engine, int index);
 
/* =========================================================================
 * [2D_AQUIFER_NODE] beds
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_gw2d_node_add(SWMM_Engine engine, const char* node, int cell, double kc,
                                       double dc, double area);

SWMM_ENGINE_API int swmm_gw2d_node_get(SWMM_Engine engine, int index, char* node, int nodelen,
                                       int* cell, double* kc, double* dc, double* area);

SWMM_ENGINE_API int swmm_gw2d_node_remove(SWMM_Engine engine, int index);

SWMM_ENGINE_API int swmm_gw2d_node_get_flags(SWMM_Engine engine, int index, int* locate,
                                             int* exchange, int* automatic);

SWMM_ENGINE_API int swmm_gw2d_node_set_exchange(SWMM_Engine engine, int index, int exchange);

typedef struct SWMM_GwNodeBed {
    const char* node;
    int cell, locate, exchange, automatic;
    double kc, dc, area;
} SWMM_GwNodeBed;

typedef struct SWMM_LidNodeBottomEdit {
    int node, expected_mode, mode;
} SWMM_LidNodeBottomEdit;

SWMM_ENGINE_API int swmm_gw2d_node_replace(SWMM_Engine engine, const SWMM_GwNodeBed* expected,
                                           int expected_count, const SWMM_GwNodeBed* replacement,
                                           int count, const SWMM_LidNodeBottomEdit* bottoms,
                                           int bottom_count, int apply);
 
/* =========================================================================
 * [2D_AQUIFER_LINKS] conduit beds (closed C-API gap 2026-10-11)
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_gw2d_link_add(SWMM_Engine engine, const char* link, double kc, double dc,
                                       int exchange);

SWMM_ENGINE_API int swmm_gw2d_link_get(SWMM_Engine engine, int index, char* link, int linklen,
                                       double* kc, double* dc, int* exchange);

SWMM_ENGINE_API int swmm_gw2d_link_remove(SWMM_Engine engine, int index);
 
/* =========================================================================
 * Running state — SI throughout
 * ========================================================================= */

SWMM_ENGINE_API int swmm_gw2d_is_active(SWMM_Engine engine, int* active);

SWMM_ENGINE_API int swmm_gw2d_get_dimensions(SWMM_Engine engine, int* n_cells, int* m_layers);

SWMM_ENGINE_API int swmm_gw2d_get_cell(SWMM_Engine engine, int cell, int var, double* value);

SWMM_ENGINE_API int swmm_gw2d_get_cell_bulk(SWMM_Engine engine, int var, double* out, int len,
                                            int* written);

SWMM_ENGINE_API int swmm_gw2d_get_column(SWMM_Engine engine, int cell, double* theta, int len,
                                         int* written);

SWMM_ENGINE_API int swmm_gw2d_get_ledger(SWMM_Engine engine, int term, double* value);

SWMM_ENGINE_API int swmm_gw2d_get_continuity_error(SWMM_Engine engine, double* value);

SWMM_ENGINE_API int swmm_gw2d_get_tier_histogram(SWMM_Engine engine, long* out, int len,
                                                 int* written);
 
/* Optional recharge execution status. These flags describe the pure operator,
 * never full groundwater/device execution. Counters are process-local; component
 * restore resets them. They exclude rolled-back numerical transactions. */
#define SWMM_GW2D_OP_CLOSED_FORM_RECHARGE 1u
#define SWMM_GW2D_HOST_WATER_AND_RECEIPTS 1u
#define SWMM_GW2D_HOST_TRANSPORT 2u
#define SWMM_GW2D_HOST_REACTIONS 4u
#define SWMM_GW2D_HOST_THERMAL 8u
 
typedef struct SWMM_GwExecutionStatus {
    unsigned int struct_size; /* set to sizeof(SWMM_GwExecutionStatus) */
    int active;
    unsigned int available_operators, executed_operators, host_owned_operations;
    int effective_threads; /* 0 before host runtime initialization or on CPU */
    unsigned long long accepted_batches, accepted_cells;
    char recharge_backend[16]; /* current selection: cpu or omp */
    char profile[128];
    char detail[256];
} SWMM_GwExecutionStatus;

SWMM_ENGINE_API int swmm_gw2d_get_execution_status(SWMM_Engine engine,
                                                   SWMM_GwExecutionStatus* status);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_GW2D_H */