openswmm_engine.h

Go to the documentation of this file.

 
#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);
 
/* =========================================================================
 * 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);
 
/* =========================================================================
 * 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_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_edit.h"
 
#ifdef OPENSWMM_HAS_2D
#include "openswmm_2d.h"
#endif
 
#endif /* OPENSWMM_ENGINE_H */