CalejoControl/docs/PUMP_CONTROL_LOGIC_CONFIGURATION.md

Pump Control Logic Configuration

Overview

The Calejo Control system now supports three configurable pump control logics for converting MPC outputs to pump actuation signals. These logics can be configured per pump through protocol mappings or pump configuration.

Available Control Logics

1. MPC-Driven Adaptive Hysteresis (Primary)

Use Case: Normal operation with MPC + live level data

Logic:

• Converts MPC output to level thresholds for start/stop control
• Uses current pump state to minimize switching
• Adaptive buffer size based on expected level change rate

Configuration Parameters:

{
  "control_logic": "mpc_adaptive_hysteresis",
  "control_params": {
    "safety_min_level": 0.5,
    "safety_max_level": 9.5,
    "adaptive_buffer": 0.5,
    "min_switch_interval": 300
  }
}

2. State-Preserving MPC (Enhanced)

Use Case: When pump wear/energy costs are primary concern

Logic:

• Explicitly minimizes pump state changes by considering switching penalties
• Calculates benefit vs. penalty for state changes
• Maintains current state when penalty exceeds benefit

Configuration Parameters:

{
  "control_logic": "state_preserving_mpc",
  "control_params": {
    "activation_threshold": 10.0,
    "deactivation_threshold": 5.0,
    "min_switch_interval": 300,
    "state_change_penalty_weight": 2.0
  }
}

3. Backup Fixed-Band Control (Fallback)

Use Case: Backup when level sensor fails

Logic:

• Uses fixed level bands based on pump station height
• Three operation modes: "mostly_on", "mostly_off", "balanced"
• Always active safety overrides

Configuration Parameters:

{
  "control_logic": "backup_fixed_band",
  "control_params": {
    "pump_station_height": 10.0,
    "operation_mode": "balanced",
    "absolute_max": 9.5,
    "absolute_min": 0.5
  }
}

Configuration Methods

Method 1: Protocol Mapping Preprocessing

Configure through protocol mappings in the dashboard:

{
  "preprocessing_enabled": true,
  "preprocessing_rules": [
    {
      "type": "pump_control_logic",
      "parameters": {
        "logic_type": "mpc_adaptive_hysteresis",
        "control_params": {
          "safety_min_level": 0.5,
          "adaptive_buffer": 0.5
        }
      }
    }
  ]
}

Method 2: Pump Configuration

Configure directly in pump metadata:

UPDATE pumps 
SET control_parameters = '{
  "control_logic": "mpc_adaptive_hysteresis",
  "control_params": {
    "safety_min_level": 0.5,
    "adaptive_buffer": 0.5
  }
}' 
WHERE station_id = 'station1' AND pump_id = 'pump1';

Method 3: Control Type Selection

Set the pump's control type to use the preprocessor:

UPDATE pumps 
SET control_type = 'PUMP_CONTROL_PREPROCESSOR'
WHERE station_id = 'station1' AND pump_id = 'pump1';

Integration Points

Setpoint Manager Integration

The pump control preprocessor integrates with the existing Setpoint Manager:

1. MPC outputs are read from the database (pump_plans table)
2. Current state is obtained from pump feedback
3. Control logic is applied based on configuration
4. Actuation signals are sent via protocol mappings

Safety Integration

All control logics include safety overrides:

• Emergency stop conditions
• Absolute level limits
• Minimum switch intervals
• Equipment protection

Monitoring and Logging

Each control decision is logged with:

• Control logic used
• MPC input value
• Resulting pump command
• Reason for decision
• Safety overrides applied

Example log entry:

{
  "event": "pump_control_decision",
  "station_id": "station1",
  "pump_id": "pump1",
  "mpc_output": 45.2,
  "control_logic": "mpc_adaptive_hysteresis",
  "result_reason": "set_activation_threshold",
  "pump_command": false,
  "max_threshold": 2.5
}

Testing and Validation

Test Scenarios

1. Normal Operation: MPC outputs with live level data
2. Sensor Failure: No level signal available
3. State Preservation: Verify minimal switching
4. Safety Overrides: Test emergency conditions

Validation Metrics

• Pump state change frequency
• Level control accuracy
• Safety limit compliance
• Energy efficiency

Migration Guide

From Legacy Control

1. Identify pumps using level-based control
2. Configure appropriate control logic
3. Update protocol mappings if needed
4. Monitor performance and adjust parameters

Adding New Pumps

1. Set control_type to 'PUMP_CONTROL_PREPROCESSOR'
2. Configure control_parameters JSON
3. Set up protocol mappings
4. Test with sample MPC outputs