Inlet.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_INLET_HPP
#define OPENSWMM_INLET_HPP
 
#include <cstdint>
#include <vector>
 
namespace openswmm {
 
struct SimulationContext;
struct XSectParams;
struct Table;
 
namespace inlet {

enum class InletType : int {
    GRATE = 0,
    CURB = 1,
    COMBO = 2,
    SLOTTED = 3,
    DROP_GRATE = 4,
    DROP_CURB = 5,
    CUSTOM = 6
};

enum class GrateType : int {
    P_BAR_50 = 0,
    P_BAR_50x100 = 1,
    P_BAR_30 = 2,
    CURVED_VANE = 3,
    TILT_BAR_45 = 4,
    TILT_BAR_30 = 5,
    RETICULINE = 6,
    GENERIC = 7
};

enum class Placement : int { AUTOMATIC = 0, ON_GRADE = 1, ON_SAG = 2 };

enum class ThroatAngle : int { HORIZONTAL = 0, INCLINED = 1, VERTICAL = 2 };

enum class CurveKind : int { UNRESOLVED = 0, DIVERSION = 1, RATING = 2 };

inline constexpr double MIN_RUNOFF_FLOW = 0.001;
inline constexpr double INLET_FUDGE = 0.0001;
inline constexpr double INLET_BIG = 1.0e10;
 
// ============================================================================
// Kernel inputs — the legacy module-level shared variables, made explicit
// ============================================================================

struct Geom {
    double sx = 0.01;       
    double sl = 0.0;        
    double sw = 0.01;       
    double a = 0.0;         
    double w = 0.0;         
    double t = 0.0;         
    double n = 0.016;       
    int nsides = 1;         
    double t_crown = 100.0; 
    double beta = 0.0;      
    double qfactor = 0.0;   

    const XSectParams* xs = nullptr;
};

struct Design {
    int type = 0; 
    int grate_type = static_cast<int>(GrateType::GENERIC);
    double grate_length = 0.0;   
    double grate_width = 0.0;    
    double frac_open_area = 0.0; 
    double splash_veloc = 0.0;   
    double curb_length = 0.0;    
    double curb_height = 0.0;    
    int curb_throat = static_cast<int>(ThroatAngle::VERTICAL);
    double slotted_length = 0.0; 
    double slotted_width = 0.0;  
};

struct UsageParams {
    int num_inlets = 1;
    double clog_factor = 1.0; 
    double flow_limit = 0.0;  
};
 
// ============================================================================
// Pure kernel — 1:1 ports of the legacy static functions
// ============================================================================

double getEo(double sr, double ts, double w);

double getFlowSpread(const Geom& g, double Q);

double getGutterFlowRatio(const Geom& g, double w);

double getGutterAreaRatio(const Geom& g, double grate_width, double area);

double getSplashOverVelocity(int grate_type, double grate_length);

double getGrateInletCapture(const Design& d, Geom& g, double Q);

double getCurbInletCapture(const Geom& g, double Q, double opening_length);

double getOnGradeInletCapture(const Design& d, Geom& g, double Q, double depth);

double getOnGradeCapturedFlow(const Design& d, const UsageParams& u, Geom& g, double q,
                              double depth);

void findOnSagGrateFlows(const Design& d, const Geom& g, double depth, double* weir_flow,
                         double* orifice_flow);

void findOnSagCurbFlows(const Design& d, const Geom& g, double depth, double opening_length,
                        double* weir_flow, double* orifice_flow);

double getCurbOrificeFlow(double flow_depth, double opening_height, double opening_length,
                          int throat_angle);

double getOnSagSlottedFlow(const Design& d, double depth);

double getOnSagInletCapture(const Design& d, const Geom& g, double depth);

double getOnSagCapturedFlow(const Design& d, const UsageParams& u, const Geom& g, double depth,
                            int nsides_prev);

double getCustomCapturedFlow(const UsageParams& u, const Geom& g, const Table& curve,
                             int curve_kind, double q, double depth, double ucf_flow,
                             double ucf_len);

double getInletArea(const Design& d, const UsageParams& u);
 
// ============================================================================
// Runtime SoA
// ============================================================================
 
struct InletSoA {
    int count = 0;
 
    // --- host / topology -----------------------------------------------------
    std::vector<int> link_idx;        
    std::vector<int> host_node;       
    std::vector<int> node_idx;        
    std::vector<int> bypass_node;     
    std::vector<int> up_link;         
    std::vector<int> up_link2;        
    std::vector<uint8_t> two_inbound; 
 
    // --- design --------------------------------------------------------------
    std::vector<int> inlet_type;
    std::vector<int> grate_type;
    std::vector<double> grate_length;   
    std::vector<double> grate_width;    
    std::vector<double> open_area;      
    std::vector<double> splash_veloc;   
    std::vector<double> curb_length;    
    std::vector<double> curb_height;    
    std::vector<int> curb_throat;       
    std::vector<double> slotted_length; 
    std::vector<double> slotted_width;  
    std::vector<int> curve_index;       
    std::vector<int> curve_kind;        
 
    // --- usage ---------------------------------------------------------------
    std::vector<int> num_inlets;
    std::vector<double> clog_factor;
    std::vector<double> flow_limit;    
    std::vector<double> local_depress; 
    std::vector<double> local_width;   
    std::vector<int> placement;        
    std::vector<uint8_t> is_sag;       
 
    // --- street / conduit geometry (internal units) --------------------------
    std::vector<double> sx;                
    std::vector<double> gutter_depression; 
    std::vector<double> gutter_width;      
    std::vector<double> road_roughness;    
    std::vector<double> t_crown;           
    std::vector<int> n_sides;
    std::vector<double> slope;       
    std::vector<double> flow_factor; 
 
    // --- per-step results ----------------------------------------------------
    std::vector<double> q_approach;     
    std::vector<double> flow_capture;   
    std::vector<double> backflow;       
    std::vector<double> backflow_ratio; 
 
    // --- legacy statistics (inlet.c:78-87, updateInletStats :985) ------------
    std::vector<int> flow_periods;
    std::vector<int> capture_periods;
    std::vector<int> backflow_periods;
    std::vector<double> peak_flow;         
    std::vector<double> peak_flow_capture; 
    std::vector<double> avg_flow_capture;  
    std::vector<double> bypass_freq;       
 
    // --- volume statistics (Gap #68 → InletUsageStore) -----------------------
    std::vector<double> stat_capture_vol;  
    std::vector<double> stat_bypass_vol;   
    std::vector<double> stat_backflow_vol; 
    std::vector<double> stat_peak_flow;    

    void resize(int n);
};
 
class InletSolver {
public:
    void init(SimulationContext& ctx);

    void computeAll(SimulationContext& ctx, double dt);

    void adjustQualInflows(SimulationContext& ctx, double dt);

    void adjustFloodingTotals(SimulationContext& ctx, double dt) const;

    void gatherStats(SimulationContext& ctx) const;

    const InletSoA& soa() const noexcept { return soa_; }
    bool hasInlets() const noexcept { return soa_.count > 0; }
 
private:
    InletSoA soa_;

    std::vector<double> node_inlet_flow_;
    std::vector<double> node_inflow_;

    int nsides_prev_ = 0;

    std::vector<uint8_t> is_capture_node_;

    Geom geomOf(const SimulationContext& ctx, int ii, const XSectParams* xs) const;
    Design designOf(int ii) const;
    UsageParams usageOf(int ii) const;

    void updateStats(int ii, double q);

    void computeBackflowRatios();
};
 
} // namespace inlet
} // namespace openswmm
 
#endif // OPENSWMM_INLET_HPP