![]() |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
C API implementation — tables (time series, curves) and patterns. More...
#include "openswmm_api_common.hpp"#include "../edit/ObjectDeleter.hpp"#include "../../../include/openswmm/engine/openswmm_tables.h"#include "StringCase.hpp"Functions | |
| SWMM_ENGINE_API int | swmm_table_count (SWMM_Engine engine) |
| Get the total number of tables (time series + curves) in the model. | |
| SWMM_ENGINE_API int | swmm_table_index (SWMM_Engine engine, const char *id) |
| Look up a table's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_table_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a table by index. | |
| SWMM_ENGINE_API int | swmm_table_get_type (SWMM_Engine engine, int idx, int *type) |
| Get a table's type code. | |
| SWMM_ENGINE_API int | swmm_timeseries_add (SWMM_Engine engine, const char *id) |
| Add a new time series to the model. | |
| SWMM_ENGINE_API int | swmm_curve_add (SWMM_Engine engine, const char *id, int type) |
| Add a new curve to the model. | |
| SWMM_ENGINE_API int | swmm_table_add_point (SWMM_Engine engine, int idx, double x, double y) |
| Append a data point (x, y) to a table. | |
| SWMM_ENGINE_API int | swmm_table_get_point_count (SWMM_Engine engine, int idx, int *count) |
| Get the number of data points in a table. | |
| SWMM_ENGINE_API int | swmm_table_get_point (SWMM_Engine engine, int idx, int pt_idx, double *x, double *y) |
| Get a specific data point from a table. | |
| SWMM_ENGINE_API int | swmm_table_clear (SWMM_Engine engine, int idx) |
| Remove all data points from a table. | |
| SWMM_ENGINE_API int | swmm_timeseries_get_relative_info (SWMM_Engine engine, int idx, int *n_relative, double *anchor) |
| Get a timeseries' time-only (relative) row info. | |
| SWMM_ENGINE_API int | swmm_timeseries_set_relative_info (SWMM_Engine engine, int idx, int n_relative, double anchor) |
| Declare a timeseries' leading rows as time-only (relative). | |
| SWMM_ENGINE_API int | swmm_table_lookup (SWMM_Engine engine, int idx, double x, double *y) |
| Interpolate a Y value from a table for a given X. | |
| SWMM_ENGINE_API int | swmm_pattern_add (SWMM_Engine engine, const char *id, int type) |
| Add a new time pattern to the model. | |
| SWMM_ENGINE_API int | swmm_pattern_set_factors (SWMM_Engine engine, int idx, const double *factors, int count) |
| Set the multiplier factors for a time pattern. | |
| SWMM_ENGINE_API int | swmm_pattern_count (SWMM_Engine engine) |
| Get the total number of time patterns in the model. | |
| SWMM_ENGINE_API int | swmm_pattern_index (SWMM_Engine engine, const char *id) |
| Look up a pattern's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_pattern_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a pattern by index. | |
| SWMM_ENGINE_API int | swmm_pattern_get_type (SWMM_Engine engine, int idx, int *type) |
| Get a pattern's type code. | |
| SWMM_ENGINE_API int | swmm_pattern_get_factor_count (SWMM_Engine engine, int idx, int *count) |
| Get the number of multiplier factors stored for a pattern. | |
| SWMM_ENGINE_API int | swmm_pattern_get_factor (SWMM_Engine engine, int idx, int i, double *v) |
| Get one multiplier factor from a pattern. | |
| SWMM_ENGINE_API int | swmm_pattern_remove (SWMM_Engine engine, int idx) |
| Remove a time pattern by index, clearing any reference sites. | |
| SWMM_ENGINE_API int | swmm_table_rename (SWMM_Engine engine, int idx, const char *newId) |
| Rename a timeseries or curve; rewrites every name-based reference to it (gages, external inflows, outfall stage data, climate options, snow radiation series, storage/divider/pump/inlet curves and 2D boundary series/rating curves). Index-based references follow on their own. | |
| SWMM_ENGINE_API int | swmm_table_set_type (SWMM_Engine engine, int idx, int type) |
| Change a curve's type (STORAGE … PUMP5) in place, keeping its points and every reference to it. | |
| SWMM_ENGINE_API int | swmm_pattern_rename (SWMM_Engine engine, int idx, const char *newId) |
| Rename a time pattern; updates every stored reference to the previous name across inflows, DWF, aquifer ET, and options. | |
C API implementation — tables (time series, curves) and patterns.
| SWMM_ENGINE_API int swmm_curve_add | ( | SWMM_Engine | engine, |
| const char * | id, | ||
| int | type ) |
Add a new curve to the model.
Curve types use the unified TableType codes: 1=STORAGE, 2=DIVERSION, 3=RATING, 4=SHAPE, 5=CONTROL, 6=TIDAL, 7..11=PUMP1..PUMP5. Code 0 denotes TIMESERIES, not STORAGE.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | id | Unique null-terminated identifier. |
| [in] | type | Curve type code. |
| SWMM_ENGINE_API int swmm_pattern_add | ( | SWMM_Engine | engine, |
| const char * | id, | ||
| int | type ) |
Add a new time pattern to the model.
Pattern types: 0=MONTHLY, 1=DAILY, 2=HOURLY, 3=WEEKEND.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | id | Unique null-terminated identifier. |
| [in] | type | Pattern type code. |
| SWMM_ENGINE_API int swmm_pattern_count | ( | SWMM_Engine | engine | ) |
Get the total number of time patterns in the model.
| [in] | engine | Engine handle. |
| SWMM_ENGINE_API int swmm_pattern_get_factor | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | i, | ||
| double * | v ) |
Get one multiplier factor from a pattern.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based pattern index. |
| [in] | i | Zero-based factor index within the pattern. |
| [out] | v | Receives the multiplier value. |
| SWMM_ENGINE_API int swmm_pattern_get_factor_count | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | count ) |
Get the number of multiplier factors stored for a pattern.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based pattern index. |
| [out] | count | Receives the factor count (typically 12, 7, or 24). |
| SWMM_ENGINE_API int swmm_pattern_get_type | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | type ) |
Get a pattern's type code.
Pattern types: 0=MONTHLY, 1=DAILY, 2=HOURLY, 3=WEEKEND. Used by the GUI to filter pattern pickers by pattern kind (e.g. the four DWF picker rows each accept a specific type).
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based pattern index. |
| [out] | type | Receives the pattern type code. |
| SWMM_ENGINE_API const char * swmm_pattern_id | ( | SWMM_Engine | engine, |
| int | idx ) |
Get the string identifier of a pattern by index.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based pattern index. |
| SWMM_ENGINE_API int swmm_pattern_index | ( | SWMM_Engine | engine, |
| const char * | id ) |
Look up a pattern's zero-based index by its string identifier.
| [in] | engine | Engine handle. |
| [in] | id | Null-terminated pattern identifier. |
| SWMM_ENGINE_API int swmm_pattern_remove | ( | SWMM_Engine | engine, |
| int | idx ) |
Remove a time pattern by index, clearing any reference sites.
Walks every place the engine stores a pattern name and clears any entry matching the removed pattern: external inflows (ext_inflows.pattern_name), dry-weather-flow patterns (dwf.pat1..pat4), aquifer ET patterns (aquifers.upper_evap_pat), and the evaporation recovery option (options.evap_recovery_pat). The removal itself shifts subsequent pattern indices down by one — callers that hold cached pattern indices must re-resolve via swmm_pattern_index.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | idx | Zero-based pattern index. |
idx is out of range, matching the GUI's repeated-click expectations); SWMM_ERR_LIFECYCLE if not editable.| SWMM_ENGINE_API int swmm_pattern_rename | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | newId ) |
Rename a time pattern; updates every stored reference to the previous name across inflows, DWF, aquifer ET, and options.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | idx | Zero-based pattern index. |
| [in] | newId | New null-terminated identifier; must not already be in use. |
newId is empty or collides with an existing pattern; SWMM_ERR_LIFECYCLE if not editable; SWMM_ERR_BADINDEX if idx is out of range.| SWMM_ENGINE_API int swmm_pattern_set_factors | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const double * | factors, | ||
| int | count ) |
Set the multiplier factors for a time pattern.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based pattern index. |
| [in] | factors | Array of multiplier values. |
| [in] | count | Number of factors (e.g., 12 for MONTHLY, 24 for HOURLY). |
| SWMM_ENGINE_API int swmm_table_add_point | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | x, | ||
| double | y ) |
Append a data point (x, y) to a table.
For time series, x is in decimal days; for curves, x depends on the curve type (e.g., depth for storage curves).
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| [in] | x | X value (independent variable). |
| [in] | y | Y value (dependent variable). |
| SWMM_ENGINE_API int swmm_table_clear | ( | SWMM_Engine | engine, |
| int | idx ) |
Remove all data points from a table.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| SWMM_ENGINE_API int swmm_table_count | ( | SWMM_Engine | engine | ) |
Get the total number of tables (time series + curves) in the model.
| [in] | engine | Engine handle. |
| SWMM_ENGINE_API int swmm_table_get_point | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | pt_idx, | ||
| double * | x, | ||
| double * | y ) |
Get a specific data point from a table.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| [in] | pt_idx | Zero-based point index within the table. |
| [out] | x | Receives the X value. |
| [out] | y | Receives the Y value. |
| SWMM_ENGINE_API int swmm_table_get_point_count | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | count ) |
Get the number of data points in a table.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| [out] | count | Receives the point count. |
| SWMM_ENGINE_API int swmm_table_get_type | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | type ) |
Get a table's type code.
Tables are stored in a single unified array; this lets callers partition the array into time series vs. each curve type (e.g. for the GUI's Data Objects browser). Type values mirror openswmm::TableType: 0 = TIMESERIES 1 = CURVE_STORAGE 2 = CURVE_DIVERSION 3 = CURVE_RATING 4 = CURVE_SHAPE 5 = CURVE_CONTROL 6 = CURVE_TIDAL 7..11 = CURVE_PUMP1..PUMP5
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| [out] | type | Receives the type code. |
| SWMM_ENGINE_API const char * swmm_table_id | ( | SWMM_Engine | engine, |
| int | idx ) |
Get the string identifier of a table by index.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| SWMM_ENGINE_API int swmm_table_index | ( | SWMM_Engine | engine, |
| const char * | id ) |
Look up a table's zero-based index by its string identifier.
| [in] | engine | Engine handle. |
| [in] | id | Null-terminated table identifier. |
| SWMM_ENGINE_API int swmm_table_lookup | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | x, | ||
| double * | y ) |
Interpolate a Y value from a table for a given X.
Uses cursor-based lookup for efficient sequential access (e.g., during time-stepping through a time series).
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index. |
| [in] | x | X value to look up. |
| [out] | y | Receives the interpolated Y value. |
| SWMM_ENGINE_API int swmm_table_rename | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | newId ) |
Rename a timeseries or curve; rewrites every name-based reference to it (gages, external inflows, outfall stage data, climate options, snow radiation series, storage/divider/pump/inlet curves and 2D boundary series/rating curves). Index-based references follow on their own.
Uniqueness is kind-scoped and case-insensitive, as in swmm_timeseries_add / swmm_curve_add: a curve and a timeseries may share a name. Control-rule text is stored verbatim and is not rewritten.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | idx | Zero-based table index. |
| [in] | newId | New null-terminated identifier. |
newId equals the current id); SWMM_ERR_BADPARAM if newId is empty or names another table of the same kind; SWMM_ERR_LIFECYCLE if not editable; SWMM_ERR_BADINDEX if idx is out of range.| SWMM_ENGINE_API int swmm_table_set_type | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | type ) |
Change a curve's type (STORAGE … PUMP5) in place, keeping its points and every reference to it.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | idx | Zero-based table index of a curve. |
| [in] | type | New curve type code (1 = STORAGE … 11 = PUMP5). |
idx is a timeseries or type is not a curve type; SWMM_ERR_LIFECYCLE if not editable; SWMM_ERR_BADINDEX if idx is out of range.| SWMM_ENGINE_API int swmm_timeseries_add | ( | SWMM_Engine | engine, |
| const char * | id ) |
Add a new time series to the model.
| [in] | engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| [in] | id | Unique null-terminated identifier. |
| SWMM_ENGINE_API int swmm_timeseries_get_relative_info | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | n_relative, | ||
| double * | anchor ) |
Get a timeseries' time-only (relative) row info.
Rows authored without a date in a [TIMESERIES] section are elapsed times anchored at the simulation start (legacy SWMM seeds every series' date anchor with START_DATE + START_TIME). The engine stores those rows as absolute date/times after resolution; this reports how many leading rows were authored that way and the start_date offset currently baked into their x-values, so a caller can recover the authored elapsed times as x - anchor and the .inp writer emits them back in time-only form.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index (must be a TIMESERIES). |
| [out] | n_relative | Leading rows authored as elapsed time (0 = all rows carry explicit dates). |
| [out] | anchor | OADate offset baked into those rows' x-values. |
| SWMM_ENGINE_API int swmm_timeseries_set_relative_info | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | n_relative, | ||
| double | anchor ) |
Declare a timeseries' leading rows as time-only (relative).
Use after rebuilding a series through swmm_table_clear() / swmm_table_add_point() to restore its authored time-only format: the first n_relative points' x-values are treated as absolute date/times containing anchor as their simulation-start offset, and the .inp writer emits them as elapsed times (x - anchor) rather than dates. Pass 0 to mark every row as explicitly dated.
| [in] | engine | Engine handle. |
| [in] | idx | Zero-based table index (must be a TIMESERIES). |
| [in] | n_relative | Leading rows authored as elapsed time (clamped to the current point count). |
| [in] | anchor | OADate offset baked into those rows' x-values. |