DefaultOutputPlugin.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_DEFAULT_OUTPUT_PLUGIN_HPP
#define OPENSWMM_ENGINE_DEFAULT_OUTPUT_PLUGIN_HPP
 
#include "../../../include/openswmm/plugin_sdk/IOutputPlugin.hpp"
 
#include "../io/CheckpointOutputPublication.hpp"
#include "../io/CheckpointFile.hpp"
#include <string>
#include <atomic>
#include <cstdio>
#include <vector>
#include <memory>
 
namespace openswmm {

class DefaultOutputPlugin final : public IOutputPlugin {
public:
    explicit DefaultOutputPlugin(std::string out_path);
    ~DefaultOutputPlugin() override = default;
 
    // -----------------------------------------------------------------------
    // 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(); }
 
private:
    friend class SWMMEngine;
    struct PreparedCheckpoint;
    bool checkpoint_fresh_ = false;
    std::string checkpoint_header_;
    std::string checkpointBytes(const SimulationContext& ctx, double next_report_ms) const;
    std::shared_ptr<PreparedCheckpoint> prepareCheckpoint(const SimulationContext& ctx,
                                                          double next_report_ms, std::string bytes);
    void installCheckpoint(PreparedCheckpoint& prepared);
    io::CheckpointOutputPublication::Output
    checkpointPublication(const PreparedCheckpoint& prepared) const;
    void adoptCheckpoint(PreparedCheckpoint& prepared) noexcept;
    void validateCheckpoint(const SimulationContext& ctx, double next_report_ms, int periods,
                            const std::string& bytes) const;
    std::string readPrefix() const;
    std::string captureFileCheckpoint(const SimulationContext& ctx, double next,
                                      const std::filesystem::path& base,
                                      std::shared_ptr<io::OwnedCheckpointFile>& artifact) const;
    std::shared_ptr<PreparedCheckpoint> prepareFileCheckpoint(const SimulationContext& ctx,
                                                              double next, std::string bytes);
    void validateFileCheckpoint(FILE* file, uint64_t bytes, const SimulationContext& ctx,
                                double next, int periods) const;
 
    std::string out_path_;
    PluginState state_ = PluginState::UNLOADED;
    std::string last_error_;
    int step_count_ = 0;
 
    FILE* out_file_ = nullptr;
    int n_subcatch_ = 0;
    int n_nodes_ = 0;
    int n_links_ = 0;
    int n_polluts_ = 0;
    int n_subcatch_vars_ = 0;
    bool snow_process_ = false;
    int n_node_vars_ = 0;
    int n_link_vars_ = 0;
    int flow_units_code_ = 0;
    long id_start_pos_ = 0;
    long input_start_pos_ = 0;
    long output_start_pos_ = 0;
    int n_periods_ = 0;
 
    // Static-object header is written from the SimulationContext (internal
    // units), so it still needs this length factor. Subcatchment area is
    // already held in display units and needs none. Per-timestep results
    // arrive pre-converted by the engine boundary and need no plugin-side
    // conversion.
    double ucf_length_ = 1.0;
 
    // Per-object report flags, captured during prepare() from SimulationContext
    std::vector<char> subcatch_rpt_flag_;
    std::vector<char> node_rpt_flag_;
    std::vector<char> link_rpt_flag_;
 
    static constexpr int MAGIC_NUMBER = 516114522;
    static constexpr int VERSION = 60000; // SWMM 6.0.000
    static constexpr int MAX_SYS_RESULTS = 15;

    void writeHeader(const SimulationContext& ctx);
    void writeID(const char* id);
    void writeInt4(int value);
    void writeReal4(float value);
    void writeReal8(double value);
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_DEFAULT_OUTPUT_PLUGIN_HPP */