HotStartManager.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_ENGINE_HOT_START_MANAGER_HPP
#define OPENSWMM_ENGINE_HOT_START_MANAGER_HPP
 
#include <cstdint>
#include <functional>
#include <string>
#include <vector>
 
namespace openswmm {
 
struct SimulationContext;
namespace runoff {
class RunoffSolver;
}
namespace groundwater {
class GWSolver;
}
 
// ============================================================================
// Per-object state records
// ============================================================================

struct HotStartLidCellRecord {
    int layer = 0;
    double bottom = 0.0, top = 0.0, porosity = 0.0, volume = 0.0, theta = 0.0;
};
struct HotStartNodeRecord {
    std::string id;
    std::vector<double> lid_richards;     
    std::vector<double> lid_infiltration; 
    std::vector<double> lid_quality_mass; 
    std::vector<HotStartLidCellRecord> lid_cells; 
    double lid_treated_volume = 0.0;              
    double depth = 0.0;
    double head = 0.0;
    double volume = 0.0;
    double age = -1.0;
};

struct HotStartLinkRecord {
    std::string id;
    double flow = 0.0;
    double depth = 0.0;
    double volume = 0.0;
    double age = -1.0;
};

struct HotStartSubcatchRecord {
    std::string id;
    double runoff = 0.0;
    double gwater = 0.0;
 
    // Gap #54: infiltration model state (V2 only; -1 = not present / V1 file)
    int infil_model = -1;
    double infil[6] = {0, 0, 0, 0, 0, 0}; 
 
    // Gap #54: groundwater zone state (V2 only; gw_theta < 0 = not present)
    double gw_theta = -1.0;      
    double gw_lower_depth = 0.0; 
};
 
// ============================================================================
// File header (in-memory mirror of the on-disk header)
// ============================================================================

struct HotStartHeader {
    uint32_t version = 1;
    int64_t timestamp = 0;   
    double sim_time = 0.0;   
    double start_date = 0.0; 
    double end_date = 0.0;   
    std::string crs;         
};
 
// ============================================================================
// HotStartFile — opaque handle (cast to void* in C API)
// ============================================================================

struct HotStartFile {
    std::string snow_state; 
    std::string
        engine_checkpoint; 
    std::string fv_dry_state; 
    std::string gw_transport_state; 
    std::string
        surface_state; 
    HotStartHeader header;
    std::vector<HotStartNodeRecord> nodes;
    std::vector<HotStartLinkRecord> links;
    std::vector<HotStartSubcatchRecord> subcatches;

    std::vector<std::string> species;
    std::vector<double> node_species;
    std::vector<double> link_species;

    uint32_t gw_n_cells = 0;
    uint32_t gw_m_layers = 0;
    std::vector<double> gw_hg;          
    std::vector<double> gw_hu;          
    std::vector<double> gw_theta_sigma; 
    std::vector<std::vector<double>>
        gw_interface; 
    std::vector<double> gw_ledger; 

    std::vector<std::string> gw_species;   
    std::vector<double> gw_sat_mass;       
    std::vector<double> gw_unsat_mass;     
    std::vector<double> gw_species_ledger; 
    static constexpr int kGwSpeciesLedgerTerms = 13;
 
    std::string path;   
    bool dirty = false; 
 
    std::vector<std::string> warnings; 
 
    // -----------------------------------------------------------------------
    // Modification helpers
    // -----------------------------------------------------------------------

    bool set_node_depth(const std::string& id, double v);
    bool set_node_head(const std::string& id, double v);
    bool set_link_flow(const std::string& id, double v);
    bool set_link_depth(const std::string& id, double v);
    bool set_subcatch_runoff(const std::string& id, double v);
};
 
// ============================================================================
// HotStartManager — static methods (no state; acts as a utility namespace)
// ============================================================================

struct LegacySpeciesTrailer {
    std::vector<std::string> species;
    int n_subcatch = 0;
    int n_landuses = -1;         
    std::vector<double> washoff; 
    std::vector<double> ponded;  
    std::vector<double> buildup; 
};
 
class HotStartManager {
public:
    HotStartManager() = delete;
 
    // -----------------------------------------------------------------------
    // Save
    // -----------------------------------------------------------------------

    static HotStartFile* save(const SimulationContext& ctx, const std::string& path);

    static HotStartFile* save(const SimulationContext& ctx, const runoff::RunoffSolver* runoff,
                              const groundwater::GWSolver* gw, const std::string& path);

    static HotStartFile* save_with_engine_checkpoint(const SimulationContext& ctx,
                                                     const runoff::RunoffSolver* runoff,
                                                     const groundwater::GWSolver* gw,
                                                     const std::string& path,
                                                     const std::string& engine_checkpoint);
 
    // -----------------------------------------------------------------------
    // Open
    // -----------------------------------------------------------------------

    static HotStartFile* open(const std::string& path);

    static bool is_native_file(const std::string& path) noexcept;
 
    // -----------------------------------------------------------------------
    // Apply
    // -----------------------------------------------------------------------

    static int apply(HotStartFile& hs, SimulationContext& ctx,
                     std::function<void(const std::string&)> warn_cb = {});

    static int apply(HotStartFile& hs, SimulationContext& ctx, runoff::RunoffSolver* runoff,
                     groundwater::GWSolver* gw,
                     std::function<void(const std::string&)> warn_cb = {});
 
    // -----------------------------------------------------------------------
    // Legacy EPA SWMM5 hotstart (.hsf) — read + apply routing state
    // -----------------------------------------------------------------------

    static int apply_legacy_routing(const std::string& path, SimulationContext& ctx,
                                    std::function<void(const std::string&)> warn_cb = {},
                                    std::vector<double>* runoff = nullptr,
                                    LegacySpeciesTrailer* species = nullptr);

    static bool apply_species_surface(const LegacySpeciesTrailer& tr, SimulationContext& ctx,
                                      const std::function<void(const std::string&)>& warn);

    static std::size_t legacy_runoff_size(const SimulationContext& ctx, int n_land);

    static int save_legacy_routing(const std::string& path, const SimulationContext& ctx,
                                   const std::vector<double>* runoff = nullptr);
 
    // -----------------------------------------------------------------------
    // Flush (write-back modifications)
    // -----------------------------------------------------------------------

    static bool flush(HotStartFile& hs);
 
    // -----------------------------------------------------------------------
    // Last I/O error (thread-local; for error reporting to C API layer)
    // -----------------------------------------------------------------------

    static const std::string& last_io_error() noexcept;
 
private:
    // -----------------------------------------------------------------------
    // Binary I/O helpers
    // -----------------------------------------------------------------------

    static bool write_file(const HotStartFile& hs, const std::string& path);
    static bool read_file(HotStartFile& hs, const std::string& path);
 
    // -----------------------------------------------------------------------
    // CRC32 (IEEE 802.3 polynomial, no external dependency)
    // -----------------------------------------------------------------------

    static uint32_t crc32(const uint8_t* data, std::size_t len) noexcept;
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_HOT_START_MANAGER_HPP */