openswmm_output.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
//
// Copyright 2026 Caleb Buahin
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

 
#ifndef OPENSWMM_OUTPUT_H
#define OPENSWMM_OUTPUT_H
 
#include "openswmm_engine_export.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/* =========================================================================
 * Opaque handle
 * ========================================================================= */

typedef void* SWMM_Output;
 
/* =========================================================================
 * Result variable enumerations
 * ========================================================================= */

typedef enum SWMM_OutSubcatchVar {
    SWMM_OUT_SUBCATCH_RAINFALL      = 0, 
    SWMM_OUT_SUBCATCH_SNOW_DEPTH    = 1, 
    SWMM_OUT_SUBCATCH_EVAP          = 2, 
    SWMM_OUT_SUBCATCH_INFIL         = 3, 
    SWMM_OUT_SUBCATCH_RUNOFF        = 4, 
    SWMM_OUT_SUBCATCH_GW_FLOW       = 5, 
    SWMM_OUT_SUBCATCH_GW_ELEV       = 6, 
    SWMM_OUT_SUBCATCH_SOIL_MOIST    = 7, 
    SWMM_OUT_SUBCATCH_POLLUT_BASE   = 8  
} SWMM_OutSubcatchVar;

typedef enum SWMM_OutNodeVar {
    SWMM_OUT_NODE_DEPTH          = 0, 
    SWMM_OUT_NODE_HEAD           = 1, 
    SWMM_OUT_NODE_VOLUME         = 2, 
    SWMM_OUT_NODE_LATERAL_INFLOW = 3, 
    SWMM_OUT_NODE_TOTAL_INFLOW   = 4, 
    SWMM_OUT_NODE_OVERFLOW       = 5, 
    SWMM_OUT_NODE_POLLUT_BASE    = 6  
} SWMM_OutNodeVar;

typedef enum SWMM_OutLinkVar {
    SWMM_OUT_LINK_FLOW           = 0, 
    SWMM_OUT_LINK_DEPTH          = 1, 
    SWMM_OUT_LINK_VELOCITY       = 2, 
    SWMM_OUT_LINK_VOLUME         = 3, 
    SWMM_OUT_LINK_CAPACITY       = 4, 
    SWMM_OUT_LINK_POLLUT_BASE    = 5  
} SWMM_OutLinkVar;

typedef enum SWMM_OutSystemVar {
    SWMM_OUT_SYS_TEMPERATURE    =  0, 
    SWMM_OUT_SYS_RAINFALL       =  1, 
    SWMM_OUT_SYS_SNOW_DEPTH     =  2, 
    SWMM_OUT_SYS_EVAP           =  3, 
    SWMM_OUT_SYS_INFIL          =  4, 
    SWMM_OUT_SYS_RUNOFF         =  5, 
    SWMM_OUT_SYS_DW_INFLOW      =  6, 
    SWMM_OUT_SYS_GW_INFLOW      =  7, 
    SWMM_OUT_SYS_LAT_INFLOW     =  8, 
    SWMM_OUT_SYS_FLOODING       =  9, 
    SWMM_OUT_SYS_OUTFLOW        = 10, 
    SWMM_OUT_SYS_STORAGE        = 11, 
    SWMM_OUT_SYS_EVAP_TOTAL     = 12, 
    SWMM_OUT_SYS_PET            = 13  
} SWMM_OutSystemVar;
 
/* =========================================================================
 * Lifecycle
 * ========================================================================= */

SWMM_ENGINE_API SWMM_Output swmm_output_open(const char* path);

SWMM_ENGINE_API SWMM_Output swmm_output_open_live(const char* path);

SWMM_ENGINE_API int swmm_output_refresh(SWMM_Output handle, int* periods);

SWMM_ENGINE_API int swmm_output_is_live(SWMM_Output handle);

SWMM_ENGINE_API void swmm_output_close(SWMM_Output handle);
 
/* =========================================================================
 * Metadata queries
 * ========================================================================= */

SWMM_ENGINE_API int swmm_output_get_version(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_flow_units(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_subcatch_count(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_node_count(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_link_count(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_pollut_count(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_period_count(SWMM_Output handle);

SWMM_ENGINE_API int swmm_output_get_start_date(SWMM_Output handle,
                                                 double* start_date);

SWMM_ENGINE_API int swmm_output_get_report_step(SWMM_Output handle);
 
/* =========================================================================
 * Object ID retrieval
 * ========================================================================= */

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

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

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

SWMM_ENGINE_API const char* swmm_output_get_pollut_id(SWMM_Output handle,
                                                        int index);
 
/* =========================================================================
 * Per-period result retrieval (all objects, one variable, one period)
 * ========================================================================= */

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

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

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

SWMM_ENGINE_API int swmm_output_get_system_result(SWMM_Output handle,
                                                    int period,
                                                    int var,
                                                    float* value);
 
/* =========================================================================
 * Time series retrieval (one object, one variable, period range)
 * ========================================================================= */

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);

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);

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);

SWMM_ENGINE_API int swmm_output_get_system_series(SWMM_Output handle,
                                                    int var,
                                                    int start_period,
                                                    int end_period,
                                                    float* values);
 
/* =========================================================================
 * Per-object result retrieval (all variables for one object at one period)
 * ========================================================================= */

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

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

SWMM_ENGINE_API int swmm_output_get_link_attribute(SWMM_Output handle,
                                                     int link_idx,
                                                     int period,
                                                     float* values,
                                                     int* count);
 
/* =========================================================================
 * Simulation time retrieval
 * ========================================================================= */

SWMM_ENGINE_API int swmm_output_get_period_time(SWMM_Output handle,
                                                  int period,
                                                  double* time);
 
/* =========================================================================
 * Per-node summary statistics — Slice QA-01
 *
 * The SWMM 5.x binary output format does not include a stats block; these
 * functions reconstruct the four flooding statistics at read time by
 * walking the per-period node results stored in the file. The semantics
 * mirror the engine-side `swmm_node_get_stat_*` accessors (which read
 * from SimulationContext.nodes.stat_*), except sourced from a SWMM_Output
 * handle so per-output comparisons work across multiple loaded .out
 * files. Implementations are O(n_periods) per call.
 *
 * Caveat: aggregation runs over REPORT-step samples, not the engine's
 * internal routing-step samples. For runs where the report step is much
 * coarser than the routing step (e.g. report every hour vs. route every
 * 5 s), `time_flooded` and `vol_flooded` will under-count brief
 * sub-report-step flooding events. The engine-side getters
 * (`swmm_node_get_stat_*`) retain the legacy routing-step precision —
 * use those when a fresh in-process run is the source.
 * ========================================================================= */

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

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

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

SWMM_ENGINE_API int swmm_output_get_node_stat_time_flooded(SWMM_Output handle,
                                                             int          node_idx,
                                                             double*      value);
 
/* =========================================================================
 * Error reporting
 * ========================================================================= */

SWMM_ENGINE_API int swmm_output_get_error_code(SWMM_Output handle);
 
#ifdef __cplusplus
}
#endif
 
#endif /* OPENSWMM_OUTPUT_H */