SurfaceQuality2D.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_2D_QUALITY_SURFACE_QUALITY_2D_HPP
#define OPENSWMM_ENGINE_2D_QUALITY_SURFACE_QUALITY_2D_HPP
 
#include <cstddef>
#include <cstdint>
#include <string>
#include <utility>
#include <vector>
 
#include "../../input/SectionRegistry.hpp"
 
namespace openswmm {
struct SimulationContext;
}
 
namespace openswmm::twoD {
 
struct MeshData;
struct SurfaceStateData;
struct SurfaceTransportState;
struct SolverOptions2D;

enum class SqScope : int8_t { GLOBAL = 0, TAG = 1, CELL = 2 };
 
struct SqScopeKey {
    SqScope scope = SqScope::GLOBAL;
    std::string tag; 
    int cell = -1;   
};

struct CoverageRow2D {
    SqScopeKey key;
    std::vector<std::pair<std::string, double>> uses; 
};

struct LoadingRow2D {
    SqScopeKey key;
    std::string species;
    double value = 0.0;
};

struct CurbRow2D {
    SqScopeKey key;
    double length = 0.0;
};

class SurfaceQuality2D {
public:
    // ---- authoring (section handlers, C API, writer) -----------------------
    std::vector<CoverageRow2D> coverage_rows;
    std::vector<LoadingRow2D> loading_rows;
    std::vector<CurbRow2D> curb_rows;
    bool authored() const noexcept {
        return !coverage_rows.empty() || !loading_rows.empty() || !curb_rows.empty();
    }

    void clearRows() {
        coverage_rows.clear();
        loading_rows.clear();
        curb_rows.clear();
    }

    std::vector<std::string> resolve(const SimulationContext& ctx, const MeshData& mesh,
                                     const SurfaceTransportState& tr, const SolverOptions2D& opts);

    bool active() const noexcept { return active_; }

    void initState(const SimulationContext& ctx, const MeshData& mesh);

    void step(const SimulationContext& ctx, const MeshData& mesh, SurfaceStateData& state,
              double dt_runoff, double abs_time, bool is_raining);
 
    // ---- read-back --------------------------------------------------------
    int nLandUses() const noexcept { return n_lu_; }
    int nSpecies() const noexcept {
        return n_sp_;
    } 

    int nCells() const noexcept { return n_cells_; }
    int rowOf(int s) const noexcept { return row_of_[static_cast<std::size_t>(s)]; }
    const std::string& speciesName(int s) const noexcept {
        return names_[static_cast<std::size_t>(s)];
    }

    double coverage(int c, int lu) const noexcept { return cov_[cidx(c, lu)]; }
    double curbLength(int c) const noexcept { return curb_[static_cast<std::size_t>(c)]; }
    double buildup(int c, int lu, int s) const noexcept { return bu_[bidx(c, lu, s)]; }
    double buildupPerArea(int c, int s) const noexcept;
    const std::vector<double>& ledInitBuildup() const noexcept { return led_init_; }
    const std::vector<double>& ledBuildup() const noexcept { return led_bu_; }
    const std::vector<double>& ledWashoff() const noexcept { return led_wo_; }
    const std::vector<double>& ledSweeping() const noexcept { return led_sw_; }
    const std::vector<double>& ledBmp() const noexcept { return led_bmp_; }
    double mcf(int s) const noexcept { return mcf_[static_cast<std::size_t>(s)]; }
    double runoffVolume(int c) const noexcept { return runoff_vol_[static_cast<std::size_t>(c)]; }
    double wetRunoffVolume(int c) const noexcept {
        return wet_runoff_vol_[static_cast<std::size_t>(c)];
    }
 
private:
    std::size_t cidx(int c, int lu) const noexcept {
        return static_cast<std::size_t>(c) * static_cast<std::size_t>(n_lu_) +
               static_cast<std::size_t>(lu);
    }
    std::size_t bidx(int c, int lu, int s) const noexcept {
        return (static_cast<std::size_t>(lu) * static_cast<std::size_t>(n_sp_) +
                static_cast<std::size_t>(s)) *
                   static_cast<std::size_t>(n_cells_) +
               static_cast<std::size_t>(c);
    }
    struct Params { // per (lu, s), read from the 1D tables at resolve
        int bu_type = 0;
        double c0 = 0, c1 = 0, c2 = 0;
        int ts_idx = -1;
        int normalizer = 0;
        double max_days = 0;
        int wo_type = 0;
        double coeff = 0, expon = 0, sweep_effic = 0, bmp_effic = 0;
    };
    const Params& param(int lu, int s) const noexcept {
        return params_[static_cast<std::size_t>(lu) * static_cast<std::size_t>(n_sp_) +
                       static_cast<std::size_t>(s)];
    }
    void loadParams(const SimulationContext& ctx);
 
    bool active_ = false;
    int n_cells_ = 0, n_lu_ = 0, n_sp_ = 0;
    bool si_ = false;
    double area_to_landarea_ = 1.0;      
    std::vector<int> row_of_;            
    std::vector<std::string> names_;     
    std::vector<double> mcf_;            
    std::vector<Params> params_;         
    std::vector<double> cov_;            
    std::vector<double> curb_;           
    std::vector<double> area_la_;        
    std::vector<double> init_;           
    std::vector<double> bu_;             
    std::vector<double> last_swept_;     
    std::vector<double> runoff_vol_;     
    std::vector<double> wet_runoff_vol_; 
    std::vector<double> led_init_, led_bu_, led_wo_, led_sw_, led_bmp_; 
};
 
// ---- section parsers (exposed for tests) -----------------------------------
std::string parse2DCoveragesLine(const std::vector<std::string>& tokens,
                                 std::vector<CoverageRow2D>& rows);
std::string parse2DLoadingsLine(const std::vector<std::string>& tokens,
                                std::vector<LoadingRow2D>& rows);
std::string parse2DCurbLengthLine(const std::vector<std::string>& tokens,
                                  std::vector<CurbRow2D>& rows);

void registerSurfaceQualitySections(SurfaceQuality2D& sq, input::SectionRegistry& registry);

std::string formatSqScope(const SqScopeKey& k);
std::string parseSqScope(const std::vector<std::string>& tokens, std::size_t& at, SqScopeKey& key,
                         const char* section);
 
} // namespace openswmm::twoD
 
#endif // OPENSWMM_ENGINE_2D_QUALITY_SURFACE_QUALITY_2D_HPP