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 "SnowResults.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 {
    // Optional UEB process columns, in SWMM_OUT_SUBCATCH_SNOW_* order.
    // SI regardless of project display units; missing values remain NaN.
    static constexpr int snow_process_count = 10;
    std::vector<double> snow_process; // [subcatch * snow_process_count + field]
    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; 
    MeshSnowSnapshot surface_snow;        
    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;
    const std::vector<std::string>* surface_species_units = nullptr;
    std::vector<double> surface_buildup;
    int surface_buildup_count = 0;
    bool gw2d_active = false;
    std::vector<double> gw2d_table_elev; 
    std::vector<double> gw2d_hg;         
    std::vector<double>
        gw2d_hu; 
    std::vector<double> gw2d_recharge; 
    std::vector<double> gw2d_lateral;  
    std::vector<double>
        gw2d_node_exchange;                
    std::vector<double> gw2d_deep;         
    std::vector<double> gw2d_et;           
    std::vector<double> gw2d_dunne;        
    std::vector<double> gw2d_infil_in;     
    std::vector<double> gw2d_link_seepage; 
    std::vector<double> gw2d_sat_conc;
    std::vector<double> gw2d_unsat_conc;
    std::vector<double> gw2d_species_ledger;
    int gw2d_species_count = 0;
    const std::vector<std::string>* gw2d_species_names = nullptr;
    std::vector<double> gw2d_bed_elev;
    std::vector<int> gw2d_closure;
    std::vector<double> gw2d_theta_sigma;
    int gw2d_m_layers = 0;
    std::vector<double> gw2d_ledger;
    std::vector<double> gw2d_bed_exchange_cum;
    const std::vector<std::string>* gw2d_node_names = nullptr;
 
    // P9 thermal result contract. Values are copied from accepted runtime
    // owners on the simulation thread; energy terms are cumulative signed J.
    // Missing cells/layers are NaN so a report never fabricates a temperature.
    bool thermal2d_active = false;
    int thermal2d_layer_count = 0;
    int thermal2d_surface_budget_terms = 6;
    int thermal2d_ground_budget_terms = 12;
    std::vector<double> thermal2d_water_temperature; 
    std::vector<double> thermal2d_bed_temperature;   
    std::vector<double> thermal2d_bed_energy;        
    std::vector<double> thermal2d_bed_capacity;      
    int thermal2d_bed_species_count = 0;
    std::vector<std::string> thermal2d_bed_species_names;
    std::vector<std::string> thermal2d_bed_species_units;
    std::vector<double> thermal2d_bed_pore_volume;
    std::vector<double> thermal2d_bed_species_concentration;
    std::vector<double> thermal2d_bed_species_exchange;
    std::vector<double> thermal2d_bed_age_generation;
    std::vector<double> thermal2d_surface_budget;
    std::vector<double> thermal2d_evaporation_m3;     
    std::vector<double> thermal2d_ground_temperature; 
    std::vector<double> thermal2d_ground_energy;      
    std::vector<double> thermal2d_ground_capacity;    
    std::vector<double> thermal2d_ground_layer_center_m;
    std::vector<double> thermal2d_ground_layer_temperature;
    std::vector<double> thermal2d_ground_layer_energy;
    std::vector<double> thermal2d_ground_layer_capacity;
    std::vector<double> thermal2d_ground_budget;
    int thermal2d_lid_layer_count = 0;
    std::vector<int> thermal2d_lid_layer_node_index;
    std::vector<int> thermal2d_lid_layer_face_index;
    std::vector<int> thermal2d_lid_layer_physical_index;
    std::vector<int> thermal2d_lid_layer_control_index;
    std::vector<int> thermal2d_lid_layer_authored_index;
    std::vector<std::string> thermal2d_lid_layer_node_id;
    std::vector<double> thermal2d_lid_layer_top_m;
    std::vector<double> thermal2d_lid_layer_bottom_m;
    std::vector<double> thermal2d_lid_layer_area_m2;
    std::vector<double> thermal2d_lid_layer_temperature;
    std::vector<double> thermal2d_lid_layer_energy;
    std::vector<double> thermal2d_lid_layer_capacity;
    std::vector<double> thermal2d_lid_layer_ground_contact_j;
 
    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; 
    std::vector<double> gw2d_infil_capacity; 
    std::vector<double>
        gw2d_infil_remaining; 
    std::vector<double> gw2d_infil_refresh; 
    std::vector<double> gw2d_infil_pending; 
    std::vector<double>
        gw2d_reject; 
    std::vector<double> gw2d_reject_cum; 
    std::vector<double> gw2d_dunne_cum;  
    std::vector<double> gw2d_et_pending;
    std::vector<double> gw2d_et_potential_cum;
    std::vector<double> gw2d_et_surface_cum;
    std::vector<double> gw2d_et_soil_cum;
    std::vector<double> gw2d_et_unused_cum;
    std::vector<double> gw2d_et_surface;
    std::vector<double> gw2d_et_potential;
    std::vector<double> gw2d_et_stress;
    std::vector<double> gw2d_et_refresh;
 
    // Appended for plugin-ABI compatibility: initial finite local-bed stores.
    std::vector<double> thermal2d_bed_initial_energy;
    std::vector<double> thermal2d_bed_species_initial_amount;
    // Additive groundwater completion output, absent for compatibility BULK profiles.
    int gw2d_transport_layers = 0, gw2d_boundary_count = 0;
    std::vector<double> gw2d_layer_mass, gw2d_layer_concentration; // [species,layer,face]
    std::vector<double> gw2d_boundary_water; // [boundary,4]: requested in/out, accepted in/out
    std::vector<double>
        gw2d_boundary_species; // [species,boundary,4]: advective in/out, imposed in/out
    std::vector<int> gw2d_boundary_cell_edge;  // [boundary,2], zero-based
    std::vector<double> gw2d_transport_ledger; // [species,20], append-only public SPL terms
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_SIMULATION_SNAPSHOT_HPP */