QualityRouting.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_ROUTING_HPP
#define OPENSWMM_QUALITY_ROUTING_HPP
 
#include "FvQualityTransport.hpp"
#include <vector>
 
namespace openswmm {
 
struct SimulationContext;
 
namespace quality {
 
// ============================================================================
// Constants
// ============================================================================
 
constexpr double ZERO_VOLUME = 0.0353147; 
constexpr double ZERO_DEPTH = 0.003281;   
constexpr double LEGACY_ZERO = 1.0e-10;
 
// ============================================================================
// Shared shape of the legacy mixing kernels
//
// The pollutant kernels in QualityRouting.cpp and the water-age, heat and MSX
// mirrors in transport/components all route on the SAME rules — that identity
// is the mirrors' design contract, and the reason WATER_AGE or HEAT_TRANSPORT
// can be switched on without moving a pollutant trajectory. Four hand-copies
// of those rules had already drifted apart (each mirror still carried the
// pre-correction spelling, and their "matches the quality path" zero-volume
// constant was 1e-10 against the quality path's one litre), so the rules live
// here once and every kernel asks rather than re-derives.
// ============================================================================

bool linkTakesUpstreamValue(const SimulationContext& ctx, int link);

double conduitMixingInflow(const SimulationContext& ctx, int link, double dt);

bool linkIsDry(const SimulationContext& ctx, int link);

bool nodeIsReactor(const SimulationContext& ctx, int node);

bool nodeIsDry(const SimulationContext& ctx, int node, double q_in);

double storageEvapFactor(const SimulationContext& ctx, int node);

void updateUntreatedStorageHrt(SimulationContext& ctx, double dt);

void applyNodeTreatment(SimulationContext& ctx, int node, double dt, double q_in_cfs,
                        const double* cin);
 
// ============================================================================
// Quality solver
// ============================================================================
 
class QualitySolver {
public:
    void init(int n_nodes, int n_links, int n_pollutants);

    void execute(SimulationContext& ctx, double dt);
    FvTransportWater& fvWater() noexcept {return fv_transport_.water;}
    bool fvTransportAccepted() const noexcept {return fv_transport_.accepted();}
    bool hasFvRetainedDryMass() const noexcept {return fv_transport_.hasRetainedDryMass();}
    std::string fvDryRestartState(const SimulationContext& ctx) const {return fv_transport_.dryRestartState(ctx);}
    std::string restoreFvDryRestart(SimulationContext& ctx,const std::string& blob,bool apply) {return fv_transport_.restoreDryRestart(ctx,blob,apply);}
    std::vector<double> fvRetainedPollutantMass(const SimulationContext& ctx) const {return fv_transport_.retainedPollutantMass(ctx);}
    std::vector<double> fvRetainedSpeciesMass(const SimulationContext& ctx) const {return fv_transport_.retainedSpeciesMass(ctx);}
    void beginFvWindow() noexcept {fv_transport_.beginWindow();}

    void assembleExternalLoads(SimulationContext& ctx, double dt);

    void addExtInflowLoads(SimulationContext& ctx, double dt);
    void addCouplingLoads(SimulationContext& ctx, double dt);
    void addQualityOnlyInflows(SimulationContext& ctx, double dt); 

    void addWetWeatherLoads(SimulationContext& ctx, double dt);

    void updateLinkQuality(SimulationContext& ctx, double dt);


    void applyTreatment(SimulationContext& ctx, double dt, bool full_inflow = true);
 
private:
    int n_pollutants_ = 0;
    FvQualityTransport fv_transport_;
    std::vector<double> qual_vol_lat_;
    std::vector<double> qual_vol_lat_neg_;
 
    // Quality mass inflow arrays are stored on NodeData (nodes.qual_mass_in[],
    // nodes.qual_vol_in[]) so that external quality sources (user forcing, DWF
    // quality, etc.) can contribute at the same assembly point.

    void addRdiiLoads(SimulationContext& ctx, double dt);

    void addDwfLoads(SimulationContext& ctx, double dt);

    void addGwLoads(SimulationContext& ctx, double dt);

    void addIfaceLoads(SimulationContext& ctx, double dt);

    void accumulateLinkLoads(SimulationContext& ctx, double dt);

    void mixAtNodes(SimulationContext& ctx, double dt);

    void applyDecay(SimulationContext& ctx, double dt);
};
 
} // namespace quality
} // namespace openswmm
 
#endif // OPENSWMM_QUALITY_ROUTING_HPP