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);

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 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_;

    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