# PLCNG: Predictive Lyapunov-Constrained Neural Gate

Upgraded MEC offloading gate combining **Scheme 1 (LC-NeuralGate)** and **Scheme 3 (Predictive MPAC)**.

## Architecture

```
Queue History → GRU Predictor → Predicted Trajectory + Context
Current State ──────────────────────────────────────┐
                                                     ↓
                                           GateNetwork (MLP)
                                                     ↓
                                           Raw Admission Probs
                                                     ↓
                                     Lyapunov Safety Projection (QP)
                                                     ↓
                                       Final Per-Device Admission
```

## Key Innovations

1. **Joint Lyapunov Stability**: Analyzes coupled local+edge queue system
2. **Per-Device Neural Gate**: Context-aware admission probabilities (not global budget)
3. **Safety Projection Layer**: Every-step QP guarantees drift bound satisfaction
4. **GRU Queue Predictor**: Short-horizon queue trajectory prediction
5. **MPAC**: Model Predictive Admission Control with receding horizon

## Project Structure

```
code_v2/
├── configs/default.yaml          # All hyperparameters
├── src/
│   ├── env.py                    # Enhanced MEC environment
│   ├── neural_gate.py            # LC-NeuralGate + safety projection
│   ├── queue_predictor.py        # GRU predictor
│   ├── mpac.py                   # Model Predictive Admission Control
│   ├── plcng.py                  # Combined PLCNG module
│   ├── dqn.py                    # DQN agent
│   ├── ppo.py                    # PPO agent
│   ├── baselines.py              # All baseline gates
│   ├── training.py               # Training pipeline
│   └── evaluation.py             # Evaluation + statistics
├── run_experiments.py            # Full experiment suite
└── run_smoke_test.py             # Quick verification
```

## Quick Start

```bash
# Smoke test (< 1 minute)
python run_smoke_test.py

# Main comparison (20 seeds × 6 regimes × 6 gates)
python run_experiments.py --experiment main --seeds 20 --train-episodes 150

# Ablation study
python run_experiments.py --experiment ablation --seeds 10

# All experiments
python run_experiments.py --experiment all --seeds 20
```

## Experiment Suite

| # | Experiment | Purpose |
|---|-----------|---------|
| 1 | Main Comparison | PLCNG vs all baselines across (λ, C_e) grid |
| 2 | Ablation | Decompose PLCNG: full vs neural_only vs mpac_only |
| 3 | Frozen Retrofit | Apply PLCNG to pre-trained policies without retraining |
| 4 | OOD Stress | Capacity drop, traffic shift, MMPP, channel perturbation |
| 5 | Budget Sensitivity | Training episodes: 75, 150, 300, 600 |
| 6 | Scalability | Device count: 5, 10, 15, 20 |

## PLCNG Modes

| Mode | Neural Gate | Predictor | MPAC | Safety Proj |
|------|-----------|-----------|------|------------|
| `full` | ✓ | ✓ | ✓ | ✓ |
| `neural_only` | ✓ | ✗ | ✗ | ✓ |
| `mpac_only` | ✗ | ✓ | ✓ | ✗ |
| `predictor_gate` | ✓ | ✓ | ✗ | ✓ |
