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 HotStartNodeRecord {
    std::string id;
    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 {
    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<double> gw_ledger;       
 
    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 = {});
 
    // -----------------------------------------------------------------------
    // 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 = {});

    static int save_legacy_routing(const std::string& path,
                                   const SimulationContext& ctx);
 
    // -----------------------------------------------------------------------
    // 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 */