![]() |
OpenSWMM Engine
6.0.0-alpha.4
Data-oriented, plugin-extensible SWMM Engine (6.0.0-alpha.4)
|
OpenSWMM Engine — Rain Gage C API. More...
#include "openswmm_engine.h"Go to the source code of this file.
Typedefs | |
| typedef enum SWMM_GageDataSource | SWMM_GageDataSource |
| Rain gage data source type. | |
| typedef enum SWMM_GageRainType | SWMM_GageRainType |
| Rain gage rainfall data format. | |
Enumerations | |
| enum | SWMM_GageDataSource { SWMM_GAGE_TIMESERIES = 0 , SWMM_GAGE_FILE = 1 } |
| Rain gage data source type. More... | |
| enum | SWMM_GageRainType { SWMM_RAIN_INTENSITY = 0 , SWMM_RAIN_VOLUME = 1 , SWMM_RAIN_CUMULATIVE = 2 } |
| Rain gage rainfall data format. More... | |
Functions | |
| SWMM_ENGINE_API int | swmm_gage_count (SWMM_Engine engine) |
| Get the total number of rain gages in the model. | |
| SWMM_ENGINE_API int | swmm_gage_index (SWMM_Engine engine, const char *id) |
| Look up a rain gage's zero-based index by its string identifier. | |
| SWMM_ENGINE_API const char * | swmm_gage_id (SWMM_Engine engine, int idx) |
| Get the string identifier of a rain gage by index. | |
| SWMM_ENGINE_API int | swmm_gage_add (SWMM_Engine engine, const char *id) |
| Add a new rain gage to the model. | |
| SWMM_ENGINE_API int | swmm_gage_set_rain_type (SWMM_Engine engine, int idx, int type) |
| Set the rainfall data format for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_rain_interval (SWMM_Engine engine, int idx, double seconds) |
| Set the rainfall recording interval for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_data_source (SWMM_Engine engine, int idx, int source) |
| Set the data source type for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_timeseries (SWMM_Engine engine, int idx, const char *ts_id) |
| Assign a time series as the data source for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_filename (SWMM_Engine engine, int idx, const char *path, const char *station_id) |
| Assign an external rainfall file as the data source for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_station_id (SWMM_Engine engine, int idx, const char *station_id) |
| Set the station id for a file-based gage (standard SWMM rain file). | |
| SWMM_ENGINE_API int | swmm_gage_set_file_column (SWMM_Engine engine, int idx, const char *column) |
| Set the data column name for a multi-column rain-file gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_file_format (SWMM_Engine engine, int idx, int format) |
| Set the rain file format for a file-based gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_snow_factor (SWMM_Engine engine, int idx, double factor) |
| Set the snow-catch deficiency correction factor (SCF) for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_rain_units (SWMM_Engine engine, int idx, int units) |
| Set the rain-depth units declared for a file-based gage. | |
| SWMM_ENGINE_API int | swmm_gage_set_scale_factor (SWMM_Engine engine, int idx, double factor) |
| Set the rainfall scaling factor for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_rain_type (SWMM_Engine engine, int idx, int *type) |
| Get the rainfall data format for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_data_source (SWMM_Engine engine, int idx, int *source) |
| Get the data source type for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_scale_factor (SWMM_Engine engine, int idx, double *factor) |
| Get the rainfall scaling factor for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_rain_interval (SWMM_Engine engine, int idx, double *seconds) |
| Get the rainfall recording interval for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_snow_factor (SWMM_Engine engine, int idx, double *factor) |
| Get the snow-catch deficiency correction factor (SCF) for a gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_timeseries (SWMM_Engine engine, int idx, char *buf, int buflen) |
| Get the assigned time series id for a TIMESERIES-source gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_station_id (SWMM_Engine engine, int idx, char *buf, int buflen) |
| Get the station id for a file-based gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_file_column (SWMM_Engine engine, int idx, char *buf, int buflen) |
| Get the data column name for a multi-column rain-file gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_file_format (SWMM_Engine engine, int idx, int *format) |
| Get the rain file format for a file-based gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_rain_units (SWMM_Engine engine, int idx, int *units) |
| Get the rain-depth units declared for a file-based gage. | |
| SWMM_ENGINE_API int | swmm_gage_get_rainfall (SWMM_Engine engine, int idx, double *rainfall) |
| Get current rainfall rate at a gage (project rate units). | |
| SWMM_ENGINE_API int | swmm_gage_set_rainfall (SWMM_Engine engine, int idx, double rainfall) |
| Override rainfall at a gage for the current timestep. | |
| SWMM_ENGINE_API int | swmm_gage_get_rainfall_bulk (SWMM_Engine engine, double *buf, int count) |
| Get current rainfall rates for all gages in a single call. | |
| SWMM_ENGINE_API int | swmm_gage_rename (SWMM_Engine engine, int idx, const char *newId) |
Rename the rain gage at idx to newId. Returns SWMM_ERR_BADPARAM if newId is null, empty, already in use, or idx is out of range. | |
| SWMM_ENGINE_API int | swmm_gage_get_rainfall_series_count (SWMM_Engine engine, int idx, int *count) |
| Number of entries in a gage's resolved rainfall series. | |
| SWMM_ENGINE_API int | swmm_gage_get_rainfall_series (SWMM_Engine engine, int idx, double *times, double *values, int count) |
| Copy a gage's resolved rainfall series. | |
| SWMM_ENGINE_API int | swmm_gage_reload_rain_files (SWMM_Engine engine) |
| Re-read every FILE-source rain gage's data from disk. | |
OpenSWMM Engine — Rain Gage C API.
Gage creation, property setters, rainfall get/set, bulk access.
| typedef enum SWMM_GageDataSource SWMM_GageDataSource |
Rain gage data source type.
| typedef enum SWMM_GageRainType SWMM_GageRainType |
Rain gage rainfall data format.
| enum SWMM_GageDataSource |
| enum SWMM_GageRainType |
| SWMM_ENGINE_API int swmm_gage_add | ( | SWMM_Engine | engine, |
| const char * | id ) |
Add a new rain gage to the model.
| engine | Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED). |
| id | Unique null-terminated identifier for the new gage. |
| SWMM_ENGINE_API int swmm_gage_count | ( | SWMM_Engine | engine | ) |
Get the total number of rain gages in the model.
| engine | Engine handle. |
| SWMM_ENGINE_API int swmm_gage_get_data_source | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | source ) |
Get the data source type for a gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | source | Receives the data source code (see SWMM_GageDataSource). |
| SWMM_ENGINE_API int swmm_gage_get_file_column | ( | SWMM_Engine | engine, |
| int | idx, | ||
| char * | buf, | ||
| int | buflen ) |
Get the data column name for a multi-column rain-file gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | buf | Caller buffer that receives the NUL-terminated column name (empty string when none is set). |
| buflen | Size of buf in bytes. |
| SWMM_ENGINE_API int swmm_gage_get_file_format | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | format ) |
Get the rain file format for a file-based gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | format | Receives the RainFileFormat code (-1 = UNKNOWN, 5 = STAN_PRCP standard SWMM rain file, 6 = USER_CSV multi-column CSV/TSV/TSF). Meaningful only when the data source is FILE. |
| SWMM_ENGINE_API int swmm_gage_get_rain_interval | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | seconds ) |
Get the rainfall recording interval for a gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | seconds | Receives the recording interval in seconds. |
| SWMM_ENGINE_API int swmm_gage_get_rain_type | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | type ) |
Get the rainfall data format for a gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | type | Receives the rain type code (see SWMM_GageRainType). |
| SWMM_ENGINE_API int swmm_gage_get_rain_units | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | units ) |
Get the rain-depth units declared for a file-based gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | units | Receives 0 = IN (inches) or 1 = MM (millimetres). |
| SWMM_ENGINE_API int swmm_gage_get_rainfall | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | rainfall ) |
Get current rainfall rate at a gage (project rate units).
| SWMM_ENGINE_API int swmm_gage_get_rainfall_bulk | ( | SWMM_Engine | engine, |
| double * | buf, | ||
| int | count ) |
Get current rainfall rates for all gages in a single call.
| engine | Engine handle. | |
| [out] | buf | Caller-allocated buffer of at least count doubles. |
| count | Number of elements (should equal swmm_gage_count()). |
| SWMM_ENGINE_API int swmm_gage_get_rainfall_series | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | times, | ||
| double * | values, | ||
| int | count ) |
Copy a gage's resolved rainfall series.
Returns the rainfall the engine will ACTUALLY apply, so a caller never has to know how a gage stores its data. The rain-type transform, the rain-file units factor, and the gage scale factor are all applied, using the same conversion the routing update runs — so a series read back here and replayed through a TIMESERIES gage of type INTENSITY reproduces the original gage.
Each entry is the intensity that applies from its own time stamp until the recording interval elapses or the next entry begins, whichever comes first; rainfall is zero in between. Pair this with swmm_gage_get_rain_interval() to reconstruct that behaviour.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | times | Receives entry times as SWMM DateTime (decimal days), matching swmm_table_get_point(). May be NULL. |
| [out] | values | Receives rainfall INTENSITY in the project's rain units per hour (in/hr for US flow units, mm/hr for SI). May be NULL. |
| count | Capacity of each output array; at most this many entries are written. |
| SWMM_ENGINE_API int swmm_gage_get_rainfall_series_count | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int * | count ) |
Number of entries in a gage's resolved rainfall series.
Works for both data sources: a TIMESERIES gage reports its table's length, a FILE gage the length of the series loaded from disk at open. A FILE gage reports 0 when its file could not be read or its format is not one the engine loads — in which case that gage also contributes no rainfall to the run.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | count | Receives the entry count. |
| SWMM_ENGINE_API int swmm_gage_get_scale_factor | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | factor ) |
Get the rainfall scaling factor for a gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | factor | Receives the current scaling factor (1.0 = no scaling). |
| SWMM_ENGINE_API int swmm_gage_get_snow_factor | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double * | factor ) |
Get the snow-catch deficiency correction factor (SCF) for a gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | factor | Receives the current correction factor (1.0 = none). |
| SWMM_ENGINE_API int swmm_gage_get_station_id | ( | SWMM_Engine | engine, |
| int | idx, | ||
| char * | buf, | ||
| int | buflen ) |
Get the station id for a file-based gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | buf | Caller buffer that receives the NUL-terminated station id (empty string when none is set). |
| buflen | Size of buf in bytes. |
| SWMM_ENGINE_API int swmm_gage_get_timeseries | ( | SWMM_Engine | engine, |
| int | idx, | ||
| char * | buf, | ||
| int | buflen ) |
Get the assigned time series id for a TIMESERIES-source gage.
| engine | Engine handle. | |
| idx | Zero-based gage index. | |
| [out] | buf | Caller buffer that receives the NUL-terminated id (empty string when no series is assigned). |
| buflen | Size of buf in bytes. |
| SWMM_ENGINE_API const char * swmm_gage_id | ( | SWMM_Engine | engine, |
| int | idx ) |
Get the string identifier of a rain gage by index.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| SWMM_ENGINE_API int swmm_gage_index | ( | SWMM_Engine | engine, |
| const char * | id ) |
Look up a rain gage's zero-based index by its string identifier.
| engine | Engine handle. |
| id | Null-terminated gage identifier. |
| SWMM_ENGINE_API int swmm_gage_reload_rain_files | ( | SWMM_Engine | engine | ) |
Re-read every FILE-source rain gage's data from disk.
Rain files are loaded once, during open(). Nothing re-runs that afterwards, so changing a gage's path, station id, or rain units — or the simulation dates the data is windowed to — has no effect until the model is reopened, and readers keep seeing the previous file's contents. Call this after such an edit.
Rebuilds the resolved series and the rainfall-file summary statistics for every FILE gage. Requires the model to be editable (BUILDING or OPENED); it is not valid mid-run.
| engine | Engine handle. |
| SWMM_ENGINE_API int swmm_gage_rename | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | newId ) |
Rename the rain gage at idx to newId. Returns SWMM_ERR_BADPARAM if newId is null, empty, already in use, or idx is out of range.
| SWMM_ENGINE_API int swmm_gage_set_data_source | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | source ) |
Set the data source type for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| source | Data source (see SWMM_GageDataSource). |
| SWMM_ENGINE_API int swmm_gage_set_file_column | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | column ) |
Set the data column name for a multi-column rain-file gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| column | Column header name inside the file (empty = use the first data column). |
Stores the column selector used by the "FILE path:col" form (multi-column CSV/TSV/TSF). Setting a non-empty column switches the gage's file format to USER_CSV; clearing it leaves the format unchanged (an empty column on a USER_CSV gage reads the file's first data column).
| SWMM_ENGINE_API int swmm_gage_set_file_format | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | format ) |
Set the rain file format for a file-based gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| format | RainFileFormat code (-1 = UNKNOWN, 5 = STAN_PRCP standard SWMM rain file, 6 = USER_CSV multi-column CSV/TSV/TSF). |
The counterpart of swmm_gage_get_file_format(), and the only way back out of USER_CSV: swmm_gage_set_file_column() and swmm_gage_set_filename() both preserve USER_CSV by design, so without this a host that ever set a column could not return the gage to a standard rain file.
The two formats' row selectors are mutually exclusive, so this clears the one that does not apply: selecting USER_CSV clears the gage's station_id (a multi-column file has no station column), and selecting any station-based format — STAN_PRCP included — clears its file column name.
| SWMM_ENGINE_API int swmm_gage_set_filename | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | path, | ||
| const char * | station_id ) |
Assign an external rainfall file as the data source for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| path | File path to the external rainfall file. |
| station_id | Station identifier within the file (standard SWMM rain file grammar Fname Station Units). |
Sets the data source to FILE. The file format is preserved when the gage is already USER_CSV (multi-column "path:col"), otherwise it is auto-detected: a non-empty file column implies USER_CSV and anything else selects the standard SWMM rain file format (STAN_PRCP). The station id is stored in the gage's station_id slot (the token matched against the file's first column), not the CSV column-name slot — see swmm_gage_set_file_column().
| SWMM_ENGINE_API int swmm_gage_set_rain_interval | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | seconds ) |
Set the rainfall recording interval for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| seconds | Recording interval in seconds. |
| SWMM_ENGINE_API int swmm_gage_set_rain_type | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | type ) |
Set the rainfall data format for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| type | Rainfall type (see SWMM_GageRainType). |
| SWMM_ENGINE_API int swmm_gage_set_rain_units | ( | SWMM_Engine | engine, |
| int | idx, | ||
| int | units ) |
Set the rain-depth units declared for a file-based gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| units | 0 = IN (inches), 1 = MM (millimetres). |
| SWMM_ENGINE_API int swmm_gage_set_rainfall | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | rainfall ) |
Override rainfall at a gage for the current timestep.
Overrides gage-driven rainfall for all subcatchments that use this gage. Applied for one timestep only.
| SWMM_ENGINE_API int swmm_gage_set_scale_factor | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | factor ) |
Set the rainfall scaling factor for a gage.
The scaling factor multiplies the gage's rainfall intensity after rain-type and unit conversion. May be changed at any time (including while the simulation is RUNNING) to support parameter sweeps; the new value takes effect on the next timestep.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| factor | Strictly positive scaling factor (1.0 = no scaling). |
| SWMM_ENGINE_API int swmm_gage_set_snow_factor | ( | SWMM_Engine | engine, |
| int | idx, | ||
| double | factor ) |
Set the snow-catch deficiency correction factor (SCF) for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| factor | Strictly positive correction factor (1.0 = no correction). |
| SWMM_ENGINE_API int swmm_gage_set_station_id | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | station_id ) |
Set the station id for a file-based gage (standard SWMM rain file).
| engine | Engine handle. |
| idx | Zero-based gage index. |
| station_id | Station identifier within the file ("*" or empty = all rows). |
| SWMM_ENGINE_API int swmm_gage_set_timeseries | ( | SWMM_Engine | engine, |
| int | idx, | ||
| const char * | ts_id ) |
Assign a time series as the data source for a gage.
| engine | Engine handle. |
| idx | Zero-based gage index. |
| ts_id | Null-terminated time series identifier. |