OutputReader.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_OUTPUT_READER_HPP
#define OPENSWMM_ENGINE_OUTPUT_READER_HPP
 
#include <cstdio>
#include <cstdint>
#include <string>
#include <vector>

 
namespace openswmm {

class OutputReader {
public:
    OutputReader() = default;
    ~OutputReader();

    OutputReader(const OutputReader&) = delete;
    OutputReader& operator=(const OutputReader&) = delete;

    bool open(const char* path);

    bool openLive(const char* path);

    int refresh();

    bool is_live() const noexcept { return live_; }

    void close();

    bool is_open() const noexcept { return file_ != nullptr; }
 
    // -- Metadata ---------------------------------------------------------

    int version() const noexcept { return version_; }
    int flow_units() const noexcept { return flow_units_; }
    int subcatch_count() const noexcept { return n_subcatch_; }
    int node_count() const noexcept { return n_nodes_; }
    int link_count() const noexcept { return n_links_; }
    int pollut_count() const noexcept { return n_polluts_; }
    int period_count() const noexcept { return n_periods_; }
    double start_date() const noexcept { return start_date_; }
    int report_step() const noexcept { return report_step_; }
    int error_code() const noexcept { return error_code_; }

    bool has_subcatch_variable(int code) const {
        const int i = subcatchColumn(code);
        return i >= 0 && i < n_subcatch_vars_;
    }

    int subcatch_var_count() const noexcept { return n_subcatch_vars_; }
    int node_var_count() const noexcept { return n_node_vars_; }
    int link_var_count() const noexcept { return n_link_vars_; }
    int system_var_count() const noexcept { return n_system_vars_; }
 
    // -- Object IDs -------------------------------------------------------

    const char* subcatch_id(int index) const;
    const char* node_id(int index) const;
    const char* link_id(int index) const;

    const char* pollut_id(int index) const;
    int pollut_units(int index) const;
 
    // -- Per-period results (all objects, one variable) --------------------

    bool get_subcatch_result(int period, int var, float* values) const;

    bool get_node_result(int period, int var, float* values) const;

    bool get_link_result(int period, int var, float* values) const;

    bool get_system_result(int period, int var, float* value) const;

    bool get_node_block(int period, std::vector<float>& values) const;
    bool get_link_block(int period, std::vector<float>& values) const;
 
    // -- Time series (one object, one variable, period range) --------------

    bool get_subcatch_series(int obj_idx, int var, int start_period, int end_period,
                             float* values) const;

    bool get_node_series(int obj_idx, int var, int start_period, int end_period,
                         float* values) const;

    bool get_link_series(int obj_idx, int var, int start_period, int end_period,
                         float* values) const;

    bool get_system_series(int var, int start_period, int end_period, float* values) const;
 
    // -- Per-object all-variables at one period ----------------------------

    bool get_subcatch_attribute(int obj_idx, int period, float* values, int* count) const;

    bool get_node_attribute(int obj_idx, int period, float* values, int* count) const;

    bool get_link_attribute(int obj_idx, int period, float* values, int* count) const;
 
    // -- Period time -------------------------------------------------------

    bool get_period_time(int period, double* time) const;
 
    // -- Per-node summary statistics — Slice QA-01 -------------------------
    //
    // Computed on-demand from the per-period node results stored in the
    // file. See openswmm_output.h for unit conventions + the report-step
    // vs. routing-step precision caveat. Each method is O(n_periods).
    bool get_node_stat_max_depth(int node_idx, double* value) const;
    bool get_node_stat_max_overflow(int node_idx, double* value) const;
    bool get_node_stat_vol_flooded(int node_idx, double* value) const;
    bool get_node_stat_time_flooded(int node_idx, double* value) const;
 
private:
    static constexpr int32_t MAGIC_NUMBER = 516114522;
 
    FILE* file_ = nullptr;
 
    // Header fields
    int version_ = 0;
    int flow_units_ = 0;
    int n_subcatch_ = 0;
    int n_nodes_ = 0;
    int n_links_ = 0;
    int n_polluts_ = 0;
 
    // Variable counts (read from file)
    int n_subcatch_vars_ = 0;
    std::vector<int> subcatch_codes_;
    int subcatchColumn(int code) const;
    int n_node_vars_ = 0;
    int n_link_vars_ = 0;
    int n_system_vars_ = 0;
 
    // Report metadata
    double start_date_ = 0.0;
    int report_step_ = 0;
 
    // Footer fields
    long id_start_pos_ = 0;
    long input_start_pos_ = 0;
    long output_start_pos_ = 0;
    int n_periods_ = 0;
    int error_code_ = 0;
 
    // Computed: bytes per period record
    long bytes_per_period_ = 0;
 
    // openLive(): period count comes from the file size until the footer lands
    bool live_ = false;
 
    // Object IDs
    std::vector<std::string> subcatch_ids_;
    std::vector<std::string> node_ids_;
    std::vector<std::string> link_ids_;
    std::vector<std::string> pollut_ids_;
    std::vector<int> pollut_units_;
 
    // -- Helpers ----------------------------------------------------------

    bool readResultBlock(int period, int objectType, int count, int variables,
                         std::vector<float>& values) const;
    bool readFooter();
    bool readHeader();
    bool readIDs();
    bool readVariableCodes();

    bool readInt4(int32_t& value) const;
    bool readReal4(float& value) const;
    bool readReal8(double& value) const;

    long periodOffset(int period) const;

    bool seekToVar(int period, int obj_type, int obj_idx, int var) const;
};
 
} /* namespace openswmm */
 
#endif /* OPENSWMM_ENGINE_OUTPUT_READER_HPP */