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 enum SWMM_InpProfile {
    SWMM_INP_PROFILE_FULL  = 0,  
    SWMM_INP_PROFILE_SWMM5 = 1   
} 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_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 */