OpenSWMM Engine  6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
Loading...
Searching...
No Matches
openswmm_tables.h File Reference

OpenSWMM Engine — Tables (Time Series & Curves) and Patterns C API. More...

#include "openswmm_engine.h"
Include dependency graph for openswmm_tables.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

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_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.
 
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.
 

Detailed Description

OpenSWMM Engine — Tables (Time Series & Curves) and Patterns C API.

Table identity, creation, data point management, cursor-optimized lookup, and time pattern management.

See also
openswmm_engine.h
Author
Caleb Buahin caleb.nosp@m..bua.nosp@m.hin@g.nosp@m.mail.nosp@m..com
License
Apache-2.0

Function Documentation

◆ swmm_curve_add()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idUnique null-terminated identifier.
[in]typeCurve type code.
Returns
SWMM_OK on success, or an error code.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. ID is copied. Null or duplicate ID within the same table kind returns BADPARAM; curves and timeseries may share a name. type is stored by direct enum cast without range validation; supply the TableType curve codes documented by swmm_table_get_type(), rather than a legacy curve-only numbering.
Here is the call graph for this function:

◆ swmm_pattern_add()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idUnique null-terminated identifier.
[in]typePattern type code.
Returns
SWMM_OK on success, or an error code.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. Copies the ID and appends an empty-factor row. This wrapper does not enforce uniqueness or a type range; caller must supply an unambiguous name and supported type.
Here is the call graph for this function:

◆ swmm_pattern_count()

SWMM_ENGINE_API int swmm_pattern_count ( SWMM_Engine engine)

Get the total number of time patterns in the model.

Parameters
[in]engineEngine handle.
Returns
Number of patterns, or -1 on error.

◆ swmm_pattern_get_factor()

SWMM_ENGINE_API int swmm_pattern_get_factor ( SWMM_Engine engine,
int idx,
int i,
double * v )

Get one multiplier factor from a pattern.

Parameters
[in]engineEngine handle.
[in]idxZero-based pattern index.
[in]iZero-based factor index within the pattern.
[out]vReceives the multiplier value.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. v must be non-null or BADPARAM is returned.
Here is the call graph for this function:

◆ swmm_pattern_get_factor_count()

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based pattern index.
[out]countReceives the factor count (typically 12, 7, or 24).
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. count must be non-null or BADPARAM is returned.
Here is the call graph for this function:

◆ swmm_pattern_get_type()

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).

Parameters
[in]engineEngine handle.
[in]idxZero-based pattern index.
[out]typeReceives the pattern type code.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. type must be non-null or BADPARAM is returned.
Here is the call graph for this function:

◆ swmm_pattern_id()

SWMM_ENGINE_API const char * swmm_pattern_id ( SWMM_Engine engine,
int idx )

Get the string identifier of a pattern by index.

Parameters
[in]engineEngine handle.
[in]idxZero-based pattern index.
Returns
Null-terminated string owned by the engine, or NULL on error.
Note
ID storage is borrowed until name/table/pattern changes, close/reopen or engine destruction; copy before retaining it across edits.

◆ swmm_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.

Parameters
[in]engineEngine handle.
[in]idNull-terminated pattern identifier.
Returns
Zero-based index, or -1 if not found.
Note
ID matching is case-insensitive; null engine/ID or absent name returns -1.

◆ swmm_pattern_remove()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idxZero-based pattern index.
Returns
SWMM_OK on success (idempotent: returns SWMM_OK if idx is out of range, matching the GUI's repeated-click expectations); SWMM_ERR_LIFECYCLE if not editable.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE.
Here is the call graph for this function:

◆ swmm_pattern_rename()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idxZero-based pattern index.
[in]newIdNew null-terminated identifier; must not already be in use.
Returns
SWMM_OK on success; SWMM_ERR_BADPARAM if newId is empty or collides with an existing pattern; SWMM_ERR_LIFECYCLE if not editable; SWMM_ERR_BADINDEX if idx is out of range.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. New ID is copied and checked case-insensitively against other patterns; a case-only respelling of this row is allowed. Stored pattern-reference rewriting matches the previous spelling exactly. Null/empty names return BADPARAM.
Here is the call graph for this function:

◆ swmm_pattern_set_factors()

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based pattern index.
[in]factorsArray of multiplier values.
[in]countNumber of factors (e.g., 12 for MONTHLY, 24 for HOURLY).
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. factors must be non-null and count positive or BADPARAM is returned. Copies exactly count values and refreshes the inflow solver pattern cache for next-step use; factor count/type compatibility and finite/range values are not checked.
Here is the call graph for this function:

◆ swmm_table_add_point()

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).

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
[in]xX value (independent variable).
[in]yY value (dependent variable).
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. No lifecycle, finite-value or ascending-x validation is imposed; the point appends in insertion order and does not reset the existing lookup cursor. Caller must maintain a usable ordered table. Time-series x is an absolute SWMM DateTime; curve x/y units depend on curve type.
Here is the call graph for this function:

◆ swmm_table_clear()

SWMM_ENGINE_API int swmm_table_clear ( SWMM_Engine engine,
int idx )

Remove all data points from a table.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. Clears x/y, resets the lookup cursor and removes relative-row metadata (n_relative=0, anchor=0).
Here is the call graph for this function:

◆ swmm_table_count()

SWMM_ENGINE_API int swmm_table_count ( SWMM_Engine engine)

Get the total number of tables (time series + curves) in the model.

Parameters
[in]engineEngine handle.
Returns
Number of tables, or -1 on error.

◆ swmm_table_get_point()

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
[in]pt_idxZero-based point index within the table.
[out]xReceives the X value.
[out]yReceives the Y value.
Returns
SWMM_OK on success, or an error code.
Note
x may be NULL to suppress that output. y may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX.
Here is the call graph for this function:

◆ swmm_table_get_point_count()

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
[out]countReceives the point count.
Returns
SWMM_OK on success, or an error code.
Note
count may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/pollutant index check returns SWMM_ERR_BADINDEX.
Here is the call graph for this function:

◆ swmm_table_get_type()

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

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
[out]typeReceives the type code.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. type must be non-null or BADPARAM is returned.
Here is the call graph for this function:

◆ swmm_table_id()

SWMM_ENGINE_API const char * swmm_table_id ( SWMM_Engine engine,
int idx )

Get the string identifier of a table by index.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
Returns
Null-terminated string owned by the engine, or NULL on error.
Note
ID storage is borrowed until name/table/pattern changes, close/reopen or engine destruction; copy before retaining it across edits.
Here is the call graph for this function:

◆ swmm_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.

Parameters
[in]engineEngine handle.
[in]idNull-terminated table identifier.
Returns
Zero-based index, or -1 if not found.
Note
Searches timeseries first, then curves; the two kinds may share an ID, so this unqualified lookup prefers the timeseries. Null engine/ID returns -1.

◆ swmm_table_lookup()

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).

Parameters
[in]engineEngine handle.
[in]idxZero-based table index.
[in]xX value to look up.
[out]yReceives the interpolated Y value.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. y must be non-null or BADPARAM is returned. Empty tables return 0; a singleton or out-of-range query returns the nearest endpoint value. Interior values use linear interpolation; nearly duplicate x entries use their mean. Updates the table cursor, so exclusive access is required even though x/y data are not changed.
Here is the call graph for this function:

◆ swmm_table_rename()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idxZero-based table index.
[in]newIdNew null-terminated identifier.
Returns
SWMM_OK on success (also when 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.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. New ID is copied; null/empty names return BADPARAM. Rewrites recognized stored name-reference sites case-insensitively, including applicable 2D boundaries, while preserving the numeric table index.
Here is the call graph for this function:

◆ swmm_table_set_type()

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.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idxZero-based table index of a curve.
[in]typeNew curve type code (1 = STORAGE … 11 = PUMP5).
Returns
SWMM_OK on success; SWMM_ERR_BADPARAM if 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.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX.
Here is the call graph for this function:

◆ swmm_timeseries_add()

SWMM_ENGINE_API int swmm_timeseries_add ( SWMM_Engine engine,
const char * id )

Add a new time series to the model.

Parameters
[in]engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
[in]idUnique null-terminated identifier.
Returns
SWMM_OK on success, or an error code.
Note
Requires BUILDING or OPENED; other states return SWMM_ERR_LIFECYCLE. A null engine returns SWMM_ERR_BADHANDLE. ID is copied. Null or duplicate ID within the same table kind returns BADPARAM; curves and timeseries may share a name.
Here is the call graph for this function:

◆ swmm_timeseries_get_relative_info()

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index (must be a TIMESERIES).
[out]n_relativeLeading rows authored as elapsed time (0 = all rows carry explicit dates).
[out]anchorOADate offset baked into those rows' x-values.
Returns
SWMM_OK on success, or an error code.
Note
n_relative may be NULL to suppress that output. anchor may be NULL to suppress that output. A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. A non-TIMESERIES table returns BADPARAM; optional outputs may both be NULL. Metadata retrieval does not shift any x-values.
Here is the call graph for this function:

◆ swmm_timeseries_set_relative_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).

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.

Parameters
[in]engineEngine handle.
[in]idxZero-based table index (must be a TIMESERIES).
[in]n_relativeLeading rows authored as elapsed time (clamped to the current point count).
[in]anchorOADate offset baked into those rows' x-values.
Returns
SWMM_OK on success, or an error code.
Note
A null engine returns SWMM_ERR_BADHANDLE. A failed table/pattern/point index check returns SWMM_ERR_BADINDEX. No lifecycle guard is imposed. A non-TIMESERIES table or negative n_relative returns BADPARAM; count is clamped to current point count. Stores anchor directly without shifting x-values or checking finite dates.
Here is the call graph for this function: