# 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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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:

```json
{
  "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:

```sql
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:

```sql
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:
```json
{
  "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