C FFI wrapper for the OutputReader class. More...

#include "../../../include/openswmm/engine/openswmm_output.h"
#include "OutputReader.hpp"

Include dependency graph for openswmm_output_impl.cpp:

Macros
#define	CHECK_READER(h)

Functions
SWMM_ENGINE_API SWMM_Output	swmm_output_open (const char *path)
	Open a binary output file for reading.

SWMM_ENGINE_API SWMM_Output	swmm_output_open_live (const char *path)
	Open a binary output file that is still being written.

SWMM_ENGINE_API int	swmm_output_refresh (SWMM_Output handle, int *periods)
	Re-count the periods of a file opened with swmm_output_open_live().

SWMM_ENGINE_API int	swmm_output_is_live (SWMM_Output handle)
	1 while a handle from swmm_output_open_live() has not yet seen the closing records, 0 otherwise, -1 on NULL.

SWMM_ENGINE_API void	swmm_output_close (SWMM_Output handle)
	Close the output file and free all resources.

SWMM_ENGINE_API int	swmm_output_get_version (SWMM_Output handle)
	Get the SWMM version stored in the output file.

SWMM_ENGINE_API int	swmm_output_get_flow_units (SWMM_Output handle)
	Get the flow units code.

SWMM_ENGINE_API int	swmm_output_get_subcatch_count (SWMM_Output handle)
	Get the number of subcatchments in the output file.

SWMM_ENGINE_API int	swmm_output_get_node_count (SWMM_Output handle)
	Get the number of nodes in the output file.

SWMM_ENGINE_API int	swmm_output_get_link_count (SWMM_Output handle)
	Get the number of links in the output file.

SWMM_ENGINE_API int	swmm_output_get_pollut_count (SWMM_Output handle)
	Get the number of pollutants in the output file.

SWMM_ENGINE_API int	swmm_output_get_period_count (SWMM_Output handle)
	Get the number of reporting periods (timesteps) in the output file.

SWMM_ENGINE_API int	swmm_output_get_start_date (SWMM_Output handle, double *start_date)
	Get the simulation start date as a SWMM DateTime double.

SWMM_ENGINE_API int	swmm_output_get_report_step (SWMM_Output handle)
	Get the report step in seconds.

SWMM_ENGINE_API const char *	swmm_output_get_subcatch_id (SWMM_Output handle, int index)
	Get the string ID of a subcatchment by index.

SWMM_ENGINE_API const char *	swmm_output_get_node_id (SWMM_Output handle, int index)
	Get the string ID of a node by index.

SWMM_ENGINE_API const char *	swmm_output_get_link_id (SWMM_Output handle, int index)
	Get the string ID of a link by index.

SWMM_ENGINE_API const char *	swmm_output_get_pollut_id (SWMM_Output handle, int index)
	Get the string ID of a species (pollutant) column by index.

SWMM_ENGINE_API int	swmm_output_get_subcatch_result (SWMM_Output handle, int period, int var, float *values)
	Get one subcatchment variable for all subcatchments at a given period.

SWMM_ENGINE_API int	swmm_output_get_node_result (SWMM_Output handle, int period, int var, float *values)
	Get one node variable for all nodes at a given period.

SWMM_ENGINE_API int	swmm_output_get_link_result (SWMM_Output handle, int period, int var, float *values)
	Get one link variable for all links at a given period.

SWMM_ENGINE_API int	swmm_output_get_system_result (SWMM_Output handle, int period, int var, float *value)
	Get system-wide results at a given period.

SWMM_ENGINE_API int	swmm_output_get_subcatch_series (SWMM_Output handle, int subcatch_idx, int var, int start_period, int end_period, float *values)
	Get a subcatchment variable time series across a range of periods.

SWMM_ENGINE_API int	swmm_output_get_node_series (SWMM_Output handle, int node_idx, int var, int start_period, int end_period, float *values)
	Get a node variable time series across a range of periods.

SWMM_ENGINE_API int	swmm_output_get_link_series (SWMM_Output handle, int link_idx, int var, int start_period, int end_period, float *values)
	Get a link variable time series across a range of periods.

SWMM_ENGINE_API int	swmm_output_get_system_series (SWMM_Output handle, int var, int start_period, int end_period, float *values)
	Get a system variable time series across a range of periods.

SWMM_ENGINE_API int	swmm_output_get_subcatch_attribute (SWMM_Output handle, int subcatch_idx, int period, float values, int count)
	Get all result variables for a single subcatchment at one period.

SWMM_ENGINE_API int	swmm_output_get_node_attribute (SWMM_Output handle, int node_idx, int period, float values, int count)
	Get all result variables for a single node at one period.

SWMM_ENGINE_API int	swmm_output_get_link_attribute (SWMM_Output handle, int link_idx, int period, float values, int count)
	Get all result variables for a single link at one period.

SWMM_ENGINE_API int	swmm_output_get_period_time (SWMM_Output handle, int period, double *time)
	Get the simulation time for a given period as a SWMM DateTime double.

SWMM_ENGINE_API int	swmm_output_get_node_stat_max_depth (SWMM_Output handle, int node_idx, double *value)
	Maximum node depth across all reporting periods.

SWMM_ENGINE_API int	swmm_output_get_node_stat_max_overflow (SWMM_Output handle, int node_idx, double *value)
	Maximum node overflow rate across all reporting periods.

SWMM_ENGINE_API int	swmm_output_get_node_stat_vol_flooded (SWMM_Output handle, int node_idx, double *value)
	Total flood volume at the node across the simulation.

SWMM_ENGINE_API int	swmm_output_get_node_stat_time_flooded (SWMM_Output handle, int node_idx, double *value)
	Total time the node was flooded across the simulation.

SWMM_ENGINE_API int	swmm_output_get_error_code (SWMM_Output handle)
	Get the error code stored in the output file footer.

Detailed Description

C FFI wrapper for the OutputReader class.

Maps the C API declared in openswmm_output.h to the C++ OutputReader implementation. Each function casts the opaque SWMM_Output handle to an OutputReader pointer.

See also: openswmm_output.h — public C API; OutputReader.hpp — internal C++ reader

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 Apache-2.0

Macro Definition Documentation

◆ CHECK_READER

#define CHECK_READER ( h )

Value:

do { if (!(h)) return -1; } while(0)

Function Documentation

◆ swmm_output_close()

SWMM_ENGINE_API void swmm_output_close ( SWMM_Output handle )

Close the output file and free all resources.

Parameters

handle Output reader handle (NULL safe).

◆ swmm_output_get_error_code()

SWMM_ENGINE_API int swmm_output_get_error_code ( SWMM_Output handle )

Get the error code stored in the output file footer.

Parameters

handle Output reader handle.

Returns: Error code from the simulation (0 = success), or -1 on reader error.

◆ swmm_output_get_flow_units()

SWMM_ENGINE_API int swmm_output_get_flow_units ( SWMM_Output handle )

Get the flow units code.

Parameters

handle Output reader handle.

Returns: Flow units code (0=CFS, 1=GPM, 2=MGD, 3=CMS, 4=LPS, 5=MLD), or -1 on error.

◆ swmm_output_get_link_attribute()

SWMM_ENGINE_API int swmm_output_get_link_attribute	(	SWMM_Output	handle,
		int	link_idx,
		int	period,
		float *	values,
		int *	count )

Get all result variables for a single link at one period.

Parameters

handle	Output reader handle.
link_idx	Zero-based link index.
period	Zero-based period index.
values	Caller-allocated array of n_link_vars floats.
count	Pointer to receive the number of variables written.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_link_count()

SWMM_ENGINE_API int swmm_output_get_link_count ( SWMM_Output handle )

Get the number of links in the output file.

Parameters

handle Output reader handle.

Returns: Link count, or -1 on error.

◆ swmm_output_get_link_id()

SWMM_ENGINE_API const char * swmm_output_get_link_id	(	SWMM_Output	handle,
		int	index )

Get the string ID of a link by index.

Parameters

handle	Output reader handle.
index	Zero-based link index.

Returns: Null-terminated string owned by the reader, or NULL on error.

◆ swmm_output_get_link_result()

SWMM_ENGINE_API int swmm_output_get_link_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Get one link variable for all links at a given period.

Parameters

handle	Output reader handle.
period	Zero-based period index.
var	Link variable (see SWMM_OutLinkVar).
values	Caller-allocated array of at least link_count floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_link_series()

SWMM_ENGINE_API int swmm_output_get_link_series	(	SWMM_Output	handle,
		int	link_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Get a link variable time series across a range of periods.

Parameters

handle	Output reader handle.
link_idx	Zero-based link index.
var	Link variable.
start_period	First period (inclusive, zero-based).
end_period	Last period (inclusive, zero-based).
values	Caller-allocated array of (end_period - start_period + 1) floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_node_attribute()

SWMM_ENGINE_API int swmm_output_get_node_attribute	(	SWMM_Output	handle,
		int	node_idx,
		int	period,
		float *	values,
		int *	count )

Get all result variables for a single node at one period.

Parameters

handle	Output reader handle.
node_idx	Zero-based node index.
period	Zero-based period index.
values	Caller-allocated array of n_node_vars floats.
count	Pointer to receive the number of variables written.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_node_count()

SWMM_ENGINE_API int swmm_output_get_node_count ( SWMM_Output handle )

Get the number of nodes in the output file.

Parameters

handle Output reader handle.

Returns: Node count, or -1 on error.

◆ swmm_output_get_node_id()

SWMM_ENGINE_API const char * swmm_output_get_node_id	(	SWMM_Output	handle,
		int	index )

Get the string ID of a node by index.

Parameters

handle	Output reader handle.
index	Zero-based node index.

Returns: Null-terminated string owned by the reader, or NULL on error.

◆ swmm_output_get_node_result()

SWMM_ENGINE_API int swmm_output_get_node_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Get one node variable for all nodes at a given period.

Parameters

handle	Output reader handle.
period	Zero-based period index.
var	Node variable (see SWMM_OutNodeVar).
values	Caller-allocated array of at least node_count floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_node_series()

SWMM_ENGINE_API int swmm_output_get_node_series	(	SWMM_Output	handle,
		int	node_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Get a node variable time series across a range of periods.

Parameters

handle	Output reader handle.
node_idx	Zero-based node index.
var	Node variable.
start_period	First period (inclusive, zero-based).
end_period	Last period (inclusive, zero-based).
values	Caller-allocated array of (end_period - start_period + 1) floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_node_stat_max_depth()

SWMM_ENGINE_API int swmm_output_get_node_stat_max_depth	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Maximum node depth across all reporting periods.

Computes max(SWMM_OUT_NODE_DEPTH) over the open file's period range. Result is in the model's length units (ft / m).

Parameters

handle	Output reader handle.
node_idx	Zero-based node index (0 .. node_count - 1).
value	[out] Maximum depth on success; unchanged on error.

Returns: 0 on success, -1 on error (bad handle, index out of range, or I/O failure during aggregation).

◆ swmm_output_get_node_stat_max_overflow()

SWMM_ENGINE_API int swmm_output_get_node_stat_max_overflow	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Maximum node overflow rate across all reporting periods.

Computes max(SWMM_OUT_NODE_OVERFLOW) over the open file's period range. Result is in the file's flow units (see swmm_output_get_flow_units).

◆ swmm_output_get_node_stat_time_flooded()

SWMM_ENGINE_API int swmm_output_get_node_stat_time_flooded	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Total time the node was flooded across the simulation.

Counts the report periods where overflow > 0 and multiplies by the file's report-step seconds. Result is in seconds — matching swmm_node_get_stat_time_flooded units. Divide by 3600 for hours (the convention SWMM's statsrpt uses for display).

◆ swmm_output_get_node_stat_vol_flooded()

SWMM_ENGINE_API int swmm_output_get_node_stat_vol_flooded	(	SWMM_Output	handle,
		int	node_idx,
		double *	value )

Total flood volume at the node across the simulation.

Aggregates sum(overflow_i * report_step) over the periods where overflow > 0. Result is in cubic feet (US) or cubic metres (SI) — matching swmm_node_get_stat_vol_flooded units. Returns 0 when the file has no positive-overflow periods.

◆ swmm_output_get_period_count()

SWMM_ENGINE_API int swmm_output_get_period_count ( SWMM_Output handle )

Get the number of reporting periods (timesteps) in the output file.

Parameters

handle Output reader handle.

Returns: Period count, or -1 on error.

◆ swmm_output_get_period_time()

SWMM_ENGINE_API int swmm_output_get_period_time	(	SWMM_Output	handle,
		int	period,
		double *	time )

Get the simulation time for a given period as a SWMM DateTime double.

The value is the same SWMM DateTime convention used elsewhere in the API: integer days since 1899-12-30 plus fractional time of day. Use the helpers in openswmm_datetime.h to convert to a calendar date/time.

Parameters

handle	Output reader handle.
period	Zero-based period index.
time	Pointer to receive the simulation time as a SWMM DateTime double.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_pollut_count()

SWMM_ENGINE_API int swmm_output_get_pollut_count ( SWMM_Output handle )

Get the number of pollutants in the output file.

Parameters

handle Output reader handle.

Returns: Pollutant count, or -1 on error.

◆ swmm_output_get_pollut_id()

SWMM_ENGINE_API const char * swmm_output_get_pollut_id	(	SWMM_Output	handle,
		int	index )

Get the string ID of a species (pollutant) column by index.

The .out header carries one name per species column. Reading it is the ONLY way to identify a column's meaning: the per-column unit field is a three-value concentration enum, so the water-age column (__WATER_AGE__, reported in HOURS) necessarily reuses a concentration code. Consumers plotting or converting a species column must key on this name, not on the unit code.

Parameters

handle	Output reader handle.
index	Zero-based species index (0 .. pollut_count-1).

Returns: Null-terminated string owned by the reader, or NULL on error.

◆ swmm_output_get_report_step()

SWMM_ENGINE_API int swmm_output_get_report_step ( SWMM_Output handle )

Get the report step in seconds.

Parameters

handle Output reader handle.

Returns: Report step (seconds), or -1 on error.

◆ swmm_output_get_start_date()

SWMM_ENGINE_API int swmm_output_get_start_date	(	SWMM_Output	handle,
		double *	start_date )

Get the simulation start date as a SWMM DateTime double.

SWMM's native DateTime representation is a double where the integer part is days since 1899-12-30 (OLE Automation epoch) and the fractional part is the time-of-day fraction (0.5 = noon). Convert to a calendar date/time via the datetime functions in openswmm_datetime.h.

Parameters

handle	Output reader handle.
start_date	Pointer to receive the start date value (SWMM DateTime).

Returns: 0 on success, -1 on error.

◆ swmm_output_get_subcatch_attribute()

SWMM_ENGINE_API int swmm_output_get_subcatch_attribute	(	SWMM_Output	handle,
		int	subcatch_idx,
		int	period,
		float *	values,
		int *	count )

Get all result variables for a single subcatchment at one period.

Parameters

handle	Output reader handle.
subcatch_idx	Zero-based subcatchment index.
period	Zero-based period index.
values	Caller-allocated array of n_subcatch_vars floats.
count	Pointer to receive the number of variables written.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_subcatch_count()

SWMM_ENGINE_API int swmm_output_get_subcatch_count ( SWMM_Output handle )

Get the number of subcatchments in the output file.

Parameters

handle Output reader handle.

Returns: Subcatchment count, or -1 on error.

◆ swmm_output_get_subcatch_id()

SWMM_ENGINE_API const char * swmm_output_get_subcatch_id	(	SWMM_Output	handle,
		int	index )

Get the string ID of a subcatchment by index.

Parameters

handle	Output reader handle.
index	Zero-based subcatchment index.

Returns: Null-terminated string owned by the reader, or NULL on error.

◆ swmm_output_get_subcatch_result()

SWMM_ENGINE_API int swmm_output_get_subcatch_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	values )

Get one subcatchment variable for all subcatchments at a given period.

Parameters

handle	Output reader handle.
period	Zero-based period index.
var	Subcatchment variable (see SWMM_OutSubcatchVar).
values	Caller-allocated array of at least subcatch_count floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_subcatch_series()

SWMM_ENGINE_API int swmm_output_get_subcatch_series	(	SWMM_Output	handle,
		int	subcatch_idx,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Get a subcatchment variable time series across a range of periods.

Parameters

handle	Output reader handle.
subcatch_idx	Zero-based subcatchment index.
var	Subcatchment variable.
start_period	First period (inclusive, zero-based).
end_period	Last period (inclusive, zero-based).
values	Caller-allocated array of (end_period - start_period + 1) floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_system_result()

SWMM_ENGINE_API int swmm_output_get_system_result	(	SWMM_Output	handle,
		int	period,
		int	var,
		float *	value )

Get system-wide results at a given period.

Parameters

handle	Output reader handle.
period	Zero-based period index.
var	System variable (see SWMM_OutSystemVar).
value	Pointer to receive the single float value.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_system_series()

SWMM_ENGINE_API int swmm_output_get_system_series	(	SWMM_Output	handle,
		int	var,
		int	start_period,
		int	end_period,
		float *	values )

Get a system variable time series across a range of periods.

Parameters

handle	Output reader handle.
var	System variable.
start_period	First period (inclusive, zero-based).
end_period	Last period (inclusive, zero-based).
values	Caller-allocated array of (end_period - start_period + 1) floats.

Returns: 0 on success, -1 on error.

◆ swmm_output_get_version()

SWMM_ENGINE_API int swmm_output_get_version ( SWMM_Output handle )

Get the SWMM version stored in the output file.

Parameters

handle Output reader handle.

Returns: Version number (e.g. 52001), or -1 on error.

◆ swmm_output_is_live()

SWMM_ENGINE_API int swmm_output_is_live ( SWMM_Output handle )

1 while a handle from swmm_output_open_live() has not yet seen the closing records, 0 otherwise, -1 on NULL.

◆ swmm_output_open()

SWMM_ENGINE_API SWMM_Output swmm_output_open ( const char * path )

Open a binary output file for reading.

Parameters

path	Path to a .out file produced by DefaultOutputPlugin.

Returns: Opaque handle, or NULL on failure (invalid file, I/O error).

◆ swmm_output_open_live()

SWMM_ENGINE_API SWMM_Output swmm_output_open_live ( const char * path )

Open a binary output file that is still being written.

Unlike swmm_output_open(), this does not need the closing records: offsets come from a forward parse of the header and the period count from the file size (whole records only). Use it to tail a run in progress — both the 6.x engine and the legacy 5.x engines flush the file after every report period — or to salvage the completed periods of a run that died before finishing. Poll swmm_output_refresh() for growth. Never modifies the file.

Parameters

path	Path to a .out file whose header is complete.

Returns: Opaque handle, or NULL if the header cannot be parsed yet.

◆ swmm_output_refresh()

SWMM_ENGINE_API int swmm_output_refresh	(	SWMM_Output	handle,
		int *	periods )

Re-count the periods of a file opened with swmm_output_open_live().

Once the writer's closing records appear, they are adopted (period count + error code) and the handle stops being live; it then behaves exactly like one from swmm_output_open(). On a non-live handle this is a no-op that reports the current count.

Parameters

handle	Output reader handle.
periods	Optional out: current period count.

Returns: 0 on success, -1 on a NULL handle.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ CHECK_READER

Function Documentation

◆ swmm_output_close()

◆ swmm_output_get_error_code()

◆ swmm_output_get_flow_units()

◆ swmm_output_get_link_attribute()

◆ swmm_output_get_link_count()

◆ swmm_output_get_link_id()

◆ swmm_output_get_link_result()

◆ swmm_output_get_link_series()

◆ swmm_output_get_node_attribute()

◆ swmm_output_get_node_count()

◆ swmm_output_get_node_id()

◆ swmm_output_get_node_result()

◆ swmm_output_get_node_series()

◆ swmm_output_get_node_stat_max_depth()

◆ swmm_output_get_node_stat_max_overflow()

◆ swmm_output_get_node_stat_time_flooded()

◆ swmm_output_get_node_stat_vol_flooded()

◆ swmm_output_get_period_count()

◆ swmm_output_get_period_time()

◆ swmm_output_get_pollut_count()

◆ swmm_output_get_pollut_id()

◆ swmm_output_get_report_step()

◆ swmm_output_get_start_date()

◆ swmm_output_get_subcatch_attribute()

◆ swmm_output_get_subcatch_count()

◆ swmm_output_get_subcatch_id()

◆ swmm_output_get_subcatch_result()

◆ swmm_output_get_subcatch_series()

◆ swmm_output_get_system_result()

◆ swmm_output_get_system_series()

◆ swmm_output_get_version()

◆ swmm_output_is_live()

◆ swmm_output_open()

◆ swmm_output_open_live()

◆ swmm_output_refresh()