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_; }
 
    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;
 
    // -- 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;
 
    // -- 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;
    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_;
 
    // -- Helpers ----------------------------------------------------------
 
    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 */