openswmm_engine.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_ENGINE_H
#define OPENSWMM_ENGINE_H
 
#include "openswmm_callbacks.h"
 
/* =========================================================================
 * Export macro
 * ========================================================================= */
 
#ifdef OPENSWMM_ENGINE_STATIC
#  define SWMM_ENGINE_API
#else
#  ifdef _WIN32
#    ifdef openswmm_engine_EXPORTS
#      define SWMM_ENGINE_API __declspec(dllexport)
#    else
#      define SWMM_ENGINE_API __declspec(dllimport)
#    endif
#  else
#    define SWMM_ENGINE_API __attribute__((visibility("default")))
#  endif
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Error codes
 * ========================================================================= */
 
typedef enum SWMM_ErrorCode {
    SWMM_OK              =  0,
    SWMM_ERR_NOMEM       =  1,
    SWMM_ERR_INPFILE     =  2,
    SWMM_ERR_RPTFILE     =  3,
    SWMM_ERR_OUTFILE     =  4,
    SWMM_ERR_PARSE       =  5,
    SWMM_ERR_LIFECYCLE   =  6,
    SWMM_ERR_BADHANDLE   =  7,
    SWMM_ERR_BADINDEX    =  8,
    SWMM_ERR_BADPARAM    =  9,
    SWMM_ERR_PLUGIN      = 10,
    SWMM_ERR_IO          = 11,
    SWMM_ERR_HOTSTART    = 12,
    SWMM_ERR_CRS         = 13,
    SWMM_ERR_NUMERICAL   = 14,
    SWMM_ERR_DEPENDENCY  = 15,  
    SWMM_ERR_INTERNAL    = 99
} SWMM_ErrorCode;
 
typedef enum SWMM_WarnCode {
    SWMM_WARN_NONE              = 0,
    SWMM_WARN_HOTSTART_MISSING  = 1,
    SWMM_WARN_UNKNOWN_SECTION   = 2,
    SWMM_WARN_UNKNOWN_OPTION    = 3,
    SWMM_WARN_DEPRECATED_KW     = 4,
    SWMM_WARN_PLUGIN_INIT       = 5,
    SWMM_WARN_NUMERICAL         = 6,
    SWMM_WARN_STABILITY_LIMIT   = 7
} SWMM_WarnCode;
 
/* =========================================================================
 * Engine lifecycle state
 * ========================================================================= */
 
typedef enum SWMM_EngineState {
    SWMM_STATE_NONE        = 0,
    SWMM_STATE_CREATED     = 1,
    SWMM_STATE_OPENED      = 2,
    SWMM_STATE_INITIALIZED = 3,
    SWMM_STATE_STARTED     = 4,
    SWMM_STATE_RUNNING     = 5,
    SWMM_STATE_ENDED       = 6,
    SWMM_STATE_CLOSED      = 7,
    SWMM_STATE_BUILDING    = 8  
} SWMM_EngineState;
 
/* =========================================================================
 * Object type identifiers
 * ========================================================================= */
 
typedef enum SWMM_ObjectType {
    SWMM_OBJ_GAGE      = 0,
    SWMM_OBJ_SUBCATCH  = 1,
    SWMM_OBJ_NODE      = 2,
    SWMM_OBJ_LINK      = 3,
    SWMM_OBJ_POLLUT    = 4,
    SWMM_OBJ_LANDUSE   = 5,
    SWMM_OBJ_TIMESER   = 6,
    SWMM_OBJ_TABLE     = 7,
    SWMM_OBJ_RDII      = 8,
    SWMM_OBJ_UNITHYD   = 9,
    SWMM_OBJ_SNOWMELT  = 10,
    SWMM_OBJ_SHAPE     = 11,
    SWMM_OBJ_LID       = 12
} SWMM_ObjectType;
 
/* =========================================================================
 * Engine lifecycle functions
 * ========================================================================= */

SWMM_ENGINE_API SWMM_Engine swmm_engine_create(void);

SWMM_ENGINE_API int swmm_engine_open(SWMM_Engine engine,
                                      const char* inp, const char* rpt, const char* out,
                                      const char* input_plugin_lib);

SWMM_ENGINE_API int swmm_engine_initialize(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_engine_start(SWMM_Engine engine, int save_results);

SWMM_ENGINE_API int swmm_engine_step(SWMM_Engine engine, double* elapsed_time);

SWMM_ENGINE_API int swmm_engine_stride(SWMM_Engine engine, int n_steps, double* elapsed_time);

SWMM_ENGINE_API int swmm_engine_end(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_engine_report(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_engine_close(SWMM_Engine engine);

SWMM_ENGINE_API void swmm_engine_destroy(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_engine_get_state(SWMM_Engine engine, int* state);
 
/* =========================================================================
 * Convenience run functions
 * ========================================================================= */

SWMM_ENGINE_API int swmm_engine_run(const char* inp, const char* rpt, const char* out,
                                     const char* input_plugin_lib);

SWMM_ENGINE_API int swmm_engine_run_with_callback(
    const char* inp, const char* rpt, const char* out,
    const char* input_plugin_lib,
    SWMM_ProgressCallback callback, void* user_data);
 
/* =========================================================================
 * Callback registration
 * ========================================================================= */
 
SWMM_ENGINE_API int swmm_set_progress_callback  (SWMM_Engine engine,
                                                   SWMM_ProgressCallback  callback, void* user_data);
SWMM_ENGINE_API int swmm_set_warning_callback   (SWMM_Engine engine,
                                                   SWMM_WarningCallback   callback, void* user_data);
SWMM_ENGINE_API int swmm_set_step_begin_callback(SWMM_Engine engine,
                                                   SWMM_StepBeginCallback callback, void* user_data);
SWMM_ENGINE_API int swmm_set_step_end_callback  (SWMM_Engine engine,
                                                   SWMM_StepEndCallback   callback, void* user_data);
 
/* =========================================================================
 * Error reporting
 * ========================================================================= */
 
SWMM_ENGINE_API int         swmm_get_last_error    (SWMM_Engine engine);
SWMM_ENGINE_API const char* swmm_get_last_error_msg(SWMM_Engine engine);
SWMM_ENGINE_API const char* swmm_error_message     (int code);

SWMM_ENGINE_API void        swmm_engine_set_lenient_open(SWMM_Engine engine, int on);
 
/* Enumerate the errors/warnings accumulated on the engine during open (e.g.
 * after a lenient open). Index is 0-based; out-of-range returns "". */
SWMM_ENGINE_API int         swmm_get_error_count   (SWMM_Engine engine);
SWMM_ENGINE_API const char* swmm_get_error_at      (SWMM_Engine engine, int index);
SWMM_ENGINE_API int         swmm_get_warning_count (SWMM_Engine engine);
SWMM_ENGINE_API const char* swmm_get_warning_at    (SWMM_Engine engine, int index);
 
/* =========================================================================
 * Thread capability query (engine-independent)
 * ========================================================================= */

typedef struct {
    int logical_cpus;       
    int omp_max_threads;    
    int omp_available;      
    int perf_cores;         
    int kokkos_omp_threads; 
} SWMM_ThreadInfo;

SWMM_ENGINE_API int swmm_get_thread_info(SWMM_ThreadInfo* out);

SWMM_ENGINE_API int swmm_get_effective_threads(SWMM_Engine engine, int threads_option,
                                               int* global_threads, int* dw_threads,
                                               int* twod_threads);
 
/* =========================================================================
 * Transport matrix (E2, 2026-09-07) — which species classes run in which
 * domain, and why not. Engine-computed from the open model's options
 * (IGNORE_QUALITY, WATER_AGE, HEAT_TRANSPORT, the reactions component,
 * IGNORE_2D and the [2D_OPTIONS] TRANSPORT_* keys); the .rpt prints the
 * same table. Valid after swmm_engine_open; re-read after option edits.
 * ========================================================================= */
 
#define SWMM_TRANSPORT_DOMAIN_RUNOFF       0
#define SWMM_TRANSPORT_DOMAIN_GROUNDWATER  1
#define SWMM_TRANSPORT_DOMAIN_NETWORK_1D   2
#define SWMM_TRANSPORT_DOMAIN_SURFACE_2D   3
#define SWMM_TRANSPORT_DOMAIN_COUNT        4
 
#define SWMM_TRANSPORT_CLASS_POLLUTANTS    0
#define SWMM_TRANSPORT_CLASS_MSX           1
#define SWMM_TRANSPORT_CLASS_AGE           2
#define SWMM_TRANSPORT_CLASS_TEMPERATURE   3
#define SWMM_TRANSPORT_CLASS_COUNT         4
 
#define SWMM_TRANSPORT_ENABLED             0
#define SWMM_TRANSPORT_DISABLED_BY_USER    1   
#define SWMM_TRANSPORT_UNAVAILABLE         2   
 
typedef struct SWMM_TransportCell {
    int  state;        
    int  count;        
    char reason[96];   
} SWMM_TransportCell;
 
typedef struct SWMM_TransportMatrix {
    SWMM_TransportCell cell[SWMM_TRANSPORT_DOMAIN_COUNT][SWMM_TRANSPORT_CLASS_COUNT];
} SWMM_TransportMatrix;

SWMM_ENGINE_API int swmm_get_transport_matrix(SWMM_Engine engine, SWMM_TransportMatrix* out);

SWMM_ENGINE_API const char* swmm_transport_domain_name(int domain);
SWMM_ENGINE_API const char* swmm_transport_class_name(int species_class);
 
/* =========================================================================
 * Simulation timing
 * ========================================================================= */
 
SWMM_ENGINE_API int swmm_get_start_time  (SWMM_Engine engine, double* start);
SWMM_ENGINE_API int swmm_get_end_time    (SWMM_Engine engine, double* end);
SWMM_ENGINE_API int swmm_get_current_time(SWMM_Engine engine, double* current);
SWMM_ENGINE_API int swmm_get_routing_step(SWMM_Engine engine, double* dt);
 
/* =========================================================================
 * Unit system query
 * =========================================================================
 * All C API getters return — and all setters accept — values in the project's
 * DISPLAY units, selected by [OPTIONS] FLOW_UNITS. These accessors report which
 * units are in effect so callers (bindings, coupling) can interpret values.
 */

SWMM_ENGINE_API int swmm_get_flow_units(SWMM_Engine engine, int* flow_units);

SWMM_ENGINE_API int swmm_get_unit_system(SWMM_Engine engine, int* unit_system);
 
/* =========================================================================
 * Routing event and steady-state status
 * ========================================================================= */

SWMM_ENGINE_API int swmm_is_between_events(SWMM_Engine engine, int* is_between);

SWMM_ENGINE_API int swmm_get_event_count(SWMM_Engine engine, int* count);
 
/* -------------------------------------------------------------------------
 * [EVENTS] section accessors (Slice CW — added 2026-05-21).
 *
 * Mirrors the per-row reader in `handle_events` (InfraHandler.cpp). All times
 * are DateTime decimal days (consistent with `swmm_get_start_time` etc.).
 * `swmm_events_count` is a synonym of the legacy `swmm_get_event_count` and
 * is provided so the [EVENTS] surface is self-consistent.
 * ------------------------------------------------------------------------- */

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

SWMM_ENGINE_API int swmm_events_get(SWMM_Engine engine, int idx,
                                    double* start, double* end);

SWMM_ENGINE_API int swmm_events_set(SWMM_Engine engine, int idx,
                                    double start, double end);

SWMM_ENGINE_API int swmm_events_add(SWMM_Engine engine,
                                    double start, double end, int* out_idx);

SWMM_ENGINE_API int swmm_events_remove(SWMM_Engine engine, int idx);

SWMM_ENGINE_API int swmm_events_clear(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_get_steady_state_skip(SWMM_Engine engine, int* enabled);
SWMM_ENGINE_API int swmm_set_steady_state_skip(SWMM_Engine engine, int enabled);
 
/* =========================================================================
 * Phase 1b: Runoff interface file (legacy "Frunoff").
 *
 * Persists per-subcatchment runoff snapshots to a binary file so the
 * runoff phase of a long simulation can be cached and replayed in a
 * downstream routing-only run.  Mirrors the legacy SWMM-5 file format
 * (see src/engine/hydrology/RunoffInterface.hpp).
 *
 * SAVE mode is fully integrated: open the file in SAVE before
 * @c swmm_engine_start, run the simulation as normal, then close.  The
 * engine emits one record per runoff substep automatically.
 *
 * USE mode currently exposes the file but does NOT yet auto-skip the
 * engine's runoff computation — callers must invoke
 * @ref swmm_runoff_iface_read_step between simulation steps and
 * understand that the engine will overwrite the loaded state if runoff
 * still runs.  Full USE-mode auto-skip is tracked as a follow-up.
 *
 * @since 6.0.0
 * ========================================================================= */

SWMM_ENGINE_API int swmm_runoff_iface_open_write(SWMM_Engine engine, const char* path);

SWMM_ENGINE_API int swmm_runoff_iface_open_read(SWMM_Engine engine, const char* path);

SWMM_ENGINE_API int swmm_runoff_iface_save_step(SWMM_Engine engine, double dt);

SWMM_ENGINE_API int swmm_runoff_iface_read_step(SWMM_Engine engine, int* has_data);

SWMM_ENGINE_API int swmm_runoff_iface_close(SWMM_Engine engine);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
/* =========================================================================
 * Master include — pull in all domain headers
 *
 * Each domain header includes openswmm_engine.h itself (for SWMM_ENGINE_API
 * and the handle typedef), so include guards prevent recursion.
 * ========================================================================= */
 
#include "openswmm_datetime.h"
#include "openswmm_model.h"
#include "openswmm_nodes.h"
#include "openswmm_links.h"
#include "openswmm_subcatchments.h"
#include "openswmm_gages.h"
#include "openswmm_massbalance.h"
#include "openswmm_hotstart.h"
#include "openswmm_spatial.h"
#include "openswmm_pollutants.h"
#include "openswmm_initial_quality.h"
#include "openswmm_reactions.h"
#include "openswmm_process_components.h"
#include "openswmm_tables.h"
#include "openswmm_inflows.h"
#include "openswmm_controls.h"
#include "openswmm_infrastructure.h"
#include "openswmm_quality.h"
#include "openswmm_statistics.h"
#include "openswmm_forcing.h"
#include "openswmm_climate.h"
#include "openswmm_edit.h"
 
#ifdef OPENSWMM_HAS_2D
#include "openswmm_2d.h"
#include "openswmm_gw_transport.h"   /* U4 (2026-09-07) */
#endif
 
#endif /* OPENSWMM_ENGINE_H */