openswmm_controls.h File Reference

OpenSWMM Engine — Control Rules C API. More...

#include "openswmm_engine.h"

Include dependency graph for openswmm_controls.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
SWMM_ENGINE_API int	swmm_control_add_rule (SWMM_Engine engine, const char *rule_text)
	Add a control rule from its text representation.
SWMM_ENGINE_API int	swmm_control_count (SWMM_Engine engine)
	Get the total number of control rules defined.
SWMM_ENGINE_API int	swmm_control_get_rule (SWMM_Engine engine, int idx, char *buf, int buflen)
	Get the text of a control rule by index.
SWMM_ENGINE_API int	swmm_control_clear_rules (SWMM_Engine engine)
	Remove all control rules from the model.
SWMM_ENGINE_API int	swmm_control_set_link_setting (SWMM_Engine engine, int link_idx, double setting)
	Directly set the control setting of a link.
SWMM_ENGINE_API int	swmm_control_set_link_status (SWMM_Engine engine, int link_idx, int status)
	Directly set the open/close status of a link.

Detailed Description

OpenSWMM Engine — Control Rules C API.

Control rule addition, retrieval, clearing, and direct link setting/status overrides.

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

Function Documentation

swmm_control_add_rule()

SWMM_ENGINE_API int swmm_control_add_rule	(	SWMM_Engine	engine,
		const char *	rule_text
	)

Add a control rule from its text representation.

The rule text follows the standard SWMM control rule syntax (e.g., "RULE R1\\nIF NODE J1 DEPTH > 5\\nTHEN PUMP P1 STATUS = ON"). Lines are separated by newline characters within the string.

Parameters

engine	Engine handle.
rule_text	Null-terminated string containing the full rule text.

Returns

SWMM_OK on success, or an error code.

swmm_control_clear_rules()

SWMM_ENGINE_API int swmm_control_clear_rules

(

SWMM_Engine

engine

)

Remove all control rules from the model.

Parameters

engine

Engine handle.

Returns

SWMM_OK on success, or an error code.

swmm_control_count()

SWMM_ENGINE_API int swmm_control_count

(

SWMM_Engine

engine

)

Get the total number of control rules defined.

Parameters

engine

Engine handle.

Returns

Number of control rules, or -1 on error.

swmm_control_get_rule()

SWMM_ENGINE_API int swmm_control_get_rule	(	SWMM_Engine	engine,
		int	idx,
		char *	buf,
		int	buflen
	)

Get the text of a control rule by index.

Parameters

engine	Engine handle.
idx	Zero-based rule index.
buf	Caller-allocated buffer to receive the rule text.
buflen	Size of buf in bytes.

Returns

SWMM_OK on success, or an error code.

swmm_control_set_link_setting()

SWMM_ENGINE_API int swmm_control_set_link_setting	(	SWMM_Engine	engine,
		int	link_idx,
		double	setting
	)

Directly set the control setting of a link.

Bypasses the control rule engine. For pumps: 0.0=off, 1.0=full. For orifices/weirs: fractional opening [0, 1].

Parameters

engine	Engine handle (RUNNING state).
link_idx	Zero-based link index.
setting	Setting value.

Returns

SWMM_OK on success, or an error code.

swmm_control_set_link_status()

SWMM_ENGINE_API int swmm_control_set_link_status	(	SWMM_Engine	engine,
		int	link_idx,
		int	status
	)

Directly set the open/close status of a link.

Bypasses the control rule engine. Status: 0=closed, 1=open.

Parameters

engine	Engine handle (RUNNING state).
link_idx	Zero-based link index.
status	0 for closed, non-zero for open.

Returns

SWMM_OK on success, or an error code.