openswmm_gages_impl.cpp File Reference

C API implementation — rain gage identity, creation, properties, state, bulk. More...

#include "openswmm_api_common.hpp"
#include "../../../include/openswmm/engine/openswmm_gages.h"

Include dependency graph for openswmm_gages_impl.cpp:

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

C API implementation — rain gage identity, creation, properties, state, bulk.

See also

include/openswmm/engine/openswmm_gages.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

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.