README.md

---
language:
- en
- vi
license: mit
library_name: pytorch
tags:
- time-series
- power-systems
- forecasting
- kan
- kolmogorov-arnold-networks
- industrial-iot
- smart-grid
- energy
metrics:
- mae
- rmse
- r2
pipeline_tag: time-series-forecasting
---

# Industrial Power Load Forecasting: Residual Kolmogorov–Arnold Network (KAN)

[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue.svg)](https://github.com/neitpm/power-load-forecasting)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Zero Data Leakage](https://img.shields.io/badge/Evaluation-Zero%20Data%20Leakage-success.svg)]()

This model card releases the reproducible architecture, zero-leakage preprocessing contract, multi-seed stability benchmarks, and statistical evaluation manifests for the **Residual Kolmogorov–Arnold Network (KAN)** applied to short-term (30-minute horizon) industrial power load forecasting.

---

## 📌 Problem & Task Overview

- **Task**: Single-step ahead short-term electric power load forecasting ($\Delta t = 30\text{ minutes}$).
- **Target Variable**: Active Power $P\text{ (kW)}$ at Feeder 480, 110kV/22kV Substation 224 Tan Hung (**Tay Ninh Power Company / PC Tây Ninh**).
- **Core Architecture**: **Residual KAN Regressor** with learnable B-spline activation functions and Target Normalization ($\hat{P}_{t+1} = P_t + \text{KAN}(X)$).
- **Ensemble Methodology**: Uniform simple averaging across 5 independent random seeds (`[42, 101, 2024, 7, 999]`), guaranteeing **zero data leakage** without post-hoc test weight optimization.

---

## 📊 Evaluation & Master Benchmark

Evaluation was conducted on an out-of-sample test split consisting of **14,385 valid 30-minute samples** across **16 continuous time segments** (`2024-11-02 15:30:00` to `2025-08-30 23:30:00`).

$$\Delta\text{Metric (\%)} = \frac{\text{Metric}_{\text{Persistence}} - \text{Metric}_{\text{Model}}}{\text{Metric}_{\text{Persistence}}} \times 100\%$$

| Family | Model | MAE (kW) | RMSE (kW) | sMAPE (%) | $R^2$ Score | $\Delta\text{MAE vs Persistence}$ | $\Delta\text{RMSE vs Persistence}$ |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
| **Naive Baseline** | 1. Persistence Naive ($P_{t}$) | 598.36 | 1160.44 | **13.35%** | 0.8770 | Baseline (0.00%) | Baseline (0.00%) |
| **Naive Baseline** | 2. Seasonal Naive 24h ($\text{lag}_{48}$) | 1363.07 | 2495.50 | 30.41% | 0.4313 | -127.80% | -115.05% |
| **Naive Baseline** | 3. Seasonal Naive 7d ($\text{lag}_{336}$) | 1882.99 | 3123.69 | 42.54% | 0.1090 | -214.69% | -169.18% |
| **Naive Baseline** | 4. Moving Average (1.5h) | 1016.16 | 1586.70 | 21.74% | 0.7701 | -69.82% | -36.73% |
| **Classical ML** | 5. Ridge Regression | 730.96 | 1186.89 | 24.73% | 0.8714 | -22.16% | -2.28% |
| **Classical ML** | 6. XGBoost Regressor | 645.24 | 1155.21 | 23.30% | 0.8781 | -7.83% | +0.45% |
| **Classical ML** | 7. HistGradientBoosting Regressor | 648.01 | 1153.06 | 23.41% | 0.8786 | -8.30% | +0.64% |
| **Multi-seed Stability** | 8. Residual KAN Single (Mean $\pm$ Std)* | 528.99 $\pm$ 12.23 | 1033.35 $\pm$ 13.78 | 19.17% $\pm$ 0.32% | 0.9025 $\pm$ 0.0026 | +11.59% | +10.95% |
| **Proposed Model** | 9. **Residual KAN Ensemble (5 Seeds)\*\*** | **519.78** | **1019.95** | 18.96% | **0.9050** | **+13.13%** | **+12.11%** |

*All metrics are verified directly from `reports/master_model_comparison_benchmark.md` and `reports/moving_block_bootstrap_summary.json`.*

> **Critical Scientific Insight:**  
> While the Residual KAN Ensemble significantly reduced absolute error ($\text{MAE} -13.13\%$) and squared deviation ($\text{RMSE} -12.11\%$, $R^2 = 0.9050$), **Persistence Naive ($P_t$) remained superior in sMAPE ($13.35\%$)**. This underscores the essential role of evaluating against strong naive baselines in short-horizon time-series forecasting.

---

## 🔒 Data Privacy & Access Policy

In compliance with enterprise data governance regulations of **Tay Ninh Power Company**, the proprietary 5-year raw metering database is **not publicly hosted on Hugging Face Hub**. 
This release packages the full pipeline, feature generation contracts, model definitions, and integrity manifests. Users with their own metering CSVs can run end-to-end preprocessing using the provided CLI tools.

---

## 💻 Quickstart Inference Example

```python
import torch
import numpy as np
from code.models_kan import ResidualKANRegressor

# Initialize Residual KAN Regressor
in_features = 24  # Input lag and cyclical features
model = ResidualKANRegressor(in_features=in_features, hidden_dims=[64, 32], p_t_idx=0)
model.eval()

# Synthetic input: batch of 4 time steps
x_sample = torch.randn(4, in_features)

with torch.no_grad():
    y_pred_scaled = model(x_sample)

print("Predicted scaled load increment:", y_pred_scaled.numpy())
assert not torch.isnan(y_pred_scaled).any(), "Prediction contains NaN!"
assert not torch.isinf(y_pred_scaled).any(), "Prediction contains Inf!"
print("Smoke test passed: Clean finite predictions.")
```

---

## 📦 Verified Artifacts Manifest

All artifacts are verified with SHA-256 in [`metadata/weights_manifest.json`](metadata/weights_manifest.json).