Controls.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_CONTROLS_HPP
#define OPENSWMM_CONTROLS_HPP
 
#include <cstdint>
#include <vector>
#include <string>
#include <unordered_map>
#include "../core/StringCase.hpp"
#include "../math/MathExpr.hpp"
 
namespace openswmm {
 
struct SimulationContext;
 
namespace controls {
 
// ============================================================================
// Comparison and logic operators
// ============================================================================
 
enum class CompareOp : int { EQ = 0, NE = 1, LT = 2, LE = 3, GT = 4, GE = 5 };
enum class LogicOp   : int { AND = 0, OR = 1 };
 
// ============================================================================
// Condition variable types (matching ALL legacy RuleAttrib values)
// ============================================================================
 
enum class ConditionVar : int {
    // Node attributes
    NODE_DEPTH     = 0,
    NODE_MAXDEPTH  = 1,
    NODE_HEAD      = 2,
    NODE_VOLUME    = 3,
    NODE_INFLOW    = 4,
 
    // Link attributes
    LINK_FLOW      = 10,
    LINK_DEPTH     = 11,
    LINK_SETTING   = 12,
    LINK_STATUS    = 13,
    LINK_FULLFLOW  = 14,
    LINK_FULLDEPTH = 15,
    LINK_VELOCITY  = 16,
    LINK_LENGTH    = 17,
    LINK_SLOPE     = 18,
    LINK_TIMEOPEN  = 19,
    LINK_TIMECLOSED= 20,
 
    // Gage attributes
    GAGE_RAIN      = 30,      
    GAGE_RAIN_PAST = 31,      
 
    // System / time
    SIM_TIME       = 40,
    SIM_DATE       = 41,
    CLOCK_TIME     = 42,
    SIM_DAY        = 43,      
    SIM_MONTH      = 44,      
    SIM_DAYOFYEAR  = 45       
};
 
// ============================================================================
// Action attribute (what is being set on the link)
// ============================================================================
 
enum class ActionType : int {
    NUMERIC    = 0,    
    CURVE      = 1,    
    TIMESERIES = 2,    
    PID        = 3     
};
 
// ============================================================================
// Rule premise (condition)
// ============================================================================
 
struct Premise {
    LogicOp      logic         = LogicOp::AND;
    bool         is_expression = false;      
    int          expr_idx      = -1;         
 
    ConditionVar lhs_var       = ConditionVar::NODE_DEPTH;
    int          lhs_idx       = -1;         
    int          lhs_param     = 0;          
 
    CompareOp    op            = CompareOp::EQ;
 
    bool         rhs_is_variable = false;
    ConditionVar rhs_var       = ConditionVar::NODE_DEPTH;
    int          rhs_idx       = -1;
    double       rhs_value     = 0.0;
};
 
// ============================================================================
// Rule action
// ============================================================================
 
struct Action {
    int        link_idx      = -1;       
    int        rule_idx      = -1;       
    ActionType type          = ActionType::NUMERIC;
    double     value         = 0.0;      
    int        curve_idx     = -1;       
    int        tseries_idx   = -1;       
    int        pid_idx       = -1;       
};
 
// ============================================================================
// PID controller state (per action)
// ============================================================================
 
struct PIDState {
    double kp        = 0.0;
    double ki        = 0.0;   
    double kd        = 0.0;
    double setpoint  = 0.0;
    double e1        = 0.0;   
    double e2        = 0.0;   
    int    action_idx = -1;   
};
 
// ============================================================================
// Named variable (for rule expressions)
// ============================================================================
 
struct NamedVariable {
    std::string  name;
    ConditionVar var;
    int          idx = -1;
};
 
// ============================================================================
// Control rule
// ============================================================================
 
struct Rule {
    std::string          name;
    std::vector<Premise> premises;
    std::vector<Action>  then_actions;
    std::vector<Action>  else_actions;
    double               priority = 0.0;
};
 
// ============================================================================
// Control engine
// ============================================================================

struct ParseError {
    int         line = -1;   
    std::string message;     
};
 
class ControlEngine {
public:
    void init(const std::vector<Rule>& rules);

    int evaluate(SimulationContext& ctx, double current_time, double dt);
 
    // Rule parsing (from [CONTROLS] text)
    int parseRuleText(const std::string& text, SimulationContext& ctx);

    const ParseError& lastParseError() const noexcept { return last_parse_error_; }

    void clearRules();
 
    // Named variables
    void addNamedVariable(const std::string& name, ConditionVar var, int idx);
 
    // Math expressions
    int addExpression(const std::string& name, const std::string& formula);
 
    std::vector<Rule>& rules() { return rules_; }

    int lastActionCount() const { return last_action_count_; }

    void resetRuleStep() { next_rule_eval_time_ = -1.0; }
 
    // ========================================================================
    // SoA batch evaluation index (AD-14)
    // ========================================================================

    struct PremiseSoA {
        ConditionVar var_type;       
        int count = 0;
 
        // Per-premise SoA (contiguous, aligned for SIMD)
        std::vector<int>    rule_idx;     
        std::vector<int>    premise_idx;  
        std::vector<int>    obj_idx;      
        std::vector<int>    flat_idx;     
        std::vector<int>    op;           
        std::vector<double> rhs_value;    
 
        // Per-premise flags
        std::vector<bool>   rhs_is_variable; 
        std::vector<bool>   is_expression;   
 
        // Working buffer (reused each evaluate call)
        std::vector<double> lhs_values;  
        std::vector<bool>   results;     
    };

    void buildPremiseSoA();

    void batchEvaluateGroup(PremiseSoA& group,
                            const SimulationContext& ctx,
                            double current_time, double half_step);
 
private:
    int last_action_count_ = 0;     
    std::vector<Rule>        rules_;
    std::vector<PIDState>    pid_states_;
    std::vector<NamedVariable> named_vars_;
    std::vector<mathexpr::Expression> expressions_;
    std::unordered_map<std::string, int, CiHash, CiEqual> expr_index_;
    ParseError               last_parse_error_;  
 
    // SoA premise groups (one per variable type that has premises)
    std::vector<PremiseSoA>  premise_groups_;
 
    // ------------------------------------------------------------------
    // Two-phase evaluator state (§7 of CONTROL_RULES_LEGACY_PARITY_AUDIT)
    // ------------------------------------------------------------------
    // Phase 1 batch-evaluates premises (group-major) into the flat cache.
    // Phase 2 walks each rule's premises in declaration order and applies
    // legacy AND/OR semantics by reading the flat cache.
    //
    // Layout: premise_results_[ rule_premise_offset_[r] + p ] holds the
    // result of rule r's premise p.  uint8_t (not bool) so Phase 1's
    // compare loops remain SIMD-writable.
 
    std::vector<uint8_t> premise_results_;       
    std::vector<int>     rule_premise_offset_;   
    int                  total_premises_ = 0;    
 
    // Per-rule premise result tracking (for combining AND/OR)
    std::vector<bool>        rule_results_;   
 
    // TIMEOPEN/TIMECLOSED tracking: when each link's setting last changed.
    // Stored as absolute date (decimal days) matching legacy Link[j].timeLastSet.
    // Step 6 of the parity remediation will move this to ctx.links.time_last_set.
    std::vector<double> link_time_last_set_;

    double next_rule_eval_time_ = -1.0;
 
    // Tracked across a single evaluate() call
    double control_value_ = 0.0;
    double set_point_     = 0.0;
 
    // Pending action list (for priority deduplication)
    struct PendingAction {
        int        link_idx;
        double     value;
        double     priority;
        int        rule_idx;
        ActionType type = ActionType::NUMERIC;  
    };
    std::vector<PendingAction> pending_actions_;
 
    double getVariableValue(const SimulationContext& ctx,
                            ConditionVar var, int idx,
                            double current_time, int param = 0) const;
 
    bool evaluatePremise(const SimulationContext& ctx,
                         const Premise& p, double current_time, double half_step);
 
    bool compareValues(double lhs, CompareOp op, double rhs) const;
    bool compareTimes(double lhs, CompareOp op, double rhs, double half_step) const;
 
    double computePIDSetting(PIDState& pid, double control_value,
                             double current_setting, bool is_pump, double dt);
 
    void updateActionValue(Action& a, SimulationContext& ctx,
                           double current_time, double dt);

    int applyPendingActions(SimulationContext& ctx, double current_time);

    double getNamedVariableValue(const std::string& name,
                                 const SimulationContext& ctx,
                                 double current_time) const;
};
 
} // namespace controls
} // namespace openswmm
 
#endif // OPENSWMM_CONTROLS_HPP