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;

SWMM_ENGINE_API int swmm_output_get_pollut_units(SWMM_Output handle, int index);
 
/* =========================================================================
 * 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, 
    /* Optional UEB fields. These are codes, not positional array indices.
       All use SI, averaged over the non-LID subcatchment area. Their accepted
       clock is recorded separately; it can differ from the hydraulic report
       clock. A file without UEB has no extension. Unavailable rows are NaN. */
    SWMM_OUT_SUBCATCH_SNOW_SWE = 65536,          
    SWMM_OUT_SUBCATCH_SNOW_ENERGY = 65537,       
    SWMM_OUT_SUBCATCH_SNOW_SURFACE_TEMP = 65538, 
    SWMM_OUT_SUBCATCH_SNOW_BULK_TEMP = 65539,    
    SWMM_OUT_SUBCATCH_SNOW_ALBEDO = 65540,       
    SWMM_OUT_SUBCATCH_SNOW_COVER = 65541,        
    SWMM_OUT_SUBCATCH_SNOW_MELT = 65542,         
    SWMM_OUT_SUBCATCH_SNOW_INPUT = 65543,        
    SWMM_OUT_SUBCATCH_SNOW_SUBLIMATION = 65544,  
    SWMM_OUT_SUBCATCH_SNOW_TIME = 65545          
} SWMM_OutSubcatchVar;

SWMM_ENGINE_API int swmm_output_has_subcatch_variable(SWMM_Output handle, int code);
 
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_INFIL = 3,       
    SWMM_OUT_SYS_RUNOFF = 4,      
    SWMM_OUT_SYS_DW_INFLOW = 5,   
    SWMM_OUT_SYS_GW_INFLOW = 6,   
    SWMM_OUT_SYS_RDII_INFLOW = 7, 
    SWMM_OUT_SYS_EXT_INFLOW = 8,  
    SWMM_OUT_SYS_TOTAL_INFLOW =
        9,                      
    SWMM_OUT_SYS_FLOODING = 10, 
    SWMM_OUT_SYS_OUTFLOW = 11,  
    SWMM_OUT_SYS_STORAGE = 12,  
    SWMM_OUT_SYS_EVAP = 13,     
    SWMM_OUT_SYS_PET = 14,      
    SWMM_OUT_SYS_LAT_INFLOW = SWMM_OUT_SYS_TOTAL_INFLOW 
} 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` can miss brief events or assign
 * an entire report interval to a brief positive sample. 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 */