SimulationSnapshot.hpp

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

    bool has_subcatchments = true;
 
    // -----------------------------------------------------------------------
    // 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-cell vectors are sized `surface_tri_count` (a "tri" is any
    // cell — triangle or quadrilateral, triangles first); per-vertex vectors
    // are sized `surface_vert_count`. `surface_edge_flux` is flat
    // [cell * surface_edge_stride + edge] of size
    // `surface_tri_count * surface_edge_stride`, where the stride is 3 for an
    // all-triangle mesh (byte-compatible with pre-quad consumers) and 4 once
    // any quad exists; padding slots of a triangle row are 0.
    //
    // 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;             
    int surface_quad_count = 0;             
    int surface_edge_stride = 3;            
    std::vector<uint8_t> surface_cell_nv;
 
    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_infil_rate;     
    std::vector<double> surface_infil_cum;      
    std::vector<double> surface_rain_cum;       
    std::vector<double> surface_species_conc;
    int surface_species_count = 0;
    const std::vector<std::string>* surface_species_names = nullptr;
    std::vector<double> surface_edge_flux;      
    std::vector<double> surface_vert_head;      
    std::vector<double> surface_vert_depth;     
    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 */