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

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

Copyright

Copyright (c) 2026 Caleb Buahin. All rights reserved.

License\n MIT License

Typedef Documentation

SWMM_GageDataSource

typedef enum SWMM_GageDataSource SWMM_GageDataSource

Rain gage data source type.

SWMM_GageRainType

typedef enum SWMM_GageRainType SWMM_GageRainType

Rain gage rainfall data format.

Enumeration Type Documentation

SWMM_GageDataSource

enum 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

enum 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

engine	Engine handle (SWMM_STATE_BUILDING or SWMM_STATE_OPENED).
id	Unique 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

engine

Engine 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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	source	Receives the data source code (see SWMM_GageDataSource).

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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	seconds	Receives 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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	type	Receives 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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	units	Receives 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

	engine	Engine handle.
[out]	buf	Caller-allocated buffer of at least count doubles.
	count	Number of elements (should equal swmm_gage_count()).

Returns

SWMM_OK on success, or an error code.

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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	factor	Receives 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

	engine	Engine handle.
	idx	Zero-based gage index.
[out]	factor	Receives 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

	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.

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

	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.

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

engine	Engine handle.
idx	Zero-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

engine	Engine handle.
id	Null-terminated gage identifier.

Returns

Zero-based index, or -1 if not found.

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

engine	Engine handle.
idx	Zero-based gage index.
source	Data source (see SWMM_GageDataSource).

Returns

SWMM_OK on success, or an error code.

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

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

Returns

SWMM_OK on success, or an error code.

Sets the data source to FILE and 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.

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

engine	Engine handle.
idx	Zero-based gage index.
seconds	Recording 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

engine	Engine handle.
idx	Zero-based gage index.
type	Rainfall 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

engine	Engine handle.
idx	Zero-based gage index.
units	0 = 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

engine	Engine handle.
idx	Zero-based gage index.
factor	Strictly 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

engine	Engine handle.
idx	Zero-based gage index.
factor	Strictly 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

engine	Engine handle.
idx	Zero-based gage index.
station_id	Station 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

engine	Engine handle.
idx	Zero-based gage index.
ts_id	Null-terminated time series identifier.

Returns

SWMM_OK on success, or an error code.