SimulationSnapshot.hpp

Go to the documentation of this file.

 
#ifndef OPENSWMM_SIMULATION_SNAPSHOT_HPP
#define OPENSWMM_SIMULATION_SNAPSHOT_HPP
 
#include <vector>
#include <string>
#include <cstdint>
 
namespace openswmm {
 
// NOTE ON UNITS: the 1D node / link / subcatchment / gage / system fields below
// are delivered in PROJECT DISPLAY units (e.g. m, m³, CMS for an SI project;
// ft, ft³, CFS for US). The engine applies a single conversion boundary
// (convertSnapshotToDisplay) when building the snapshot, so output plugins
// write values directly without re-applying Ucf/Qcf. Dimensionless fields
// (capacity, soil moisture, pollutant concentrations) are unconverted. The 2D
// surface_* arrays on SimulationSnapshot are the exception: they are SI-native
// solver outputs and are NOT touched by the boundary.

struct NodeSnapshot {
    std::vector<double> depth;          
    std::vector<double> head;           
    std::vector<double> volume;         
    std::vector<double> lateral_inflow; 
    std::vector<double> total_inflow;   
    std::vector<double> overflow;       
};

struct LinkSnapshot {
    std::vector<double> flow;       
    std::vector<double> depth;      
    std::vector<double> velocity;   
    std::vector<double> volume;     
    std::vector<double> capacity;   
};

struct SubcatchSnapshot {
    std::vector<double> rainfall;   
    std::vector<double> snow_depth; 
    std::vector<double> evap;       
    std::vector<double> infil;      
    std::vector<double> runoff;     
    std::vector<double> gw_flow;    
    std::vector<double> gw_elev;    
    std::vector<double> soil_moist; 
};

struct GageSnapshot {
    std::vector<double> rainfall;   
};

struct SimulationSnapshot {
    // -----------------------------------------------------------------------
    // Timing
    // -----------------------------------------------------------------------

    double sim_time = 0.0;

    std::int64_t wall_time_unix = 0;

    int output_step_index = 0;
 
    // -----------------------------------------------------------------------
    // Object counts
    // -----------------------------------------------------------------------
 
    int node_count     = 0; 
    int link_count     = 0; 
    int subcatch_count = 0; 
    int gage_count     = 0; 
    int pollut_count   = 0; 
 
    // -----------------------------------------------------------------------
    // State arrays (parallel to the engine's SoA arrays)
    // -----------------------------------------------------------------------
 
    NodeSnapshot     nodes;       
    LinkSnapshot     links;       
    SubcatchSnapshot subcatch;    
    GageSnapshot     gages;       
 
    // -----------------------------------------------------------------------
    // System-level results (for binary output file)
    // -----------------------------------------------------------------------
 
    double sys_temperature    = 0.0;  
    double sys_rainfall       = 0.0;  
    double sys_snow_depth     = 0.0;  
    double sys_evap           = 0.0;  
    double sys_infil          = 0.0;  
    double sys_runoff         = 0.0;  
    double sys_dw_inflow      = 0.0;  
    double sys_gw_inflow      = 0.0;  
    double sys_ii_inflow      = 0.0;  
    double sys_ext_inflow     = 0.0;  
    double sys_flooding       = 0.0;  
    double sys_outflow        = 0.0;  
    double sys_storage        = 0.0;  
    double sys_pet            = 0.0;  
 
    // -----------------------------------------------------------------------
    // Pollutant concentrations (optional; populated only if quality routing active)
    // -----------------------------------------------------------------------

    std::vector<double> node_quality;

    std::vector<double> link_quality;

    std::vector<double> subcatch_quality;
 
    // -----------------------------------------------------------------------
    // String tables (for plugins that need to label their output)
    // -----------------------------------------------------------------------

    const std::vector<std::string>* node_ids     = nullptr;

    const std::vector<std::string>* link_ids     = nullptr;

    const std::vector<std::string>* subcatch_ids = nullptr;

    const std::vector<std::string>* gage_ids     = nullptr;

    const std::vector<std::string>* pollut_names = nullptr;
 
    // -----------------------------------------------------------------------
    // Unit information
    // -----------------------------------------------------------------------

    const char* flow_units = nullptr;

    const char* length_units = nullptr;

    int flow_units_code = 0;
 
    // -----------------------------------------------------------------------
    // 2D surface routing state (optional; populated only when the engine was
    // built with OPENSWMM_BUILD_2D and the input file contains a 2D mesh)
    //
    // Layout: per-triangle vectors are sized `surface_tri_count`; per-vertex
    // vectors are sized `surface_vert_count`. `surface_edge_flux` is flat
    // [tri * 3 + edge] of size `surface_tri_count * 3`.
    //
    // Fields are deep-copied from `SurfaceRouter2D::state()` on the main
    // simulation thread; consumers (Default2DOutputPlugin and any third-party
    // 2D output plugins) read them through the IO-thread snapshot reference
    // without further synchronization.
    //
    // Vectors are empty when 2D is inactive (either OPENSWMM_BUILD_2D=OFF or
    // the input file contained no [2D_VERTICES] section). Plugins must check
    // `surface_tri_count == 0` to skip 2D-specific work in that case.
    // -----------------------------------------------------------------------
 
    int surface_tri_count  = 0;             
    int surface_vert_count = 0;             
 
    std::vector<double> surface_depth;          
    std::vector<double> surface_head;           
    std::vector<double> surface_grad_hx;        
    std::vector<double> surface_grad_hy;        
    std::vector<double> surface_grad_hx_lim;    
    std::vector<double> surface_grad_hy_lim;    
    std::vector<double> surface_rainfall;       
    std::vector<double> surface_coupling_flux;  
    std::vector<double> surface_net_source;     
    std::vector<double> surface_edge_flux;      
    std::vector<double> surface_vert_head;      
    std::vector<double> surface_face_vx;        
    std::vector<double> surface_face_vy;        
    std::vector<double> surface_continuity_err; 
 
    // Cumulative rendering envelopes (SI-native, monotone over the run), per face.
    // A snapshot of these at any time is the envelope up to that time; the 2D
    // output plugin overwrites the fixed [nFace] envelope datasets in place.
    std::vector<double> surface_stat_max_depth;    
    std::vector<double> surface_stat_max_velocity; 
    std::vector<double> surface_stat_max_cont_err; 
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_SIMULATION_SNAPSHOT_HPP */