SimulationContext.hpp

Go to the documentation of this file.

 
#ifndef OPENSWMM_ENGINE_SIMULATION_CONTEXT_HPP
#define OPENSWMM_ENGINE_SIMULATION_CONTEXT_HPP
 
#include "../data/GageData.hpp"
#include "../data/LinkData.hpp"
#include "../data/NameIndex.hpp"
#include "../data/NodeData.hpp"
#include "../data/PollutantData.hpp"
#include "../data/SubcatchData.hpp"
#include "../data/TableData.hpp"
#include "SimulationOptions.hpp"
#include "SpatialFrame.hpp"
#include "UserFlags.hpp"
#include "../data/QualityData.hpp"
#include "../data/InflowData.hpp"
#include "../data/InfraData.hpp"
#include "../data/HydrologyData.hpp"
#include "../data/ForcingData.hpp"
 
#include <algorithm>
#include <cstdint>
#include <string>
#include <vector>
 
namespace openswmm {
 
// ============================================================================
// Plugin specification (from [PLUGINS] section)
// ============================================================================
 
struct PluginSpec {
    std::string              path;       
    std::vector<std::string> init_args;  
};
 
// ============================================================================
// Engine state enumeration
// ============================================================================
 
enum class EngineState : int32_t {
    CREATED      = 0,  
    OPENED       = 1,  
    INITIALIZED  = 2,  
    RUNNING      = 3,  
    PAUSED       = 4,  
    ENDED        = 5,  
    REPORTED     = 6,  
    CLOSED       = 7,  
    ERROR_STATE  = 8,  
    BUILDING     = 9   
};
 
// ============================================================================
// SimulationContext
// ============================================================================
 
struct SimulationContext {
 
    // =========================================================================
    // Engine state
    // =========================================================================
 
    EngineState state = EngineState::CREATED;
 
    // =========================================================================
    // Options & configuration
    // =========================================================================
 
    SimulationOptions options;
 
    // =========================================================================
    // Simulation clock
    // =========================================================================
 
    double current_time = 0.0;
 
    double current_date = 0.0;
 
    double dt_output_remaining = 0.0;
 
    double dt_controls_remaining = 0.0;
 
    // =========================================================================
    // Object data stores (Structure-of-Arrays)
    // =========================================================================
 
    NodeData nodes;
 
    LinkData links;
 
    SubcatchData subcatches;
 
    GageData gages;
 
    PollutantData pollutants;
 
    TableData tables;
 
    // =========================================================================
    // Name-to-index lookup (O(1))
    // =========================================================================
 
    NameIndex node_names;
 
    NameIndex link_names;
 
    NameIndex subcatch_names;
 
    NameIndex gage_names;
 
    NameIndex pollutant_names;
 
    NameIndex table_names;
 
    // =========================================================================
    // Quality data (landuse, buildup, washoff, treatment)
    // =========================================================================
 
    NameIndex        landuse_names;
    LanduseData      landuses;
    BuildupData      buildup;
    WashoffData      washoff;
    TreatmentData    treatment;
 
    // =========================================================================
    // Inflow data (external, DWF, RDII, patterns)
    // =========================================================================
 
    ExtInflowData    ext_inflows;
    DwfData          dwf_inflows;
    RDIIAssignData   rdii_assigns;
    PatternData      patterns;
 
    // =========================================================================
    // Infrastructure data (transects, streets, inlets, controls)
    // =========================================================================
 
    TransectStore    transects;
    StreetStore      streets;
    InletStore       inlets;
    InletUsageStore  inlet_usages;
    ControlRuleStore control_rules;
 
    // =========================================================================
    // Hydrology data (snowpacks, aquifers, LID)
    // =========================================================================
 
    SnowpackStore    snowpacks;
    NameIndex        snowpack_names;
    AquiferStore     aquifers;
    NameIndex        aquifer_names;
    LidControlStore  lid_controls;
    NameIndex        lid_names;
    LidUsageStore    lid_usage;
 
    // =========================================================================
    // Spatial data
    // =========================================================================
 
    SpatialFrame spatial;
 
    // =========================================================================
    // User-defined flags
    // =========================================================================
 
    UserFlags user_flags;
 
    // =========================================================================
    // Runtime forcing data
    // =========================================================================
 
    ForcingData forcing;
 
    // =========================================================================
    // Plugin specifications (from [PLUGINS] section)
    // =========================================================================
 
    std::vector<PluginSpec> plugin_specs;
 
    // =========================================================================
    // Error / warning tracking
    // =========================================================================
 
    int error_code = 0;
 
    int warning_code = 0;
 
    std::string error_message;
 
    // =========================================================================
    // Mass balance accumulators (SoA — vectorisable batch updates)
    // =========================================================================
 
    struct MassBalance {
        // Runoff totals
        double runoff_rainfall   = 0.0;  
        double runoff_evap       = 0.0;  
        double runoff_infil      = 0.0;  
        double runoff_runoff     = 0.0;  
        double runoff_snowremov  = 0.0;  
        double runoff_init_store = 0.0;  
        double runoff_final_store= 0.0;  
 
        // Routing totals
        double routing_dry_weather   = 0.0;
        double routing_wet_weather   = 0.0;
        double routing_gw_inflow     = 0.0;
        double routing_rdii          = 0.0;
        double routing_external      = 0.0;
        double routing_flooding      = 0.0;
        double routing_outflow       = 0.0;
        double routing_evap_loss     = 0.0;
        double routing_seep_loss     = 0.0;
        double routing_init_storage  = 0.0;
        double routing_final_storage = 0.0;
 
        // User-forced volumes (diagnostic — subset of routing_external)
        double routing_forcing_inflow = 0.0; 
 
        // Per-step accumulators (reset each step for reporting)
        double step_flooding  = 0.0;
        double step_outflow   = 0.0;
        double step_dw_inflow = 0.0;
        double step_gw_inflow = 0.0;
 
        // Quality mass balance (per-pollutant, in mass units)
        std::vector<double> qual_init_buildup;   
        std::vector<double> qual_final_buildup;  
        std::vector<double> qual_surface_buildup; 
        std::vector<double> qual_wet_deposition; 
        std::vector<double> qual_sweeping;       
        std::vector<double> qual_bmp_removal;    
        std::vector<double> qual_infil_loss;     
        std::vector<double> qual_runoff_load;    
        std::vector<double> qual_routing_wet;    
        std::vector<double> qual_routing_outflow;
        std::vector<double> qual_routing_flood;  
        std::vector<double> qual_routing_init;   
        std::vector<double> qual_routing_final;  
        std::vector<double> qual_routing_reacted;
 
        void resize_quality(int n_pollutants) {
            auto np = static_cast<std::size_t>(n_pollutants);
            qual_init_buildup.assign(np, 0.0);
            qual_final_buildup.assign(np, 0.0);
            qual_surface_buildup.assign(np, 0.0);
            qual_wet_deposition.assign(np, 0.0);
            qual_sweeping.assign(np, 0.0);
            qual_bmp_removal.assign(np, 0.0);
            qual_infil_loss.assign(np, 0.0);
            qual_runoff_load.assign(np, 0.0);
            qual_routing_wet.assign(np, 0.0);
            qual_routing_outflow.assign(np, 0.0);
            qual_routing_flood.assign(np, 0.0);
            qual_routing_init.assign(np, 0.0);
            qual_routing_final.assign(np, 0.0);
            qual_routing_reacted.assign(np, 0.0);
        }
 
        void reset() {
            // Save quality vectors, reset scalars, restore vectors
            auto qi = std::move(qual_init_buildup);
            auto qf = std::move(qual_final_buildup);
            auto qsb = std::move(qual_surface_buildup);
            auto qwd = std::move(qual_wet_deposition);
            auto qsw = std::move(qual_sweeping);
            auto qbmp = std::move(qual_bmp_removal);
            auto qil = std::move(qual_infil_loss);
            auto qrl = std::move(qual_runoff_load);
            auto qrw = std::move(qual_routing_wet);
            auto qro = std::move(qual_routing_outflow);
            auto qrf = std::move(qual_routing_flood);
            auto qri = std::move(qual_routing_init);
            auto qrfi = std::move(qual_routing_final);
            auto qrr = std::move(qual_routing_reacted);
            *this = MassBalance{};
            qual_init_buildup = std::move(qi);
            qual_final_buildup = std::move(qf);
            qual_surface_buildup = std::move(qsb);
            qual_wet_deposition = std::move(qwd);
            qual_sweeping = std::move(qsw);
            qual_bmp_removal = std::move(qbmp);
            qual_infil_loss = std::move(qil);
            qual_runoff_load = std::move(qrl);
            qual_routing_wet = std::move(qrw);
            qual_routing_outflow = std::move(qro);
            qual_routing_flood = std::move(qrf);
            qual_routing_init = std::move(qri);
            qual_routing_final = std::move(qrfi);
            qual_routing_reacted = std::move(qrr);
            // Zero out the quality vectors (except init_buildup which is
            // computed once during initQuality and must survive reset)
            for (auto* v : {&qual_final_buildup,
                            &qual_surface_buildup, &qual_wet_deposition,
                            &qual_sweeping, &qual_bmp_removal,
                            &qual_infil_loss, &qual_runoff_load,
                            &qual_routing_wet, &qual_routing_outflow,
                            &qual_routing_flood, &qual_routing_init,
                            &qual_routing_final, &qual_routing_reacted}) {
                std::fill(v->begin(), v->end(), 0.0);
            }
        }
 
        double runoff_error() const {
            double total_in = runoff_rainfall + runoff_init_store;
            double total_out = runoff_evap + runoff_infil + runoff_runoff + runoff_final_store;
            return (total_in > 0.0) ? (total_in - total_out) / total_in : 0.0;
        }
 
        double routing_error() const {
            double total_in = routing_dry_weather + routing_wet_weather +
                              routing_gw_inflow + routing_rdii + routing_external +
                              routing_init_storage;
            double total_out = routing_flooding + routing_outflow +
                               routing_evap_loss + routing_seep_loss +
                               routing_final_storage;
            return (total_in > 0.0) ? (total_in - total_out) / total_in : 0.0;
        }
    } mass_balance;
 
    // =========================================================================
    // Routing time-step statistics
    // =========================================================================
 
    struct RoutingStepStats {
        double min_step  = 1.0e30; 
        double max_step  = 0.0;    
        double sum_step  = 0.0;    
        long   n_steps   = 0;      
        double steady_pct = 0.0;   
        double avg_iterations = 0.0; 
 
        void update(double dt) {
            if (dt < min_step) min_step = dt;
            if (dt > max_step) max_step = dt;
            sum_step += dt;
            ++n_steps;
        }
        double avg_step() const {
            return (n_steps > 0) ? sum_step / static_cast<double>(n_steps) : 0.0;
        }
    } routing_stats;
 
    // =========================================================================
    // Input file path (for model write / hot start)
    // =========================================================================
 
    std::string inp_file_path;
 
    // =========================================================================
    // Context-level operations
    // =========================================================================
 
    void reset() {
        state = EngineState::CREATED;
        current_time = 0.0;
        current_date = 0.0;
        dt_output_remaining = 0.0;
        dt_controls_remaining = 0.0;
        error_code = 0;
        warning_code = 0;
        error_message.clear();
 
        // Clear SoA stores
        nodes      = NodeData{};
        links      = LinkData{};
        subcatches = SubcatchData{};
        gages      = GageData{};
        pollutants = PollutantData{};
        tables     = TableData{};
 
        // Clear name indices
        node_names.clear();
        link_names.clear();
        subcatch_names.clear();
        gage_names.clear();
        pollutant_names.clear();
        table_names.clear();
 
        // Clear spatial, flags, and forcing
        spatial    = SpatialFrame{};
        user_flags.clear();
        forcing    = ForcingData{};
    }
 
    void save_state() noexcept {
        nodes.save_state();
        links.save_state();
        subcatches.save_state();
        if (options.quality_routing) {
            pollutants.save_quality_state();
        }
    }
 
    void reset_state() noexcept {
        nodes.reset_state();
        links.reset_state();
        subcatches.reset_state();
        gages.reset_state();
        pollutants.reset_quality_state();
        tables.reset_cursors();
        current_time = 0.0;
        current_date = options.start_date;
        dt_output_remaining = options.report_step;
        dt_controls_remaining = 0.0;
    }
 
    void allocate_objects() {
        nodes.resize(node_names.size());
        links.resize(link_names.size());
        subcatches.resize(subcatch_names.size());
        gages.resize(gage_names.size());
        pollutants.resize_pollutants(pollutant_names.size());
        pollutants.resize_quality(
            node_names.size(),
            link_names.size(),
            subcatch_names.size()
        );
 
        // Resize spatial coordinate arrays
        spatial.node_x.assign(static_cast<std::size_t>(node_names.size()), 0.0);
        spatial.node_y.assign(static_cast<std::size_t>(node_names.size()), 0.0);
        spatial.link_x.assign(static_cast<std::size_t>(link_names.size()), 0.0);
        spatial.link_y.assign(static_cast<std::size_t>(link_names.size()), 0.0);
        spatial.subcatch_x.assign(static_cast<std::size_t>(subcatch_names.size()), 0.0);
        spatial.subcatch_y.assign(static_cast<std::size_t>(subcatch_names.size()), 0.0);
 
        // Resize link vertex and subcatchment polygon arrays
        spatial.link_vertices_x.resize(static_cast<std::size_t>(link_names.size()));
        spatial.link_vertices_y.resize(static_cast<std::size_t>(link_names.size()));
        spatial.subcatch_polygon_x.resize(static_cast<std::size_t>(subcatch_names.size()));
        spatial.subcatch_polygon_y.resize(static_cast<std::size_t>(subcatch_names.size()));
 
        // Resize gage coordinates
        spatial.gage_x.assign(static_cast<std::size_t>(gage_names.size()), 0.0);
        spatial.gage_y.assign(static_cast<std::size_t>(gage_names.size()), 0.0);
    }
 
    // =========================================================================
    // Convenience accessors
    // =========================================================================
 
    int n_nodes()      const noexcept { return node_names.size(); }
 
    int n_links()      const noexcept { return link_names.size(); }
 
    int n_subcatches() const noexcept { return subcatch_names.size(); }
 
    int n_gages()      const noexcept { return gage_names.size(); }
 
    int n_pollutants() const noexcept { return pollutant_names.size(); }
    int n_landuses()   const noexcept { return landuse_names.size(); }
 
    int n_tables()     const noexcept { return table_names.size(); }
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_SIMULATION_CONTEXT_HPP */