Default2DOutputPlugin.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.

 
#pragma once
 
#ifdef OPENSWMM_HAS_2D
 
#include "../../../../include/openswmm/plugin_sdk/IOutputPlugin.hpp"
 
#include "../../io/CheckpointOutputPublication.hpp"
#include "../../io/CheckpointFile.hpp"
#include <string>
#include <memory>
#include <mutex>
#include <unordered_map>
#include <vector>
#include <hdf5.h>
 
namespace openswmm {
class SWMMEngine;
}
namespace openswmm::twoD {
 
struct InertialEdges;
class MomentumPhysics2D;
struct MeshData;        // forward declaration
struct SolverOptions2D; // forward declaration
class SourceResultHistory;

class Default2DOutputPlugin final : public IOutputPlugin {
public:
    explicit Default2DOutputPlugin(std::string h5_path);
    ~Default2DOutputPlugin() override;
 
    // Non-copyable
    Default2DOutputPlugin(const Default2DOutputPlugin&) = delete;
    Default2DOutputPlugin& operator=(const Default2DOutputPlugin&) = delete;
 
    // -----------------------------------------------------------------------
    // IOutputPlugin interface
    // -----------------------------------------------------------------------

    PluginState state() const noexcept override { return state_; }

    int initialize(const std::vector<std::string>& init_args,
                   const IPluginComponentInfo* info) override;

    int validate(const SimulationContext& ctx) override;

    int prepare(const SimulationContext& ctx) override;

    int update(const SimulationSnapshot& snapshot) override;

    int finalize(const SimulationContext& ctx) override;

    const char* last_error_message() const noexcept override { return last_error_.c_str(); }

    void prepareMeshAndDatasets(const MeshData& mesh);

    void setMeshCoordinateScale(double metres_per_model_unit);

    std::string configureOutput(const SolverOptions2D& opts, double report_step_sec);

    unsigned reportVariables() const noexcept { return report_vars_; }

    void enqueueSourceHistory(std::shared_ptr<const SourceResultHistory> history);
 
private:
    friend class openswmm::SWMMEngine;
    // Internal single-file, water-only continuation. IO must be idle.
    bool checkpoint_fresh_ = false;
    bool checkpoint_write_failed_ = false;
    void checkpointWriteStatus(herr_t);
    std::string checkpoint_header_;
    struct PreparedCheckpoint;
    std::string checkpointBytes(const SimulationContext&, double next_report_ms,
                                const SimulationSnapshot&);
    std::shared_ptr<PreparedCheckpoint> prepareCheckpoint(const SimulationContext&,
                                                          double next_report_ms,
                                                          const SimulationSnapshot&,
                                                          const SourceResultHistory*, std::string);
    void installCheckpoint(PreparedCheckpoint&);
    io::CheckpointOutputPublication::Output checkpointPublication(const PreparedCheckpoint&) const;
    void adoptCheckpoint(PreparedCheckpoint&) noexcept;
    void validateCheckpoint(hid_t, const SimulationContext&, double, const SimulationSnapshot&,
                            hsize_t, double, bool) const;
    std::vector<hid_t*> checkpointDatasets();
    void closeDatasets() noexcept;
    std::string fileBytes() const;
    std::string captureFileCheckpoint(const SimulationContext&, double, const SimulationSnapshot&,
                                      const std::filesystem::path&,
                                      std::shared_ptr<io::OwnedCheckpointFile>&);
    std::shared_ptr<PreparedCheckpoint>
    prepareFileCheckpoint(const SimulationContext&, double, const SimulationSnapshot&, std::string);
    void resolveCheckpointDatasets(PreparedCheckpoint&, const SimulationSnapshot&);
    std::mutex source_mutex_;
    std::vector<std::shared_ptr<const SourceResultHistory>> source_pending_;
    std::shared_ptr<const SourceResultHistory> source_written_;
    int writePendingSourceHistory();
    // ---- results-file size controls (configureOutput) ----
    hid_t storage_type_ = H5T_NATIVE_DOUBLE;  
    int compression_ = 4;                     
    unsigned report_vars_ = 0x7FFu;           
    std::vector<std::string> species_filter_; 
    std::vector<int> species_rows_;           
    double report_2d_step_days_ = 0.0;        
    double next_due_days_ = -1.0;             
    bool want(unsigned bit) const noexcept { return (report_vars_ & bit) != 0; }
    void writeSpeciesRows(const double* all, hsize_t n_species_in);
 
    std::string h5_path_;
    PluginState state_ = PluginState::UNLOADED;
    std::string last_error_;
 
    std::unordered_map<std::string, std::string>
        native_species_units_;           // keyed by identity, not surface row
    std::string model_crs_;              
    double metres_per_model_unit_ = 1.0; 
 
    hid_t file_id_ = H5I_INVALID_HID; 
 
    // Dataset handles for time-varying fields (unlimited time dimension)
    hid_t ds_time_ = H5I_INVALID_HID;
    hid_t ds_face_depth_ = H5I_INVALID_HID;
    hid_t ds_face_head_ = H5I_INVALID_HID;
    hid_t ds_face_grad_hx_ = H5I_INVALID_HID;
    hid_t ds_face_grad_hy_ = H5I_INVALID_HID;
    hid_t ds_face_grad_hx_lim_ = H5I_INVALID_HID;
    hid_t ds_face_grad_hy_lim_ = H5I_INVALID_HID;
    hid_t ds_face_rainfall_ = H5I_INVALID_HID;
    hid_t ds_face_coupling_flux_ = H5I_INVALID_HID;
    hid_t ds_face_net_source_ = H5I_INVALID_HID;
    hid_t ds_face_infil_rate_ = H5I_INVALID_HID;
    hid_t ds_face_infil_cum_ = H5I_INVALID_HID;
    hid_t ds_face_rain_cum_ = H5I_INVALID_HID;
    std::array<hid_t, meshSnowFields.size()> ds_snow_ = [] {
        std::array<hid_t, meshSnowFields.size()> ids;
        ids.fill(H5I_INVALID_HID);
        return ids;
    }();
    void createSnowDatasets(const SimulationSnapshot&);

    hid_t ds_face_species_conc_ = H5I_INVALID_HID;
    hsize_t n_species_ = 0;
    hid_t ds_face_buildup_ = H5I_INVALID_HID;
    hsize_t n_buildup_ = 0;
    static constexpr int kGwFaceFields = 27;      // G-X3: + Mesh2_face_gw_link_seepage
    static constexpr hsize_t kGwLedgerTerms = 15; // G-X3: + link (LED 10), residual last
    hid_t ds_gw_face_[kGwFaceFields] = {
        H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
        H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
        H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
        H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
        H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID, H5I_INVALID_HID,
        H5I_INVALID_HID, H5I_INVALID_HID};
    hid_t ds_gw_ledger_ = H5I_INVALID_HID;
    static constexpr hsize_t kGwSpeciesLedgerTerms = 15;
    hid_t ds_gw_sat_conc_ = H5I_INVALID_HID;
    hid_t ds_gw_unsat_conc_ = H5I_INVALID_HID;
    hid_t ds_gw_species_ledger_ = H5I_INVALID_HID;
    hsize_t n_gw_species_ = 0;
    hid_t ds_gw_bed_exchange_ = H5I_INVALID_HID;
    hid_t ds_gw_theta_ = H5I_INVALID_HID;
    hsize_t n_gw_beds_ = 0;
    hsize_t n_gw_layers_ = 0;
    hid_t ds_gw_layer_mass_ = H5I_INVALID_HID, ds_gw_layer_conc_ = H5I_INVALID_HID;
    hid_t ds_gw_boundary_water_ = H5I_INVALID_HID, ds_gw_boundary_species_ = H5I_INVALID_HID;
    hid_t ds_gw_transport_ledger_ = H5I_INVALID_HID;
    hsize_t n_gw_transport_layers_ = 0, n_gw_boundaries_ = 0;
    bool gw_created_ = false;
    void createGroundwaterDatasets(const SimulationSnapshot& snap);
    bool heat_created_ = false;
    hsize_t n_heat_layers_ = 0;
    hsize_t n_heat_lid_layers_ = 0;
    hid_t ds_heat_water_temp_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_temp_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_energy_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_initial_energy_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_capacity_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_pore_volume_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_species_conc_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_species_initial_amount_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_species_exchange_ = H5I_INVALID_HID;
    hid_t ds_heat_bed_age_generation_ = H5I_INVALID_HID;
    hsize_t n_heat_bed_species_ = 0;
    hid_t ds_heat_surface_budget_ = H5I_INVALID_HID;
    hid_t ds_heat_evaporation_ = H5I_INVALID_HID;
    hid_t ds_heat_ground_temp_ = H5I_INVALID_HID;
    hid_t ds_heat_ground_energy_ = H5I_INVALID_HID;
    hid_t ds_heat_ground_capacity_ = H5I_INVALID_HID;
    hid_t ds_heat_layer_temp_ = H5I_INVALID_HID;
    hid_t ds_heat_layer_energy_ = H5I_INVALID_HID;
    hid_t ds_heat_layer_capacity_ = H5I_INVALID_HID;
    hid_t ds_heat_ground_budget_ = H5I_INVALID_HID;
    hid_t ds_heat_lid_temp_ = H5I_INVALID_HID;
    hid_t ds_heat_lid_energy_ = H5I_INVALID_HID;
    hid_t ds_heat_lid_capacity_ = H5I_INVALID_HID;
    hid_t ds_heat_lid_ground_contact_ = H5I_INVALID_HID;
    void createThermalDatasets(const SimulationSnapshot& snap);
    const MeshData* mixing_mesh_ = nullptr; // borrowed immutable prepared geometry
    std::unique_ptr<InertialEdges> mixing_edges_;
    std::unique_ptr<MomentumPhysics2D> mixing_diagnostics_;
    bool mixing_enabled_ = false, momentum_velocity_ = false;
    double mixing_cs_ = .1, mixing_background_ = 0, mixing_depth_coefficient_ = 0, mixing_dry_ = .001,
           coriolis_f_ = 0;
    const char* turbulence_name_ = "NONE"; 
    hid_t ds_face_eddy_viscosity_ = H5I_INVALID_HID;
    hid_t ds_face_strain_rate_ = H5I_INVALID_HID;
    hid_t ds_face_vx_ = H5I_INVALID_HID;
    hid_t ds_face_vy_ = H5I_INVALID_HID;
    hid_t ds_face_continuity_err_ = H5I_INVALID_HID;
    hid_t ds_edge_flux_ = H5I_INVALID_HID;
    hid_t ds_node_head_ = H5I_INVALID_HID;
    hid_t ds_node_depth_ = H5I_INVALID_HID;
 
    // Cumulative envelopes — fixed [nFace], overwritten in place each update()
    hid_t ds_face_max_depth_ = H5I_INVALID_HID;
    hid_t ds_face_max_velocity_ = H5I_INVALID_HID;
    hid_t ds_face_max_continuity_err_ = H5I_INVALID_HID;
 
    hsize_t n_faces_ = 0;
    hsize_t n_nodes_ = 0;
    hsize_t edge_stride_ = 3; 
    hsize_t n_steps_ = 0;     
 
    // Helpers
    void writeMeshTopology(const SimulationContext& ctx);
    void writeCrsVariable();
    hid_t createUnlimitedDataset(const char* name, int rank, const hsize_t* dims,
                                 const hsize_t* chunk_dims, hid_t type = -1);
    void writeStringAttr(hid_t loc, const char* name, const char* value);
    void writeDoubleAttr(hid_t loc, const char* name, double value);
    void extendAndWrite2D(hid_t ds, const double* data, hsize_t n_cols);
    void extendAndWrite4D(hid_t ds, const double* data, hsize_t a, hsize_t b, hsize_t c);
    void extendAndWrite3D(hid_t ds, const double* data, hsize_t dim1, hsize_t dim2);
    hid_t createFaceEnvelopeDataset(const char* name, const char* long_name, const char* units);
    void writeFaceEnvelope(hid_t ds, const double* data);
};
 
} // namespace openswmm::twoD
 
#endif // OPENSWMM_HAS_2D