HotStartManager.hpp

Go to the documentation of this file.

 
#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 HotStartNodeRecord {
    std::string id;
    double      depth  = 0.0;
    double      head   = 0.0;
    double      volume = 0.0;
};
 
struct HotStartLinkRecord {
    std::string id;
    double      flow   = 0.0;
    double      depth  = 0.0;
    double      volume = 0.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 {
    HotStartHeader                    header;
    std::vector<HotStartNodeRecord>   nodes;
    std::vector<HotStartLinkRecord>   links;
    std::vector<HotStartSubcatchRecord> subcatches;
 
    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)
// ============================================================================
 
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);
 
    // -----------------------------------------------------------------------
    // Open
    // -----------------------------------------------------------------------
 
    static HotStartFile* open(const std::string& path);
 
    // -----------------------------------------------------------------------
    // 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 = {});
 
    // -----------------------------------------------------------------------
    // 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 */