GwTransportData.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_GW_TRANSPORT_DATA_HPP
#define OPENSWMM_ENGINE_2D_GW_TRANSPORT_DATA_HPP
 
#include <cstdint>
#include <limits>
#include <set>
#include <unordered_map>
#include <string>
#include <vector>
 
namespace openswmm::twoD {

enum class GwZone : int8_t {
    SAT = 0,   
    UNSAT = 1, 
    LAYER = 2  
};

enum class GwScope : int8_t {
    GLOBAL = 0, 
    TAG = 1,    
    CELL = 2    
};

struct GwTransportOptions {
    std::string unsat_transport = "BULK"; 
    // Explicit opt-in; dormant legacy CONDUCTION flags never activate it.
    std::string thermal_model = "WATER_ONLY";
    int thermal_layers = 16;
    bool lateral_conduction = false;
    double thermal_max_step = 60, water_conductivity = .606, air_conductivity = .025,
           surface_resistance = .1;
    std::string soil_et_heat = "LATENT_SURFACE";
    std::set<std::string> thermal_authored;
    bool transport_pollutants = true;
    bool transport_msx = true;
    bool transport_age = true;
    bool transport_temperature = true;
    bool dispersion = true; 
    bool conduction = true; 
    std::string surface_thermal_bc = "AIR";
    std::string surface_thermal_arg;
    std::string deep_thermal_bc = "GEOTHERMAL_FLUX";
    std::string deep_thermal_arg;
    double deep_depth = 0.0;
    std::string thermal_mixing = "ARITHMETIC";
    double c_diff = 0.4;
    bool authored = false;
};

struct GwParamsRow {
    GwScope scope = GwScope::GLOBAL;
    std::string tag;         
    int cell = -1;           
    double rho_s = 2650.0;   
    double c_s = 880.0;      
    double lambda_s = 2.0;   
    double a_s = 0.0;        
    double alpha_L = 1.0;    
    double alpha_T = 0.1;    
    double D_m = 1.0e-9;     
    double D_v = 1.0e-9;     
    double geo_flux = 0.065; 
};

struct GwSorptionRow {
    GwScope scope = GwScope::GLOBAL;
    std::string tag;
    int cell = -1;
    std::string species;
    double kd = 0.0;     
    double decay = -1.0; 
};

struct GwInitialQualityRow {
    GwScope scope = GwScope::GLOBAL;
    std::string tag;
    int cell = -1;
    GwZone zone = GwZone::SAT;
    int layer = -1; 
    std::string species;
    double value = 0.0;
};

struct GwBoundaryQualityRow {
    int cell = -1; 
    int edge = -1; 
    std::string species;
    std::string kind = "CONC";
    double value = 0.0;  
    std::string ts_name; 
};

struct GwSourceSpeciesTerm {
    std::string species;
    std::string kind = "CONC"; 
    double value = 0.0;
    std::string ts_name;
};

struct GwSourceRow {
    std::string name;
    GwScope scope = GwScope::CELL; 
    std::string tag;
    int cell = -1;
    double x = 0.0, y = 0.0; 
    bool by_xy = false;
    double flow = 0.0;   
    std::string flow_ts; 
    double scale = 1.0;  
    std::vector<GwSourceSpeciesTerm> species;
};

struct GwTransportData {
    GwTransportOptions options;
    std::vector<GwParamsRow> params;
    std::vector<GwSorptionRow> sorption;
    std::vector<GwInitialQualityRow> initial_quality;
    std::string initial_quality_file;
    std::vector<GwBoundaryQualityRow> boundary_quality;
    std::vector<GwSourceRow> sources;

    bool empty() const noexcept {
        return !options.authored && params.empty() && sorption.empty() && initial_quality.empty() &&
               initial_quality_file.empty() && boundary_quality.empty() && sources.empty();
    }

    void clear() { *this = GwTransportData{}; }
 
    // Derived authoring indexes contain positions, never vector pointers. Direct
    // key edits or bulk replacement must invalidate them; parser and FILE reload
    // do so explicitly. Size checks also catch ordinary direct append/erase.
    void invalidateAuthoringIndexes() noexcept { source_index_size_ = quality_index_size_ = noRow; }
    static constexpr std::size_t noRow = std::numeric_limits<std::size_t>::max();

    std::size_t findSource(const std::string& name) {
        if (source_index_size_ != sources.size()) {
            source_index_size_ = noRow;
            source_index_.clear();
            source_index_.reserve(sources.size());
            for (std::size_t i = 0; i < sources.size(); ++i)
                source_index_.emplace(sources[i].name, i); // first match wins
            source_index_size_ = sources.size();
        }
        const auto it = source_index_.find(name);
        return it == source_index_.end() ? noRow : it->second;
    }

    std::size_t findInitialQuality(const GwInitialQualityRow& row) {
        if (quality_index_size_ != initial_quality.size()) {
            quality_index_size_ = noRow;
            quality_index_.clear();
            quality_index_.reserve(initial_quality.size());
            for (std::size_t i = 0; i < initial_quality.size(); ++i)
                quality_index_.emplace(QualityKey(initial_quality[i]), i);
            quality_index_size_ = initial_quality.size();
        }
        const auto it = quality_index_.find(QualityKey(row));
        return it == quality_index_.end() ? noRow : it->second;
    }

    void sourceAppended() {
        if (source_index_size_ != noRow && source_index_size_ + 1 == sources.size()) {
            source_index_.emplace(sources.back().name, sources.size() - 1);
            source_index_size_ = sources.size();
        }
    }

    void initialQualityAppended() {
        if (quality_index_size_ != noRow && quality_index_size_ + 1 == initial_quality.size()) {
            quality_index_.emplace(QualityKey(initial_quality.back()), initial_quality.size() - 1);
            quality_index_size_ = initial_quality.size();
        }
    }

    void removeSource(std::size_t index) {
        if (source_index_size_ == sources.size() && index + 1 == sources.size()) {
            const auto it = source_index_.find(sources[index].name);
            if (it != source_index_.end() && it->second == index)
                source_index_.erase(it);
            --source_index_size_;
        } else
            source_index_size_ = noRow;
        sources.erase(sources.begin() + index);
    }

    void removeInitialQuality(std::size_t index) {
        if (quality_index_size_ == initial_quality.size() && index + 1 == initial_quality.size()) {
            const auto it = quality_index_.find(QualityKey(initial_quality[index]));
            if (it != quality_index_.end() && it->second == index)
                quality_index_.erase(it);
            --quality_index_size_;
        } else
            quality_index_size_ = noRow;
        initial_quality.erase(initial_quality.begin() + index);
    }
 
private:
    struct QualityKey {
        GwScope scope;
        std::string tag;
        int cell;
        GwZone zone;
        int layer;
        std::string species;
        explicit QualityKey(const GwInitialQualityRow& r)
            : scope(r.scope), tag(r.tag), cell(r.cell), zone(r.zone), layer(r.layer),
              species(r.species) {}
        bool operator==(const QualityKey& r) const noexcept {
            return scope == r.scope && tag == r.tag && cell == r.cell && zone == r.zone &&
                   layer == r.layer && species == r.species;
        }
    };
    struct QualityHash {
        std::size_t operator()(const QualityKey& r) const noexcept {
            std::size_t h = 0;
            const auto combine = [&h](std::size_t v) {
                h ^= v + 0x9e3779b9u + (h << 6) + (h >> 2);
            };
            combine(std::hash<int>{}(static_cast<int>(r.scope)));
            combine(std::hash<std::string>{}(r.tag));
            combine(std::hash<int>{}(r.cell));
            combine(std::hash<int>{}(static_cast<int>(r.zone)));
            combine(std::hash<int>{}(r.layer));
            combine(std::hash<std::string>{}(r.species));
            return h;
        }
    };
    std::unordered_map<std::string, std::size_t> source_index_;
    std::unordered_map<QualityKey, std::size_t, QualityHash> quality_index_;
    std::size_t source_index_size_ = noRow;
    std::size_t quality_index_size_ = noRow;
};

const char* gwZoneToken(GwZone z) noexcept;
bool parseGwZone(const std::string& token, GwZone& z) noexcept;
const char* gwScopeToken(GwScope s) noexcept;
 
} // namespace openswmm::twoD
 
#endif // OPENSWMM_ENGINE_2D_GW_TRANSPORT_DATA_HPP