openswmm_callbacks.h File Reference

Callback function typedefs for the OpenSWMM Engine C API. More...

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

Go to the source code of this file.

Typedefs
typedef void *	SWMM_Engine
	Opaque handle to an OpenSWMM Engine instance.
typedef void(*	SWMM_ProgressCallback) (SWMM_Engine engine, double elapsed_frac, double sim_time, void *user_data)
	Called after each simulation timestep to report progress.
typedef void(*	SWMM_WarningCallback) (SWMM_Engine engine, int code, const char *message, void *user_data)
	Called when the engine emits a warning or non-fatal error.
typedef void(*	SWMM_StepBeginCallback) (SWMM_Engine engine, double sim_time, double dt, void *user_data)
	Called at the beginning of each simulation timestep, before physics.
typedef void(*	SWMM_StepEndCallback) (SWMM_Engine engine, double sim_time, double dt, void *user_data)
	Called at the end of each simulation timestep, after physics.
typedef void(*	SWMM_PluginStateCallback) (SWMM_Engine engine, const char *plugin_id, int old_state, int new_state, void *user_data)
	Called when a plugin changes state.
typedef void(*	SWMM_HotStartMissingCallback) (SWMM_Engine engine, const char *object_type, const char *object_id, void *user_data)
	Called for each object that was missing when applying a hot start.

Detailed Description

Callback function typedefs for the OpenSWMM Engine C API.

Callbacks allow host applications to receive runtime notifications from the simulation engine without polling. Register callbacks via the corresponding swmm_set_*_callback() functions.

All callbacks are invoked on the main simulation thread unless otherwise noted. Callbacks must be thread-safe with respect to the IO thread (i.e., do not modify simulation state from within a callback unless the engine is in a safe state).

Note

All callback function pointers accept a void* user_data parameter that is passed through unmodified from registration. Use this to carry context (e.g., a Python capsule, a C++ object pointer, etc.).

See also

openswmm_engine.h for registration functions.

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_Engine

typedef void* SWMM_Engine

Opaque handle to an OpenSWMM Engine instance.

SWMM_HotStartMissingCallback

typedef void(* SWMM_HotStartMissingCallback) (SWMM_Engine engine, const char *object_type, const char *object_id, void *user_data)

Called for each object that was missing when applying a hot start.

Allows the host application to log or react to missing objects.

Parameters

engine	The engine handle.
object_type	Type string: "NODE", "LINK", "SUBCATCH", "FLAG".
object_id	Null-terminated identifier of the missing object.
user_data	User-supplied context pointer.

SWMM_PluginStateCallback

typedef void(* SWMM_PluginStateCallback) (SWMM_Engine engine, const char *plugin_id, int old_state, int new_state, void *user_data)

Called when a plugin changes state.

Parameters

engine	The engine handle.
plugin_id	Null-terminated plugin identifier (reverse-DNS string).
old_state	Previous plugin state (SWMM_PluginState enum value).
new_state	New plugin state.
user_data	User-supplied context pointer.

SWMM_ProgressCallback

typedef void(* SWMM_ProgressCallback) (SWMM_Engine engine, double elapsed_frac, double sim_time, void *user_data)

Called after each simulation timestep to report progress.

Invoked from inside swmm_engine_step() after advancing the simulation by one timestep. The callback receives the current elapsed fraction (0.0 to 1.0) and absolute simulation time.

Parameters

engine	The engine handle that fired the callback.
elapsed_frac	Fraction of simulation complete [0.0, 1.0].
sim_time	Current simulation time in decimal days (Julian date).
user_data	User-supplied context pointer from registration.

Note

This callback is called on every physical timestep, which may be very frequent. Keep the callback implementation lightweight.

Example (C):

void my_progress(SWMM_Engine e, double frac, double t, void* ud) {
    printf("Progress: %.1f%%  t=%.4f days\n", frac * 100.0, t);
}
swmm_set_progress_callback(engine, my_progress, NULL);

SWMM_StepBeginCallback

typedef void(* SWMM_StepBeginCallback) (SWMM_Engine engine, double sim_time, double dt, void *user_data)

Called at the beginning of each simulation timestep, before physics.

This is the correct place to inject external forcings or modify boundary conditions before the engine advances the simulation.

Parameters

engine	The engine handle.
sim_time	Current simulation time (start of this step) in decimal days.
dt	Timestep duration in seconds.
user_data	User-supplied context pointer.

SWMM_StepEndCallback

typedef void(* SWMM_StepEndCallback) (SWMM_Engine engine, double sim_time, double dt, void *user_data)

Called at the end of each simulation timestep, after physics.

This is the correct place to read simulation results for real-time monitoring or control decisions.

Parameters

engine	The engine handle.
sim_time	Simulation time at the END of this step in decimal days.
dt	Timestep duration in seconds that was just completed.
user_data	User-supplied context pointer.

SWMM_WarningCallback

typedef void(* SWMM_WarningCallback) (SWMM_Engine engine, int code, const char *message, void *user_data)

Called when the engine emits a warning or non-fatal error.

Warnings are issued for recoverable situations such as:

• Missing objects during hot start application
• Deprecated input section keywords
• Numerical instabilities that were handled gracefully
• Plugin initialization issues

Parameters

engine	The engine handle that fired the callback.
code	Warning/error code (see SWMM_WarnCode enum in openswmm_engine.h).
message	Null-terminated human-readable warning message.
user_data	User-supplied context pointer from registration.