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_CANCELLED = 16,  
    SWMM_ERR_BUFSIZE = 17,    
    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 const char *swmm_engine_abi_tag(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_open_metadata(SWMM_Engine engine, const char* inp);

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_advance_to(SWMM_Engine engine, double target_seconds,
                                           double* actual_seconds);
SWMM_ENGINE_API int swmm_engine_get_elapsed_seconds(SWMM_Engine engine, double* seconds);
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);

typedef struct SWMM_TransportDraft {
    int ignore_quality, heat, age, ignore_2d;
    int surface_class[SWMM_TRANSPORT_CLASS_COUNT];
    int groundwater;
} SWMM_TransportDraft;

SWMM_ENGINE_API int swmm_preview_transport_matrix(SWMM_Engine engine,
                                                  const SWMM_TransportDraft* draft,
                                                  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
 * =========================================================================
 * Most legacy model-object getters/setters use project DISPLAY units selected
 * by [OPTIONS] FLOW_UNITS. Individual APIs explicitly document exceptions,
 * including SI mesh/coupling quantities and elapsed/calendar time units. These
 * accessors report the project display-unit selection.
 */

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"
#include "openswmm_checkpoint.h"
 
#ifdef OPENSWMM_HAS_2D
#include "openswmm_2d.h"
#include "openswmm_gw_transport.h" /* U4 (2026-09-07) */
#endif
 
#endif /* OPENSWMM_ENGINE_H */