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;
class SWMMEngine;
 
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;
    int rhs_param = 0; 
    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;
    int param = 0;
};
 
// ============================================================================
// 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; 
    int code = 0;        
    std::string token;   
};

class ControlEngine {
public:
    void init(const std::vector<Rule>& rules);

    int evaluate(SimulationContext& ctx, double current_date, double dt,
                 bool rule_time_reached = true);
 
    // 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, int param = 0);
 
    // 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_; }
 
    // ========================================================================
    // 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> param;        
        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:
    friend class openswmm::SWMMEngine;
    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_;
 
    // Tracked across a single evaluate() call
    double control_value_ = 0.0;
    double set_point_ = 0.0;
    double eval_date_ = 0.0;
    double cur_date_ = 0.0;
    double cur_time_ = 0.0;
    double elapsed_days_ = 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_;
    std::vector<int> action_slots_;

    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