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

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 HydroCouple. 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).
id	Unique null-terminated identifier for the new gage.

Returns

SWMM_OK on success, or an 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_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_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_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_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.

Returns

SWMM_OK on success, or an error code.

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