NegativeSources.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_QUALITY_NEGATIVE_SOURCES_HPP
#define OPENSWMM_QUALITY_NEGATIVE_SOURCES_HPP
 
#include <string>
 
#include "../core/SimulationContext.hpp"
 
namespace openswmm {
namespace quality {

inline void bookNegativeSourceClamp(SimulationContext& ctx, int node, int p,
                                    double shortfall) {
    auto& st = ctx.negsrc;
    st.clamp_events += 1;
    st.shortfall_mass += shortfall;
    // The negative request was booked (signed) into qual_routing_ex_in by
    // the loaders; the unmet part did not actually leave the water, so it
    // is returned to the row. v1 scope: EXTERNAL_INFLOW and the API flux
    // are the admitted negative pathways, and both book into ex_in —
    // negative DWF/GW/RDII concentrations remain out of scope, recorded.
    if (p >= 0 &&
        static_cast<std::size_t>(p) <
            ctx.mass_balance.qual_routing_ex_in.size())
        ctx.mass_balance.qual_routing_ex_in[static_cast<std::size_t>(p)] +=
            shortfall;
    if (!st.first_clamp_recorded) {
        st.first_clamp_recorded = true;
        st.first_node = node;
    }
}

inline void bookNegativeAgeClamp(SimulationContext& ctx, int node) {
    auto& st = ctx.negsrc;
    st.age_clamp_events += 1;
    if (!st.first_clamp_recorded) {
        st.first_clamp_recorded = true;
        st.first_node = node;
    }
}

inline void bookNegativeCellSourceClamp(SimulationContext& ctx, int conduit,
                                        double shortfall) {
    auto& st = ctx.negsrc;
    st.clamp_events += 1;
    st.shortfall_mass += shortfall;
    if (!st.first_clamp_recorded) {
        st.first_clamp_recorded = true;
        st.first_node = conduit;
    }
}

inline void summarizeNegativeSourceClamps(SimulationContext& ctx) {
    const auto& st = ctx.negsrc;
    if (st.clamp_events == 0 && st.age_clamp_events == 0) return;
    ctx.warnings.push_back(
        "D-NS1 summary: extraction exceeded available mass " +
        std::to_string(st.clamp_events) + " time(s) (unmet extraction " +
        std::to_string(st.shortfall_mass) + " internal mass units)" +
        (st.age_clamp_events > 0
             ? ", water-age extraction clamped " +
                   std::to_string(st.age_clamp_events) + " time(s)"
             : std::string()) +
        ", first at element index " + std::to_string(st.first_node) +
        ". Extraction clamps ROUTINELY while the system fills, when elements "
        "are near-empty; a nonzero count is not by itself a modelling error. "
        "Node-seam clamps are ledgered (the ledger carries the mass actually "
        "removed); ARD cell-source clamps are counted only — see "
        "bookNegativeCellSourceClamp.");
}
 
}  // namespace quality
}  // namespace openswmm
 
#endif  // OPENSWMM_QUALITY_NEGATIVE_SOURCES_HPP