 |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
|
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
C API implementation — model building, options, user flags, CRS. More...
#include <algorithm>#include <iterator>#include <string>#include <type_traits>#include <utility>#include <vector>#include "openswmm_api_common.hpp"#include "InpWriter.hpp"#include "DateTime.hpp"#include "charconv_compat.hpp"#include "../input/Tokenizer.hpp"#include "../input/InputParseUtils.hpp"#include "../input/PostParseResolver.hpp"#include "../../../include/openswmm/engine/openswmm_model.h"#include "../../../include/openswmm/engine/openswmm_hotstart.h"#include "../../../include/openswmm/plugin_sdk/IInputPlugin.hpp"#include "../../../include/openswmm/plugin_sdk/IPluginComponentInfo.hpp"#include <cstdio>#include <cstdlib>Functions | |
| SWMM_ENGINE_API SWMM_Engine | swmm_engine_new (void) |
| Create an empty programmatically editable engine in SWMM_STATE_BUILDING. | |
| SWMM_ENGINE_API int | swmm_validate_model (SWMM_Engine engine) |
| Check the minimal programmatic topology prerequisites without changing state. | |
| SWMM_ENGINE_API int | swmm_finalize_model (SWMM_Engine engine) |
| Resolve and initialize a programmatically built model. | |
| SWMM_ENGINE_API int | swmm_model_write (SWMM_Engine engine, const char *new_inp_path) |
| Serialize the current model with the built-in INP writer. | |
| SWMM_ENGINE_API int | swmm_model_write_staged (SWMM_Engine engine, const char *final_inp_path, SWMM_StageOutputCallback mapper, void *user_data) |
| Serialize built-in INP outputs through a mandatory caller staging mapper. | |
| SWMM_ENGINE_API int | swmm_model_write_compat (SWMM_Engine engine, const char *new_inp_path, int profile) |
| Serialize the model to a selected INP compatibility profile. | |
| SWMM_ENGINE_API int | swmm_model_write_with_plugin (SWMM_Engine engine, const char *new_path, const char *output_plugin_id) |
| Serialize through a transient named input/writer plugin. | |
| SWMM_ENGINE_API int | swmm_plugins_count (SWMM_Engine engine, int *count) |
| Count stored [PLUGINS] specifications. | |
| 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) |
| Read one stored [PLUGINS] row without resolving/loading it. | |
| SWMM_ENGINE_API int | swmm_plugin_set (SWMM_Engine engine, const char *path_or_id, const char *args) |
| Add or replace a copied plugin specification by exact path/ID key. | |
| SWMM_ENGINE_API int | swmm_plugin_remove (SWMM_Engine engine, const char *path_or_id) |
| Remove the first exact-matching stored plugin specification. | |
| SWMM_ENGINE_API int | swmm_files_get (SWMM_Engine engine, const char *key, char *buf, int buflen) |
| Read a legacy [FILES] authoring field by case-insensitive key. | |
| SWMM_ENGINE_API int | swmm_files_set (SWMM_Engine engine, const char *key, const char *value) |
| Set one copied legacy [FILES] authoring field. | |
| 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) |
| Read resolved and original strings for an existing external-file slot. | |
| SWMM_ENGINE_API int | swmm_file_path_set (SWMM_Engine engine, SWMM_FilePathRole role, const char *owner, const char *new_path) |
| Replace an external-file token and invalidate its cached absolute path. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_count (SWMM_Engine engine, int *count) |
| Count scheduled SAVE HOTSTART authoring entries. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_get_path (SWMM_Engine engine, int idx, char *buf, int buflen) |
| Copy the authored path of one scheduled save entry. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_get_datetime (SWMM_Engine engine, int idx, double *datetime) |
| Read the scheduled calendar date of one save entry. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_set_path (SWMM_Engine engine, int idx, const char *path) |
| Replace a scheduled save path without removing its row. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_set_datetime (SWMM_Engine engine, int idx, double datetime) |
| Assign a scheduled save calendar date directly. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_get_format (SWMM_Engine engine, int idx, int *format) |
| Read the authored format selector of one scheduled save. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_set_format (SWMM_Engine engine, int idx, int format) |
| Select the authored format of an existing scheduled save. | |
| SWMM_ENGINE_API int | swmm_hotstart_legacy_omits (SWMM_Engine engine, int *flags) |
| Report selected model features that legacy routing hotstarts cannot retain. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_add (SWMM_Engine engine, const char *path, double datetime) |
| Append an AUTO-format scheduled save authoring entry. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_remove (SWMM_Engine engine, int idx) |
| Remove a scheduled save entry and shift later indices down. | |
| SWMM_ENGINE_API int | swmm_hotstart_saves_clear (SWMM_Engine engine) |
| Remove all scheduled save authoring entries. | |
| SWMM_ENGINE_API int | swmm_title_get_count (SWMM_Engine engine, int *count) |
| Count stored [TITLE] note lines. | |
| SWMM_ENGINE_API int | swmm_title_get_line (SWMM_Engine engine, int index, char *buf, int buflen) |
| Copy one stored title/note line. | |
| SWMM_ENGINE_API int | swmm_title_add_line (SWMM_Engine engine, const char *line) |
| Append a copied title/note entry. | |
| SWMM_ENGINE_API int | swmm_title_set (SWMM_Engine engine, const char *text) |
| Replace title entries by splitting copied text at newline characters. | |
| SWMM_ENGINE_API int | swmm_title_clear (SWMM_Engine engine) |
| Remove all title/note entries. | |
| SWMM_ENGINE_API int | swmm_options_get (SWMM_Engine engine, const char *key, char *buf, int buflen) |
| Format a supported standard option in input-compatible string form. | |
| SWMM_ENGINE_API int | swmm_options_set (SWMM_Engine engine, const char *key, const char *value) |
| Parse and assign a supported standard simulation option. | |
| SWMM_ENGINE_API int | swmm_options_get_ext (SWMM_Engine engine, const char *key, char *buf, int buflen) |
| Read a live 2D option or stored extension string. | |
| SWMM_ENGINE_API int | swmm_options_set_ext (SWMM_Engine engine, const char *key, const char *value) |
| Set a recognized 2D option or retain a generic extension key/value. | |
| SWMM_ENGINE_API int | swmm_options_key_count (void) |
| Number of standard option keys accepted by swmm_options_get() and swmm_options_set(). | |
| SWMM_ENGINE_API int | swmm_options_key_at (int index, char *buf, int buflen) |
| Copy one standard option key by position. | |
| SWMM_ENGINE_API int | swmm_options_ext_key_count (SWMM_Engine engine, int *count) |
| Number of keys swmm_options_get_ext() currently accepts on this engine. | |
| SWMM_ENGINE_API int | swmm_options_ext_key_at (SWMM_Engine engine, int index, char *buf, int buflen) |
| Copy one key accepted by swmm_options_get_ext() by position. | |
| SWMM_ENGINE_API int | swmm_get_crs (SWMM_Engine engine, char *buf, int buflen) |
| Copy the configured coordinate-reference-system string. | |
| SWMM_ENGINE_API int | swmm_options_get_start_date (SWMM_Engine engine, double *value) |
| Read the configured simulation start calendar value. | |
| SWMM_ENGINE_API int | swmm_options_set_start_date (SWMM_Engine engine, double value) |
| Assign the simulation start calendar value directly. | |
| SWMM_ENGINE_API int | swmm_options_get_end_date (SWMM_Engine engine, double *value) |
| Read the configured simulation end calendar value. | |
| SWMM_ENGINE_API int | swmm_options_set_end_date (SWMM_Engine engine, double value) |
| Assign the simulation end calendar value directly. | |
| SWMM_ENGINE_API int | swmm_options_get_report_start (SWMM_Engine engine, double *value) |
| Read the configured report start calendar value. | |
| SWMM_ENGINE_API int | swmm_options_set_report_start (SWMM_Engine engine, double value) |
| Assign the report start calendar value directly. | |
| SWMM_ENGINE_API int | swmm_userflag_get_bool (SWMM_Engine engine, const char *name, int *value) |
| Read a model-level BOOLEAN flag assignment. | |
| SWMM_ENGINE_API int | swmm_userflag_get_int (SWMM_Engine engine, const char *name, int *value) |
| Read a model-level INTEGER flag assignment. | |
| SWMM_ENGINE_API int | swmm_userflag_get_real (SWMM_Engine engine, const char *name, double *value) |
| Read a model-level REAL flag assignment. | |
| SWMM_ENGINE_API int | swmm_userflag_set_bool (SWMM_Engine engine, const char *name, int value) |
| Define a BOOLEAN flag and assign its model-level value. | |
| SWMM_ENGINE_API int | swmm_userflag_set_int (SWMM_Engine engine, const char *name, int value) |
| Define a INTEGER flag and assign its model-level value. | |
| SWMM_ENGINE_API int | swmm_userflag_set_real (SWMM_Engine engine, const char *name, double value) |
| Define a REAL flag and assign its model-level value. | |
| SWMM_ENGINE_API int | swmm_userflag_def_count (SWMM_Engine engine, int *count) |
| Count user-flag schema definitions. | |
| 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) |
| Read a flag definition by insertion-order index. | |
| SWMM_ENGINE_API int | swmm_userflag_define (SWMM_Engine engine, const char *name, int type, const char *description) |
| Define or replace a flag schema without converting assigned values. | |
| SWMM_ENGINE_API int | swmm_userflag_undefine (SWMM_Engine engine, const char *name) |
| Remove a schema and all assignments of that flag. | |
| 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) |
| Format a stored per-object flag assignment as text. | |
| 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) |
| Parse a copied assignment using an existing flag schema. | |
| SWMM_ENGINE_API int | swmm_userflag_value_clear (SWMM_Engine engine, const char *obj_type, const char *obj_name, const char *flag_name) |
| Remove one per-object assignment, leaving its schema intact. | |
C API implementation — model building, options, user flags, CRS.
| SWMM_ENGINE_API SWMM_Engine swmm_engine_new | ( | void | ) |
Create an empty programmatically editable engine in SWMM_STATE_BUILDING.
Add model objects through their APIs, then call swmm_finalize_model() before start. No input file is required; do not call ordinary open() on this BUILDING handle.
| 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 ) |
Read resolved and original strings for an existing external-file slot.
Unknown roles, unavailable stores or unresolved owner keys are BADPARAM. This call returns stored strings and does not resolve paths or access their files.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | role | SWMM_FilePathRole selecting a scalar or vector slot; 2D roles require a 2D-enabled engine/options store. |
| [in] | owner | Borrowed vector selector: decimal hotstart/LID-report index, gage ID or timeseries ID. Required for vector roles; ignored (may be NULL) for scalar roles. |
| [out] | absolute_buf | Non-null caller-owned resolved-path buffer; may return empty when not yet resolved. NUL-terminated and silently truncated to capacity-1. |
| [in] | absolute_buflen | Positive absolute_buf capacity including NUL. |
| [out] | original_buf | Non-null caller-owned authored-token buffer; may return empty, NUL-terminated and silently truncated. |
| [in] | original_buflen | Positive original_buf capacity including NUL. |
| SWMM_ENGINE_API int swmm_file_path_set | ( | SWMM_Engine | engine, |
| SWMM_FilePathRole | role, | ||
| const char * | owner, | ||
| const char * | new_path ) |
Replace an external-file token and invalidate its cached absolute path.
Does not create vector owners, resolve paths, reopen files or validate file existence. Unknown/unavailable roles and missing owners return BADPARAM.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | role | SWMM_FilePathRole selecting an existing scalar/vector slot. |
| [in] | owner | Vector owner as for swmm_file_path_get(); may be NULL for scalar roles. The referenced gage/series/hotstart/LID-report row must already exist. |
| [in] | new_path | Non-null NUL-terminated token to copy; empty clears the slot. Relative paths remain relative until a later resolver pass. |
| SWMM_ENGINE_API int swmm_files_get | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| char * | buf, | ||
| int | buflen ) |
Read a legacy [FILES] authoring field by case-insensitive key.
Paths use the original authored token. Missing hotstart slot 0 reads as empty path or numeric 0.000000 date; dates are decimal-day strings. Unknown keys are refused before writing output.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null key listed above, plus read-only HOTSTART_SAVE_COUNT. HOTSTART_SAVE_PATH/DATETIME address slot 0. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_files_set | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| const char * | value ) |
Set one copied legacy [FILES] authoring field.
Slot-0 hotstart setters create a row if needed and remove it when both path and date are empty/zero. Date 0 means save at run end. Path assignment clears cached absolute resolution. These authoring changes do not reopen live interface files; no lifecycle guard is imposed.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null case-insensitive writable key listed above; HOTSTART_SAVE_COUNT is read-only. |
| [in] | value | Non-null NUL-terminated value: paths accept empty to clear; modes accept SAVE, USE or empty case-insensitively; HOTSTART_SAVE_DATETIME accepts a full decimal-day number or empty for 0. |
| SWMM_ENGINE_API int swmm_finalize_model | ( | SWMM_Engine | engine | ) |
Resolve and initialize a programmatically built model.
Runs swmm_validate_model(), resolves cross-references and display-to-internal units/derived geometry, sets OPENED and delegates to ordinary initialization. A later failure need not leave BUILDING intact; inspect state/errors before retrying. On success call swmm_engine_start().
| [in] | engine | Non-null BUILDING engine. |
| SWMM_ENGINE_API int swmm_get_crs | ( | SWMM_Engine | engine, |
| char * | buf, | ||
| int | buflen ) |
Copy the configured coordinate-reference-system string.
Prefers the [OPTIONS] CRS and falls back to the spatial frame CRS (used by some non-INP input plugins). Does not validate or transform coordinates; missing CRS leaves the buffer unchanged.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_hotstart_legacy_omits | ( | SWMM_Engine | engine, |
| int * | flags ) |
Report selected model features that legacy routing hotstarts cannot retain.
Reads parsed authoring before initialization and does not write or validate a complete restart. The mask is not an exhaustive restart-completeness certificate: legacy/native formats and qualified full-engine checkpoints retain different state.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [out] | flags | Non-null OR-mask of SWMM_HOTSTART_OMITS_WATER_AGE, REACTION_SPECIES, AQUIFER and NODE_LIDS; zero when none of these features are configured. |
| SWMM_ENGINE_API int swmm_hotstart_saves_add | ( | SWMM_Engine | engine, |
| const char * | path, | ||
| double | datetime ) |
Append an AUTO-format scheduled save authoring entry.
Appending does not validate collisions or file writability and does not emit the file immediately.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | path | Non-null NUL-terminated path to copy; empty creates a placeholder row. |
| [in] | datetime | SWMM DateTime decimal days since 1899-12-30; 0 means run end. Stored without finite/date validation. |
| SWMM_ENGINE_API int swmm_hotstart_saves_clear | ( | SWMM_Engine | engine | ) |
Remove all scheduled save authoring entries.
Does not delete any existing files already written by earlier entries.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| SWMM_ENGINE_API int swmm_hotstart_saves_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Count scheduled SAVE HOTSTART authoring entries.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [out] | count | Non-null destination for the stored entry count. |
| SWMM_ENGINE_API int swmm_hotstart_saves_get_datetime | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | datetime ) |
Read the scheduled calendar date of one save entry.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [out] | datetime | Non-null destination for SWMM DateTime decimal days since 1899-12-30; 0 denotes end of run. |
| SWMM_ENGINE_API int swmm_hotstart_saves_get_format | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | format ) |
Read the authored format selector of one scheduled save.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [out] | format | Non-null destination for SWMM_HOTSTART_FORMAT_AUTO, LEGACY or NATIVE. |
| SWMM_ENGINE_API int swmm_hotstart_saves_get_path | ( | SWMM_Engine | engine, |
| int | idx, | ||
| char * | buf, | ||
| int | buflen ) |
Copy the authored path of one scheduled save entry.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [out] | buf | Non-null caller-owned destination, NUL-terminated and silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including NUL. |
| SWMM_ENGINE_API int swmm_hotstart_saves_remove | ( | SWMM_Engine | engine, |
| int | idx ) |
Remove a scheduled save entry and shift later indices down.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| SWMM_ENGINE_API int swmm_hotstart_saves_set_datetime | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | datetime ) |
Assign a scheduled save calendar date directly.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [in] | datetime | SWMM DateTime decimal days since 1899-12-30; 0 saves at run end. No finite/range/order validation is performed. |
| SWMM_ENGINE_API int swmm_hotstart_saves_set_format | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | format ) |
Select the authored format of an existing scheduled save.
This setter stores a preference; actual restart-profile support is evaluated when saving.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [in] | format | SWMM_HOTSTART_FORMAT_AUTO (0), LEGACY (1) or NATIVE (2). Other values are refused. |
| SWMM_ENGINE_API int swmm_hotstart_saves_set_path | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | path ) |
Replace a scheduled save path without removing its row.
Unlike the legacy slot-0 swmm_files_set() sugar, an empty path with zero datetime does not auto-remove this entry. Use remove/clear explicitly.
| [in] | engine | Non-null live engine with exclusive caller access. Scheduled-entry authoring APIs impose no lifecycle guard and do not write a file immediately. |
| [in] | idx | Zero-based existing SAVE HOTSTART slot index; an invalid index returns SWMM_ERR_BADINDEX. |
| [in] | path | Non-null NUL-terminated path to copy; empty is permitted and clears the token/cached absolute path. |
| SWMM_ENGINE_API int swmm_model_write | ( | SWMM_Engine | engine, |
| const char * | new_inp_path ) |
Serialize the current model with the built-in INP writer.
Appends writer diagnostics to the engine warning list, including substitutions/omissions that do not prevent successful serialization. Uses full native format and may write mesh/component companions. Success is serialization, not an atomic project publication; inspect warnings. No lifecycle guard is imposed by this wrapper.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | new_inp_path | Non-null NUL-terminated destination path; borrowed for this call. Existing output files may be replaced. |
| SWMM_ENGINE_API int swmm_model_write_compat | ( | SWMM_Engine | engine, |
| const char * | new_inp_path, | ||
| int | profile ) |
Serialize the model to a selected INP compatibility profile.
SWMM_INP_PROFILE_SWMM5 produces a file a SWMM 5.x engine reads: * v6-only sections ([VIRTUAL_JUNCTIONS], [INLET_JUNCTIONS], [2D_*], * [PLUGINS], [PROCESS_COMPONENTS], [USER_FLAGS], [USER_FLAG_VALUES], * [RDII_DECAY]) and option keys are omitted, FLOW_ROUTING FV is * written as DYNWAVE, SURCHARGE_METHOD DYNAMIC_SLOT/TPA as
SLOT, a virtual junction becomes an ordinary junction, and an * inlet junction becomes an ordinary junction plus an [INLET_USAGE] * row on its approach conduit (same design, same capture node). * A SAVE HOTSTART row loses its LEGACY / NATIVE format keyword. * Each substitution is appended to the engine's warning list * (swmm_get_warning_count / swmm_get_warning_at). The file is a run * artifact: the model held by the engine is not changed. * * SWMM_INP_PROFILE_SWMM5_STOCK is the same for a STOCK EPA SWMM 5 * engine: it also drops the positional extensions only the OpenSWMM* snowpack placeholder that holds their position) and * the rain-gage scale factor — which a stock parser rejects as an * undefined object. A dropped factor other than 1.0 is reported as * a warning. Use it for any 5.x engine that is not the in-tree one.| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | new_inp_path | Non-null NUL-terminated destination path, borrowed for this call; existing outputs can be replaced. |
| [in] | profile | SWMM_INP_PROFILE_FULL, SWMM_INP_PROFILE_SWMM5 or SWMM_INP_PROFILE_SWMM5_STOCK. |
| SWMM_ENGINE_API int swmm_model_write_staged | ( | SWMM_Engine | engine, |
| const char * | final_inp_path, | ||
| SWMM_StageOutputCallback | mapper, | ||
| void * | user_data ) |
Serialize built-in INP outputs through a mandatory caller staging mapper.
Only mapped output directories may be created. References remain relative to final_inp_path; the caller owns staging cleanup, validation and publication. Plugins are excluded, and diagnostics append to the engine warning list. Callback must not throw or mutate/reenter the engine.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | final_inp_path | Non-null, nonempty final model path used to form all serialized references; not the mapped staging filename. |
| [in] | mapper | Non-null synchronous output mapper. Every actual model/mesh/component output must map to a separate staging destination distinct from all final outputs. |
| [in] | user_data | Borrowed opaque pointer passed unchanged to mapper; may be NULL and must remain valid until return. |
| SWMM_ENGINE_API int swmm_model_write_with_plugin | ( | SWMM_Engine | engine, |
| const char * | new_path, | ||
| const char * | output_plugin_id ) |
Serialize through a transient named input/writer plugin.
Creates a temporary writer so the primary input plugin is not reused. Plugin finalize is best-effort; its result does not override the write result. The built-in path appends writer warnings; component lookup failures are returned without emitting a load warning. Does not guarantee atomic publication.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | new_path | Non-null NUL-terminated destination path; borrowed for the call. |
| [in] | output_plugin_id | Borrowed library path, plugin ID or id:version. NULL/empty selects the built-in INP writer. |
| SWMM_ENGINE_API int swmm_options_ext_key_at | ( | SWMM_Engine | engine, |
| int | index, | ||
| char * | buf, | ||
| int | buflen ) |
Copy one key accepted by swmm_options_get_ext() by position.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | index | Zero-based position, less than the swmm_options_ext_key_count() result. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_options_ext_key_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Number of keys swmm_options_get_ext() currently accepts on this engine.
With a 2D surface configured these are MESH_FILE and every current [2D_OPTIONS] key; they are followed by the generic extension keys stored on the model, in byte order. Generic keys can be added by swmm_options_set_ext(), so re-count after edits.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | count | Non-null destination, written only on success. |
| SWMM_ENGINE_API int swmm_options_get | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| char * | buf, | ||
| int | buflen ) |
Format a supported standard option in input-compatible string form.
Enums use canonical input tokens, Boolean/date/numeric options use their accepted textual forms, and units follow the named input option. The formatted value is intended for swmm_options_set() round trips. Unknown keys are refused; buffer truncation still returns success.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null standard option name, matched case-insensitively. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_options_get_end_date | ( | SWMM_Engine | engine, |
| double * | value ) |
Read the configured simulation end calendar value.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | value | Non-null destination for OADate/SWMM DateTime decimal days since 1899-12-30; no timezone conversion. |
| SWMM_ENGINE_API int swmm_options_get_ext | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| char * | buf, | ||
| int | buflen ) |
Read a live 2D option or stored extension string.
2D keys read the live solver options, with applicable AUTO values resolved against authored infiltration/aquifer data. Other keys must exist in the generic extension map. Unknown keys are refused and short buffers are silently truncated.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null extension key. Recognized 2D/MESH_FILE keys use their option parser matching; generic ext_options lookup uses the exact stored key. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_options_get_report_start | ( | SWMM_Engine | engine, |
| double * | value ) |
Read the configured report start calendar value.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | value | Non-null destination for OADate/SWMM DateTime decimal days since 1899-12-30; no timezone conversion. |
| SWMM_ENGINE_API int swmm_options_get_start_date | ( | SWMM_Engine | engine, |
| double * | value ) |
Read the configured simulation start calendar value.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | value | Non-null destination for OADate/SWMM DateTime decimal days since 1899-12-30; no timezone conversion. |
| SWMM_ENGINE_API int swmm_options_key_at | ( | int | index, |
| char * | buf, | ||
| int | buflen ) |
Copy one standard option key by position.
| [in] | index | Zero-based position, less than swmm_options_key_count(). |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_options_key_count | ( | void | ) |
Number of standard option keys accepted by swmm_options_get() and swmm_options_set().
Keys are canonical spellings (aliases such as ROUTING_MODEL are omitted) and include the [REPORT] keys under their RPT_ prefix. The list is fixed for a build and needs no engine.
| SWMM_ENGINE_API int swmm_options_set | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| const char * | value ) |
Parse and assign a supported standard simulation option.
Unknown keys, malformed numeric conversions and option-specific validation failures return BADPARAM. This is not a blanket BUILDING-only interface: thermal ownership guards apply to selected keys and individual options have their own validation. Set run configuration before initialization; the call does not automatically rebuild solver state.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null case-insensitive standard option key. |
| [in] | value | Non-null NUL-terminated input-format value. Units/enum tokens are those of the corresponding SWMM [OPTIONS] key. |
| SWMM_ENGINE_API int swmm_options_set_end_date | ( | SWMM_Engine | engine, |
| double | value ) |
Assign the simulation end calendar value directly.
No lifecycle, finite-value or chronological validation is applied here. Invalidates the cached total duration for later recomputation.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | value | OADate/SWMM DateTime decimal days since 1899-12-30; caller must provide a finite, valid calendar value and consistent date ordering. |
| SWMM_ENGINE_API int swmm_options_set_ext | ( | SWMM_Engine | engine, |
| const char * | key, | ||
| const char * | value ) |
Set a recognized 2D option or retain a generic extension key/value.
Recognized 2D options parse into a copy and publish only on success; retired 2D keys are refused. INFIL_STEP and GW_ET update their live authoring stores. WRITE_ABSOLUTE_PATHS updates the standard Boolean field. Unrecognized keys are copied verbatim to ext_options without semantic validation.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | key | Non-null NUL-terminated extension name. Recognized built-in keys use case-insensitive dispatch; generic keys retain exact spelling. |
| [in] | value | Non-null NUL-terminated value, copied or parsed using the selected input grammar; empty MESH_FILE clears the external mesh reference. |
| SWMM_ENGINE_API int swmm_options_set_report_start | ( | SWMM_Engine | engine, |
| double | value ) |
Assign the report start calendar value directly.
No lifecycle, finite-value or chronological validation is applied here. Does not change simulation start/end or rebuild report scheduling.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | value | OADate/SWMM DateTime decimal days since 1899-12-30; caller must provide a finite, valid calendar value and consistent date ordering. |
| SWMM_ENGINE_API int swmm_options_set_start_date | ( | SWMM_Engine | engine, |
| double | value ) |
Assign the simulation start calendar value directly.
No lifecycle, finite-value or chronological validation is applied here. Invalidates the cached total duration for later recomputation.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | value | OADate/SWMM DateTime decimal days since 1899-12-30; caller must provide a finite, valid calendar value and consistent date ordering. |
| 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 ) |
Read one stored [PLUGINS] row without resolving/loading it.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | idx | Zero-based specification index in [0,plugin count). |
| [out] | path_buf | Optional caller-owned path/ID buffer; NUL-terminated and silently truncated when capacity is positive. |
| [in] | path_buf_sz | Buffer capacity including NUL; nonpositive suppresses path output. |
| [out] | args_buf | Optional caller-owned argument buffer. Arguments are joined with spaces and quoted as needed to preserve token boundaries. |
| [in] | args_buf_sz | Buffer capacity including NUL; nonpositive suppresses argument output. |
| SWMM_ENGINE_API int swmm_plugin_remove | ( | SWMM_Engine | engine, |
| const char * | path_or_id ) |
Remove the first exact-matching stored plugin specification.
Idempotent when no row matches. Does not unload an existing runtime instance or alter other plugin rows.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | path_or_id | Non-null NUL-terminated stored path/ID, matched case-sensitively. |
| SWMM_ENGINE_API int swmm_plugin_set | ( | SWMM_Engine | engine, |
| const char * | path_or_id, | ||
| const char * | args ) |
Add or replace a copied plugin specification by exact path/ID key.
Replaces only init_args when the exact key exists; otherwise appends. Does not load, validate or reinitialize the plugin immediately. Stored specifications are serialized on a later model write.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | path_or_id | Non-null, nonempty NUL-terminated library path, plugin ID or id:version; matched case-sensitively as stored. |
| [in] | args | Borrowed space-separated argument text with tokenizer quoting support; NULL/empty means no arguments. |
| SWMM_ENGINE_API int swmm_plugins_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Count stored [PLUGINS] specifications.
Counts authoring rows, not loaded plugin instances.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | count | Non-null destination for the number of stored plugin rows. |
| SWMM_ENGINE_API int swmm_title_add_line | ( | SWMM_Engine | engine, |
| const char * | line ) |
Append a copied title/note entry.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | line | Non-null NUL-terminated entry; an empty string appends a blank entry. Embedded newlines are not split by this function. |
| SWMM_ENGINE_API int swmm_title_clear | ( | SWMM_Engine | engine | ) |
Remove all title/note entries.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| SWMM_ENGINE_API int swmm_title_get_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Count stored [TITLE] note lines.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | count | Non-null destination for the line count. |
| SWMM_ENGINE_API int swmm_title_get_line | ( | SWMM_Engine | engine, |
| int | index, | ||
| char * | buf, | ||
| int | buflen ) |
Copy one stored title/note line.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | index | Zero-based title-line index. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| SWMM_ENGINE_API int swmm_title_set | ( | SWMM_Engine | engine, |
| const char * | text ) |
Replace title entries by splitting copied text at newline characters.
Splits on LF only; any CR bytes remain in the corresponding stored entry.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | text | Non-null NUL-terminated text. Empty clears all lines; internal blank lines are retained, a trailing newline does not add another final empty entry. |
| SWMM_ENGINE_API int swmm_userflag_def_count | ( | SWMM_Engine | engine, |
| int * | count ) |
Count user-flag schema definitions.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [out] | count | Non-null destination for the number of definitions. |
| 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 ) |
Read a flag definition by insertion-order index.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | index | Zero-based schema-definition index. |
| [out] | name_buf | Optional caller-owned uppercase-name buffer; NUL-terminated and silently truncated when capacity is positive. |
| [in] | name_buflen | Name buffer capacity including NUL; nonpositive suppresses name output. |
| [out] | type | Optional type destination: 0=BOOLEAN, 1=INTEGER, 2=REAL, 3=STRING. |
| [out] | desc_buf | Optional caller-owned description buffer; empty when absent, NUL-terminated/truncated when capacity is positive. |
| [in] | desc_buflen | Description buffer capacity including NUL; nonpositive suppresses description output. |
| SWMM_ENGINE_API int swmm_userflag_define | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| int | type, | ||
| const char * | description ) |
Define or replace a flag schema without converting assigned values.
Redefinition replaces the schema/type/description but retains previous per-object values without converting them. Callers changing type must reconcile existing assignments before using typed getters.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null, nonempty NUL-terminated name, copied in uppercase. |
| [in] | type | 0=BOOLEAN, 1=INTEGER, 2=REAL or 3=STRING. |
| [in] | description | Optional copied NUL-terminated description; NULL means empty. |
| SWMM_ENGINE_API int swmm_userflag_get_bool | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| int * | value ) |
Read a model-level BOOLEAN flag assignment.
Reads the MODEL category with an empty object key; it does not return a per-node or per-link assignment. Existing assignments must be compatible with their current schema type.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated defined flag name, matched case-insensitively; schema must have type BOOLEAN. |
| [out] | value | Non-null destination for the MODEL/empty-key assignment; 0 (false) when defined but unset. |
| SWMM_ENGINE_API int swmm_userflag_get_int | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| int * | value ) |
Read a model-level INTEGER flag assignment.
Reads the MODEL category with an empty object key; it does not return a per-node or per-link assignment. Existing assignments must be compatible with their current schema type.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated defined flag name, matched case-insensitively; schema must have type INTEGER. |
| [out] | value | Non-null destination for the MODEL/empty-key assignment; 0 when defined but unset. |
| SWMM_ENGINE_API int swmm_userflag_get_real | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| double * | value ) |
Read a model-level REAL flag assignment.
Reads the MODEL category with an empty object key; it does not return a per-node or per-link assignment. Existing assignments must be compatible with their current schema type.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated defined flag name, matched case-insensitively; schema must have type REAL. |
| [out] | value | Non-null destination for the MODEL/empty-key assignment; 0.0 when defined but unset. |
| SWMM_ENGINE_API int swmm_userflag_set_bool | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| int | value ) |
Define a BOOLEAN flag and assign its model-level value.
Defines/redefines this name as BOOLEAN with an empty description, then sets its MODEL/empty-key value. Other existing object assignments are retained without conversion. No lifecycle guard is applied.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated name, copied in uppercase. |
| [in] | value | 0 means false; any nonzero value means true. |
| SWMM_ENGINE_API int swmm_userflag_set_int | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| int | value ) |
Define a INTEGER flag and assign its model-level value.
Defines/redefines this name as INTEGER with an empty description, then sets its MODEL/empty-key value. Other existing object assignments are retained without conversion. No lifecycle guard is applied.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated name, copied in uppercase. |
| [in] | value | INTEGER value copied without additional range validation. |
| SWMM_ENGINE_API int swmm_userflag_set_real | ( | SWMM_Engine | engine, |
| const char * | name, | ||
| double | value ) |
Define a REAL flag and assign its model-level value.
Defines/redefines this name as REAL with an empty description, then sets its MODEL/empty-key value. Other existing object assignments are retained without conversion. No lifecycle guard is applied.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated name, copied in uppercase. |
| [in] | value | REAL value copied without additional range validation. |
| SWMM_ENGINE_API int swmm_userflag_undefine | ( | SWMM_Engine | engine, |
| const char * | name ) |
Remove a schema and all assignments of that flag.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | name | Non-null NUL-terminated flag name, matched case-insensitively. |
| SWMM_ENGINE_API int swmm_userflag_value_clear | ( | SWMM_Engine | engine, |
| const char * | obj_type, | ||
| const char * | obj_name, | ||
| const char * | flag_name ) |
Remove one per-object assignment, leaving its schema intact.
Idempotent for missing assignments; does not validate object existence or require an existing schema.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | obj_type | Non-null NUL-terminated category token, uppercased internally (for example NODE, LINK, SUBCATCHMENT or MODEL). |
| [in] | obj_name | Non-null NUL-terminated object key, preserved exactly including case; MODEL values conventionally use an empty key. |
| [in] | flag_name | Non-null NUL-terminated flag name, matched case-insensitively. |
| 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 ) |
Format a stored per-object flag assignment as text.
BOOLEAN uses YES/NO, INTEGER decimal, REAL g, and STRING verbatim without quoting. Looks up the supplied object key without validating object existence. Short buffers truncate silently while found remains 1.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | obj_type | Non-null NUL-terminated category token, uppercased internally (for example NODE, LINK, SUBCATCHMENT or MODEL). |
| [in] | obj_name | Non-null NUL-terminated object key, preserved exactly including case; MODEL values conventionally use an empty key. |
| [in] | flag_name | Non-null NUL-terminated flag name, matched case-insensitively. |
| [out] | buf | Non-null caller-owned buffer; success writes NUL-terminated text, silently truncated to buflen-1 bytes. |
| [in] | buflen | Positive buffer capacity in bytes, including the NUL terminator. |
| [out] | found | Non-null destination: 1 for a stored assignment, 0 when absent (including undefined flags). Missing values also write an empty buffer. |
| 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 ) |
Parse a copied assignment using an existing flag schema.
Object category and flag name are uppercased; object name is case-preserved. The API does not validate that the object exists. Boolean token handling is that of Tokenizer::parse_boolean(), rather than a separate strict validator.
| [in] | engine | Non-null live engine handle; caller provides exclusive access. |
| [in] | obj_type | Non-null NUL-terminated category token, uppercased internally (for example NODE, LINK, SUBCATCHMENT or MODEL). |
| [in] | obj_name | Non-null NUL-terminated object key, preserved exactly including case; MODEL values conventionally use an empty key. |
| [in] | flag_name | Non-null NUL-terminated flag name, matched case-insensitively. |
| [in] | value | Non-null NUL-terminated value: BOOLEAN uses the input Boolean tokenizer; INTEGER requires a complete decimal integer; REAL uses the engine numeric parser; STRING is stored verbatim. |
| SWMM_ENGINE_API int swmm_validate_model | ( | SWMM_Engine | engine | ) |
Check the minimal programmatic topology prerequisites without changing state.
Checks at least one node, at least one outfall and that every link endpoint indexes an existing node. Does not perform a duplicate-ID scan, connectivity analysis, full input validation or emit validation warnings in this wrapper.
| [in] | engine | Non-null engine in BUILDING or OPENED. |
1.13.2