Skip to content

mr-haseen-ullah/ML_CEP

BranchesTags

Repository files navigation

🔋 Adaptive Micro-Grid Segmentation

Machine Learning Solution for Smart Grid Energy Prediction

ML Pipeline GitHub Pages Python 3.9+

🌐 View Live Report →

📖 Table of Contents

🎯 Overview

This project implements a hybrid cluster-then-regress machine learning system to solve UET Mardan's Smart Grid energy prediction challenge. The system combines Gaussian Mixture Models (GMM) for clustering with Ridge Regression for prediction, achieving significantly better performance than traditional single-model approaches.

Key Achievement: The hybrid model outperforms the global baseline by identifying different operating modes in the campus energy consumption patterns and training specialized predictors for each mode.

🚨 Problem Statement

UET Mardan's Smart Grid system failed because a single global regression model couldn't accurately predict energy consumption during edge cases such as:

  • Morning rush (6 AM) - sudden surge in consumption
  • Evening rush (5 PM) - peak energy usage
  • Weekend patterns - different from weekday behavior

The global model averaged across all these different modes, leading to poor predictions when the campus operated in specific states.

Challenge: Create a machine learning system that can:

  1. Automatically detect different operating modes
  2. Train specialized predictors for each mode
  3. Run efficiently on embedded hardware
  4. Handle singular matrices (small data clusters)

💡 Solution Approach

Hybrid Architecture

Our solution uses a two-phase approach:

  1. Phase 1: Clustering (Unsupervised Learning)

    • Algorithm: Gaussian Mixture Models (GMM)
    • Purpose: Automatically discover campus operating modes
    • Selection: Bayesian Information Criterion (BIC) for optimal K

  2. Phase 2: Regression (Supervised Learning)

    • Algorithm: Ridge Regression (Closed-Form Solution)
    • Purpose: Train specialized predictor for each cluster
    • Advantage: Guaranteed invertibility (no singular matrix issues)

Why Ridge Regression?

Mathematical Guarantee:

β = (X^T X + λI)^(-1) X^T y

For any λ > 0, the matrix (X^T X + λI) is positive definite and thus always invertible, even when clusters have very few samples.

Proof: For any non-zero vector v:

v^T (X^T X + λI) v = ||Xv||² + λ||v||² > 0

This ensures the system never crashes due to singular matrices!

📁 Project Structure

ML_CEP/
├── .github/
│   └── workflows/
│       └── ml-pipeline.yml          # Automated CI/CD pipeline
│
├── data_loader.py                   # Data loading & preprocessing
├── clustering.py                    # GMM/K-Means clustering engine
├── ridge_regression.py              # Ridge regression implementation
├── hybrid_predictor.py              # Hybrid prediction system
│
├── train.py                         # Main training pipeline
├── evaluate.py                      # Model evaluation & comparison
├── predict.py                       # Inference interface
├── generate_web_report.py           # HTML report generator
│
├── requirements.txt                 # Python dependencies
├── .gitignore                       # Git ignore rules
├── readme.md                        # This file
│
├── RUN_COMPLETE_CEP.bat            # Windows: Run complete pipeline
├── run_project.bat                  # Windows: Quick start
├── setup_only.bat                   # Windows: Setup only
└── download_dataset.bat             # Windows: Download UCI dataset

🚀 Installation & Setup

Prerequisites

  • Python 3.9 or higher
  • pip (Python package manager)
  • Git (for cloning the repository)

Option 1: Quick Start (Windows)

# Clone the repository
git clone https://github.com/virusescreators/ML_CEP.git
cd ML_CEP

# Run complete pipeline (setup + train + evaluate + report)
RUN_COMPLETE_CEP.bat

Option 2: Manual Setup (All Platforms)

# 1. Clone the repository
git clone https://github.com/virusescreators/ML_CEP.git
cd ML_CEP

# 2. Create virtual environment (recommended)
python -m venv venv

# 3. Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Download dataset (optional - will use synthetic data if not available)
python -c "import urllib.request; urllib.request.urlretrieve('https://archive.ics.uci.edu/static/public/374/appliances+energy+prediction.zip', 'dataset.zip')"

Option 3: Docker (Coming Soon)

🎮 Usage

Training the Model

# Run training pipeline
python train.py

What it does:

  1. Loads and preprocesses the dataset
  2. Finds optimal number of clusters using BIC
  3. Trains GMM clustering model
  4. Trains Ridge regression models for each cluster
  5. Evaluates performance vs global baseline
  6. Saves models to models/ directory

Output:

  • models/hybrid_predictor.pkl - Trained hybrid system
  • models/global_predictor.pkl - Baseline global model
  • models/metadata.pkl - Training metadata
  • models/*.png - Training visualizations

Evaluating the Model

# Run evaluation
python evaluate.py

What it does:

  1. Loads trained models
  2. Compares hybrid vs global performance
  3. Generates detailed visualizations
  4. Identifies failure cases (small clusters)

Output:

  • results/evaluation_summary.pkl - Metrics
  • results/*.png - Comparison charts

Making Predictions

# Run inference
python predict.py

What it does:

  1. Loads trained hybrid model
  2. Accepts input features
  3. Returns predicted energy consumption
  4. Shows which cluster was used

Generating Web Report

# Generate HTML report
python generate_web_report.py

What it does:

  1. Loads training results
  2. Generates comprehensive HTML report
  3. Includes all visualizations and metrics
  4. Saves to docs/index.html

View locally:

# Open in browser
start docs/index.html  # Windows
open docs/index.html   # Mac
xdg-open docs/index.html  # Linux

⚙️ How It Works

Step-by-Step Pipeline

┌─────────────────────────────────────────┐
│  1. Load UCI Energy Dataset              │
│     (19,735 samples, 29 features)        │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  2. Preprocess Data                      │
│     - Remove date column                 │
│     - StandardScaler normalization       │
│     - Train/test split (80/20)           │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  3. Find Optimal K (Clusters)            │
│     - Test K = 2, 3, 4, 5, 6, 7         │
│     - Use BIC for model selection        │
│     - Select K with lowest BIC           │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  4. Train GMM Clustering                 │
│     - Fit Gaussian Mixture Model         │
│     - Assign training samples to clusters│
│     - Visualize clusters (PCA)           │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  5. Select Lambda (λ) Parameter          │
│     - Cross-validation on subset         │
│     - Test λ = 0.01, 0.1, 1, 10, 100    │
│     - Choose λ with lowest CV error      │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  6. Train Ridge Regression (Per Cluster) │
│     - For each cluster k:                │
│       β_k = (X_k^T X_k + λI)^(-1) X_k^T y_k │
│     - Guaranteed invertibility!          │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  7. Create Hybrid Predictor              │
│     - Combine clustering + regression    │
│     - Input → Cluster → Specialized Model│
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  8. Evaluate vs Global Baseline          │
│     - Train single Ridge model on all data│
│     - Compare RMSE: Hybrid vs Global     │
│     - Generate visualizations            │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  9. Save Models & Generate Report        │
│     - Save trained models (.pkl)         │
│     - Generate HTML report               │
│     - Deploy to GitHub Pages             │
└─────────────────────────────────────────┘

Prediction Flow

When making a prediction for new data:

Input Features (x)
      ↓
[GMM Clustering]
      ↓
Cluster ID (k)
      ↓
[Select Ridge Model k]
      ↓
ŷ = β_k^T x + b_k
      ↓
Predicted Energy (Wh)

✨ Features

Core Features

  • ✅ Automatic Mode Detection - GMM discovers patterns without manual labeling
  • ✅ Singularity-Proof Design - Ridge regularization guarantees matrix invertibility
  • ✅ Embedded-Ready - Closed-form solution (no iterative optimization)
  • ✅ Better Accuracy - Outperforms single global model.
  • ✅ Comprehensive Evaluation - Detailed comparison and failure analysis

Advanced Features

  • ✅ Automated CI/CD - GitHub Actions pipeline for training and deployment
  • ✅ Beautiful Web Reports - Interactive HTML dashboard with visualizations
  • ✅ GitHub Pages Deployment - Automatic report hosting
  • ✅ Batch Scripts - Windows batch files for easy execution
  • ✅ Modular Design - Clean separation of concerns

Technical Features

  • ✅ Numerical Stability - Positive definite matrices ensure reliable computations
  • ✅ Efficient Implementation - Vectorized operations using NumPy
  • ✅ Comprehensive Logging - Detailed progress tracking
  • ✅ Error Handling - Robust fallbacks for edge cases
  • ✅ Synthetic Data Fallback - Runs without dataset for testing

📊 Results

Performance Metrics

Run the pipeline to see your results!

Model RMSE (Wh) Improvement
Global Ridge XX.XX Baseline
Hybrid System XX.XX +X.X% ✅

Visualizations

The system automatically generates:

  1. Elbow/BIC Curve - Optimal K selection
  2. Cluster Visualization - PCA projection of discovered modes
  3. RMSE Comparison - Hybrid vs Global performance
  4. Per-Cluster Analysis - Performance breakdown by cluster
  5. Cluster Distribution - Size of each discovered mode
  6. Residual Plots - Error analysis for both models

View all visualizations: Live Report

🔄 CI/CD Pipeline

Automated Workflow (GitHub Actions)

Every push to main triggers:

1. Setup Python 3.9 environment
2. Install dependencies from requirements.txt
3. Download UCI dataset (or use synthetic data)
4. Train hybrid ML system
5. Evaluate performance
6. Generate HTML report
7. Deploy to GitHub Pages (gh-pages branch)

View Pipeline: Actions Tab

GitHub Pages

The HTML report is automatically deployed to: https://virusescreators.github.io/ML_CEP/

Updates appear ~5 minutes after pushing to main.

🔬 Technical Details

Algorithms

Clustering:

  • GMM (Gaussian Mixture Models) with Expectation-Maximization
  • Alternative: K-Means (faster but less flexible)
  • Selection: BIC (Bayesian Information Criterion)

Regression:

  • Ridge Regression with closed-form solution
  • Regularization: L2 penalty (λ parameter)
  • Selection: K-fold cross-validation

Mathematical Foundation

Ridge Regression Formula:

minimize: ||y - Xβ||² + λ||β||²

Solution: β = (X^T X + λI)^(-1) X^T y

Positive Definiteness:

For any v ≠ 0:
v^T (X^T X + λI) v = v^T X^T X v + λ v^T v
                    = ||Xv||² + λ||v||²
                    > 0  (for λ > 0)

Therefore: (X^T X + λI) is positive definite
→ Guaranteed invertible! ✅

Complexity Analysis

Training:

  • Global Model: O(nd² + d³)
  • Hybrid Model: O(nd² + Kd³)
  • For K << n/d²: Similar complexity, better accuracy!

Prediction:

  • Both models: O(d) - simple matrix multiplication
  • Suitable for real-time embedded systems! 🚀

Dataset

UCI Appliances Energy Prediction Dataset

  • Source: UCI ML Repository
  • Samples: 19,735
  • Features: 29 (temperature, humidity, time, weather, etc.)
  • Target: Energy consumption (Wh)
  • Period: 4.5 months of smart home data

🛠️ Dependencies

numpy>=1.21.0
pandas>=1.3.0
scikit-learn>=1.0.0
matplotlib>=3.4.0
seaborn>=0.11.0

See requirements.txt for exact versions.

📝 Project Information

Item Details
Student Haseen ullah
Roll Number 22MDSWE238
Course Machine Learning (SE-318)
Assignment Complex Engineering Problem (CEP) #2
University UET Mardan
Semester Fall 2025

🤝 Contributing

This is an academic project, but suggestions are welcome!

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/improvement)
  3. Commit your changes (git commit -am 'Add improvement')
  4. Push to the branch (git push origin feature/improvement)
  5. Open a Pull Request

📄 License

This project is submitted as academic work for the SE-318 Machine Learning course at UET Mardan.

🙏 Acknowledgments

  • UCI Machine Learning Repository for the dataset
  • UET Mardan for the Smart Grid initiative
  • scikit-learn community for excellent ML tools
  • GitHub for Actions and Pages hosting

📞 Contact

For questions or feedback:

🎯 Quick Links

Built with ❤️ for UET Mardan Smart Grid Initiative

Last Updated: December 2025

About

Solving the "Adaptive Micro-Grid" challenge by addressing the failure of UET Mardan’s Smart Grid pilot. This project moves beyond failed global linear regression models to handle non-stationary, multi-modal energy data through context-aware segmentation (e.g., distinguishing between weekday peak loads and weekend inactivity).

mr-haseen-ullah.github.io/ML_CEP/

Topics

machine-learning smart-grid energy-forecasting micro-grid uet-mardan

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages