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

OpenSWMM Engine — Rain Gage C API. More...

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

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.
 

Detailed Description

OpenSWMM Engine — Rain Gage C API.

Gage creation, property setters, rainfall get/set, bulk access.

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

Typedef Documentation

◆ SWMM_GageDataSource

Rain gage data source type.

◆ SWMM_GageRainType

Rain gage rainfall data format.

Enumeration Type Documentation

◆ SWMM_GageDataSource

Rain gage data source type.

Enumerator
SWMM_GAGE_TIMESERIES 

Rainfall data from an in-model time series.

SWMM_GAGE_FILE 

Rainfall data from an external file.

◆ SWMM_GageRainType

Rain gage rainfall data format.

Enumerator
SWMM_RAIN_INTENSITY 

Rainfall given as intensity (rate).

SWMM_RAIN_VOLUME 

Rainfall given as depth per interval.

SWMM_RAIN_CUMULATIVE 

Rainfall given as cumulative depth.

Function Documentation

◆ swmm_gage_add()

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

Add a new rain gage to the model.

Parameters
engineEngine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
idUnique null-terminated identifier for the new gage.
Returns
SWMM_OK on success, SWMM_ERR_LIFECYCLE if not in an editable state, or another error code.

◆ swmm_gage_count()

SWMM_ENGINE_API int swmm_gage_count ( SWMM_Engine engine)

Get the total number of rain gages in the model.

Parameters
engineEngine handle.
Returns
Number of gages, or -1 on error.

◆ swmm_gage_get_data_source()

SWMM_ENGINE_API int swmm_gage_get_data_source ( SWMM_Engine engine,
int idx,
int * source )

Get the data source type for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]sourceReceives the data source code (see SWMM_GageDataSource).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_file_column()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]bufCaller buffer that receives the NUL-terminated column name (empty string when none is set).
buflenSize of buf in bytes.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_file_format()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]formatReceives 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.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_rain_interval()

SWMM_ENGINE_API int swmm_gage_get_rain_interval ( SWMM_Engine engine,
int idx,
double * seconds )

Get the rainfall recording interval for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]secondsReceives the recording interval in seconds.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_rain_type()

SWMM_ENGINE_API int swmm_gage_get_rain_type ( SWMM_Engine engine,
int idx,
int * type )

Get the rainfall data format for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]typeReceives the rain type code (see SWMM_GageRainType).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_rain_units()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]unitsReceives 0 = IN (inches) or 1 = MM (millimetres).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_rainfall()

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_gage_get_rainfall_bulk()

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.

Parameters
engineEngine handle.
[out]bufCaller-allocated buffer of at least count doubles.
countNumber of elements (should equal swmm_gage_count()).
Returns
SWMM_OK on success, or an error code.

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

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.

Note
A FILE gage's series is windowed to the [OPTIONS] simulation dates (± one day) and reflects the file as it was read at open. Call swmm_gage_reload_rain_files() first if the path, station, units, or simulation dates have changed since.
Parameters
engineEngine handle.
idxZero-based gage index.
[out]timesReceives entry times as SWMM DateTime (decimal days), matching swmm_table_get_point(). May be NULL.
[out]valuesReceives rainfall INTENSITY in the project's rain units per hour (in/hr for US flow units, mm/hr for SI). May be NULL.
countCapacity of each output array; at most this many entries are written.
Returns
SWMM_OK on success, or an error code.
Here is the call graph for this function:

◆ swmm_gage_get_rainfall_series_count()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]countReceives the entry count.
Returns
SWMM_OK on success, or an error code.
Here is the call graph for this function:

◆ swmm_gage_get_scale_factor()

SWMM_ENGINE_API int swmm_gage_get_scale_factor ( SWMM_Engine engine,
int idx,
double * factor )

Get the rainfall scaling factor for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]factorReceives the current scaling factor (1.0 = no scaling).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_snow_factor()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]factorReceives the current correction factor (1.0 = none).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_station_id()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]bufCaller buffer that receives the NUL-terminated station id (empty string when none is set).
buflenSize of buf in bytes.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_get_timeseries()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
[out]bufCaller buffer that receives the NUL-terminated id (empty string when no series is assigned).
buflenSize of buf in bytes.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_id()

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

Get the string identifier of a rain gage by index.

Parameters
engineEngine handle.
idxZero-based gage index.
Returns
Null-terminated string owned by the engine, or NULL on error.

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

Parameters
engineEngine handle.
idNull-terminated gage identifier.
Returns
Zero-based index, or -1 if not found.

◆ swmm_gage_reload_rain_files()

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.

Parameters
engineEngine handle.
Returns
SWMM_OK on success, or an error code.
Here is the call graph for this function:

◆ swmm_gage_rename()

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_gage_set_data_source()

SWMM_ENGINE_API int swmm_gage_set_data_source ( SWMM_Engine engine,
int idx,
int source )

Set the data source type for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
sourceData source (see SWMM_GageDataSource).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_set_file_column()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
columnColumn header name inside the file (empty = use the first data column).
Returns
SWMM_OK on success, or an error code.

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_gage_set_file_format()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
formatRainFileFormat code (-1 = UNKNOWN, 5 = STAN_PRCP standard SWMM rain file, 6 = USER_CSV multi-column CSV/TSV/TSF).
Returns
SWMM_OK on success, or SWMM_ERR_BADPARAM for a code that is not a RainFileFormat value.

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_gage_set_filename()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
pathFile path to the external rainfall file.
station_idStation identifier within the file (standard SWMM rain file grammar Fname Station Units).
Returns
SWMM_OK on success, or an error code.

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_gage_set_rain_interval()

SWMM_ENGINE_API int swmm_gage_set_rain_interval ( SWMM_Engine engine,
int idx,
double seconds )

Set the rainfall recording interval for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
secondsRecording interval in seconds.
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_set_rain_type()

SWMM_ENGINE_API int swmm_gage_set_rain_type ( SWMM_Engine engine,
int idx,
int type )

Set the rainfall data format for a gage.

Parameters
engineEngine handle.
idxZero-based gage index.
typeRainfall type (see SWMM_GageRainType).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_set_rain_units()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
units0 = IN (inches), 1 = MM (millimetres).
Returns
SWMM_OK on success; SWMM_ERR_BADPARAM if units not in {0,1}.

◆ swmm_gage_set_rainfall()

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_gage_set_scale_factor()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
factorStrictly positive scaling factor (1.0 = no scaling).
Returns
SWMM_OK on success; SWMM_ERR_BADPARAM if factor <= 0.0.

◆ swmm_gage_set_snow_factor()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
factorStrictly positive correction factor (1.0 = no correction).
Returns
SWMM_OK on success; SWMM_ERR_BADPARAM if factor <= 0.0.

◆ swmm_gage_set_station_id()

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

Parameters
engineEngine handle.
idxZero-based gage index.
station_idStation identifier within the file ("*" or empty = all rows).
Returns
SWMM_OK on success, or an error code.

◆ swmm_gage_set_timeseries()

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.

Parameters
engineEngine handle.
idxZero-based gage index.
ts_idNull-terminated time series identifier.
Returns
SWMM_OK on success, or an error code.