openswmm_model.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_MODEL_H
#define OPENSWMM_MODEL_H
 
#include "openswmm_engine.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Model building — programmatic construction (state guard: BUILDING only)
 * ========================================================================= */

SWMM_ENGINE_API SWMM_Engine swmm_engine_new(void);
 
/* =========================================================================
 * Model finalisation and validation
 * ========================================================================= */

SWMM_ENGINE_API int swmm_validate_model(SWMM_Engine engine);

SWMM_ENGINE_API int swmm_finalize_model(SWMM_Engine engine);
 
/* =========================================================================
 * Model serialisation
 * ========================================================================= */

SWMM_ENGINE_API int swmm_model_write(SWMM_Engine engine, const char* new_inp_path);

typedef const char* (*SWMM_StageOutputCallback)(void* user_data, const char* final_path, int kind);
SWMM_ENGINE_API int swmm_model_write_staged(SWMM_Engine engine, const char* final_inp_path,
                                            SWMM_StageOutputCallback mapper, void* user_data);

typedef enum SWMM_InpProfile {
    SWMM_INP_PROFILE_FULL = 0,       
    SWMM_INP_PROFILE_SWMM5 = 1,      
    SWMM_INP_PROFILE_SWMM5_STOCK = 2 
} SWMM_InpProfile;

SWMM_ENGINE_API int swmm_model_write_compat(SWMM_Engine engine, const char* new_inp_path,
                                            int profile);

SWMM_ENGINE_API int swmm_model_write_with_plugin(SWMM_Engine engine, const char* new_path,
                                                 const char* output_plugin_id);
 
/* =========================================================================
 * [PLUGINS] section access (Slice AA-3.1 Phase B)
 *
 * The [PLUGINS] section of an .inp file is a list of rows, one per
 * plugin to load.  Each row is `path arg1 arg2 …` where `path` resolves
 * via the same logic as the input plugin lib (a library path, an id, or
 * an `id:version` pair) and the trailing tokens are passed to the
 * plugin's initialize() method as `init_args`.
 *
 * The accessors below let a host (GUI) read, mutate, and remove rows
 * without re-parsing the .inp file.  Plugins themselves are
 * (re-)resolved by PluginFactory at swmm_engine_open / swmm_model_write
 * time — these accessors only mutate the in-memory `plugin_specs` list.
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_plugin_get(SWMM_Engine engine, int idx, char* path_buf, int path_buf_sz,
                                    char* args_buf, int args_buf_sz);

SWMM_ENGINE_API int swmm_plugin_set(SWMM_Engine engine, const char* path_or_id, const char* args);

SWMM_ENGINE_API int swmm_plugin_remove(SWMM_Engine engine, const char* path_or_id);
 
/* =========================================================================
 * [FILES] section access (Slice AA-3 follow-up — secondary file refs)
 *
 * Read / write the legacy SWMM5 `[FILES]` section: rainfall, runoff,
 * RDII, inflows, outflows, and hot-start file references.  The
 * accessors are keyed by an uppercase string so callers don't depend
 * on the field layout of `FilesSpec`.
 *
 * Recognised keys (case-insensitive):
 *   "RAINFALL_PATH"          / "RAINFALL_MODE"
 *   "RUNOFF_PATH"            / "RUNOFF_MODE"
 *   "RDII_PATH"              / "RDII_MODE"
 *   "INFLOWS_PATH"
 *   "OUTFLOWS_PATH"
 *   "HOTSTART_USE_PATH"
 *   "HOTSTART_SAVE_PATH"     / "HOTSTART_SAVE_DATETIME"
 *
 * `*_MODE` keys take "SAVE" / "USE" / "" (empty clears the slot).
 * `HOTSTART_SAVE_DATETIME` is a SWMM decimal-day floating-point string
 * (0 == unset, write at end of run).
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_files_set(SWMM_Engine engine, const char* key, const char* value);
 
/* =========================================================================
 * External-file path slots — typed, broader API (Slice IO-9)
 * =========================================================================
 *
 * Reaches every external-file slot in the model — not just the [FILES]
 * section — so the GUI's portability normalizer can walk a uniform list
 * before save without per-role plumbing.
 *
 * Each slot carries both:
 *   - the original token as it appeared in the source `.inp`
 *     (relative-or-absolute, with whichever separators the author used);
 *   - the resolved absolute path the engine uses for `fopen`.
 *
 * The slot getter exposes both strings to the caller; the slot setter
 * updates the original token and clears the cached absolute resolution
 * (PostParseResolver re-fills it the next time it runs).
 *
 * See openswmm.gui/docs/IO_PORTABILITY_PLAN.md §3.3 for the storage model
 * and §3.7 for the GUI editor contract.
 * ========================================================================= */

typedef enum SWMM_FilePathRole {
    /* Scalar slots — `owner` ignored. */
    SWMM_FILE_RAINFALL = 1,     
    SWMM_FILE_RUNOFF = 2,       
    SWMM_FILE_RDII = 3,         
    SWMM_FILE_INFLOWS = 4,      
    SWMM_FILE_OUTFLOWS = 5,     
    SWMM_FILE_HOTSTART_USE = 6, 
    SWMM_FILE_CLIMATE_TEMP = 7, 
 
    /* Vector slots — `owner` selects the entry. */
    SWMM_FILE_HOTSTART_SAVE = 8,    
    SWMM_FILE_RAINGAGE_DATA = 9,    
    SWMM_FILE_TIMESERIES_DATA = 10, 
 
    /* Scalar slots — `owner` ignored. Unavailable (SWMM_ERR_BADPARAM) in
     * builds without 2D support. */
    SWMM_FILE_MESH_2D = 11,   
    SWMM_FILE_OUTPUT_2D = 12, 
 
    /* Vector slot — `owner` selects the entry. */
    SWMM_FILE_LID_REPORT = 13 
} SWMM_FilePathRole;

SWMM_ENGINE_API int swmm_file_path_get(SWMM_Engine engine, SWMM_FilePathRole role,
                                       const char* owner, char* absolute_buf, int absolute_buflen,
                                       char* original_buf, int original_buflen);

SWMM_ENGINE_API int swmm_file_path_set(SWMM_Engine engine, SWMM_FilePathRole role,
                                       const char* owner, const char* new_path);
 
/* =========================================================================
 * Title / notes access
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_title_get_line(SWMM_Engine engine, int index, char* buf, int buflen);

SWMM_ENGINE_API int swmm_title_add_line(SWMM_Engine engine, const char* line);

SWMM_ENGINE_API int swmm_title_set(SWMM_Engine engine, const char* text);

SWMM_ENGINE_API int swmm_title_clear(SWMM_Engine engine);
 
/* =========================================================================
 * OPTIONS access
 * ========================================================================= */

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

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

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

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

SWMM_ENGINE_API int swmm_options_key_count(void);

SWMM_ENGINE_API int swmm_options_key_at(int index, char* buf, int buflen);

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

SWMM_ENGINE_API int swmm_options_ext_key_at(SWMM_Engine engine, int index, char* buf,
                                            int buflen);

SWMM_ENGINE_API int swmm_get_crs(SWMM_Engine engine, char* buf, int buflen);
 
/* =========================================================================
 * Typed time-control accessors
 *
 * Date values are SWMM OADate doubles: the integer part is days since
 * 1899-12-30 and the fractional part is the time-of-day fraction.
 * ========================================================================= */

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

SWMM_ENGINE_API int swmm_options_set_start_date(SWMM_Engine engine, double value);

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

SWMM_ENGINE_API int swmm_options_set_end_date(SWMM_Engine engine, double value);

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

SWMM_ENGINE_API int swmm_options_set_report_start(SWMM_Engine engine, double value);
 
/* =========================================================================
 * User flags
 *
 * Flag names are case-insensitive: they are stored uppercase, matching the
 * [USER_FLAGS] INP handler.
 * ========================================================================= */

SWMM_ENGINE_API int swmm_userflag_get_bool(SWMM_Engine engine, const char* name, int* value);

SWMM_ENGINE_API int swmm_userflag_get_int(SWMM_Engine engine, const char* name, int* value);

SWMM_ENGINE_API int swmm_userflag_get_real(SWMM_Engine engine, const char* name, double* value);

SWMM_ENGINE_API int swmm_userflag_set_bool(SWMM_Engine engine, const char* name, int value);

SWMM_ENGINE_API int swmm_userflag_set_int(SWMM_Engine engine, const char* name, int value);

SWMM_ENGINE_API int swmm_userflag_set_real(SWMM_Engine engine, const char* name, double value);
 
/* -------------------------------------------------------------------------
 * User flag schema definitions ([USER_FLAGS]) and per-object values
 * ([USER_FLAG_VALUES]).
 *
 * Flag types (matching openswmm::UserFlagType):
 *   0 = BOOLEAN, 1 = INTEGER, 2 = REAL, 3 = STRING.
 *
 * Per-object values use string form symmetric with the INP encoding:
 * BOOLEAN as YES/NO, INTEGER as %d, REAL as %g, STRING verbatim (no quotes).
 * Object types and flag names are case-insensitive (stored uppercase);
 * object names are case-preserved.
 * ------------------------------------------------------------------------- */

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

SWMM_ENGINE_API int swmm_userflag_def_get(SWMM_Engine engine, int index, char* name_buf,
                                          int name_buflen, int* type, char* desc_buf,
                                          int desc_buflen);

SWMM_ENGINE_API int swmm_userflag_define(SWMM_Engine engine, const char* name, int type,
                                         const char* description);

SWMM_ENGINE_API int swmm_userflag_undefine(SWMM_Engine engine, const char* name);

SWMM_ENGINE_API int swmm_userflag_value_get(SWMM_Engine engine, const char* obj_type,
                                            const char* obj_name, const char* flag_name, char* buf,
                                            int buflen, int* found);

SWMM_ENGINE_API int swmm_userflag_value_set(SWMM_Engine engine, const char* obj_type,
                                            const char* obj_name, const char* flag_name,
                                            const char* value);

SWMM_ENGINE_API int swmm_userflag_value_clear(SWMM_Engine engine, const char* obj_type,
                                              const char* obj_name, const char* flag_name);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* OPENSWMM_MODEL_H */