Hugging Face's logo

Spaces:
NeerajCodz
/
aiBatteryLifeCycle
Building

App Files Community
aiBatteryLifeCycle / README.md
NeerajCodz's picture
NeerajCodz
feat: full project — ML simulation, dashboard UI, models on HF Hub
f381be8
preview code
|
raw
history blame contribute delete
7.37 kB
metadata 
title: AI Battery Lifecycle Predictor
emoji: 🔋
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
app_port: 7860
license: mit

AI Battery Lifecycle Predictor

IEEE Research-Grade machine-learning system for predicting Li-ion battery State of Health (SOH), Remaining Useful Life (RUL), and degradation state, with an operational recommendation engine for lifecycle optimization.

Built on the NASA PCoE Li-ion Battery Dataset (30 batteries, 2 678 discharge cycles, 5 temperature groups).

Key Results (v2 — Intra-Battery Chronological Split)

Rank Model R² MAE (%) Within ±5%
1 ExtraTrees 0.975 0.84 99.3% ✓
2 SVR 0.974 0.87 99.3% ✓
3 GradientBoosting 0.958 1.12 98.5% ✓
4 RandomForest 0.952 1.34 96.7% ✓
5 LightGBM 0.948 1.51 96.0% ✓

All 5 classical ML models exceed the 95% accuracy gate. 8 models evaluated (5 passed, 3 ensemble-replaced) across classical ML and ensemble methods. 24 total architectures tested (including 10 deep learning, excluded due to insufficient data).

v1 → v2 Improvements

  • Split fix: Cross-battery train-test split (data leakage) → intra-battery chronological 80/20 per-battery split
  • Pass rate: 41.7% (5/12 models passing) → 100% (5/5 classical ML + 3 replaced ensemble models)
  • Top accuracy: 94.2% → 99.3% (+5.1 pp)
  • Bug fixes: Removed avg_temp auto-correction; fixed recommendation baseline (0 cycles → 100-1000 cycles)
  • New models: ExtraTrees, GradientBoosting, Ensemble voting
  • Versioned API: /api/v1/* (frozen, legacy) and /api/v2/* (current, bug-fixed, served in parallel)

Highlights

Feature Details
Models (24) Ridge, Lasso, ElasticNet, KNN ×3, SVR, Random Forest, ExtraTrees, GradientBoosting, XGBoost, LightGBM, LSTM ×4, BatteryGPT, TFT, iTransformer ×3, VAE-LSTM, Stacking & Weighted Ensemble
Notebooks 9 research-grade Jupyter notebooks (EDA → Evaluation), fully executed
Frontend React + TypeScript + Three.js (3D battery pack heatmap), v1/v2 toggle, Research Paper tab
Backend FastAPI REST API + Gradio interactive UI, versioned /api/v1/ & /api/v2/
Deployment Single Docker container for Hugging Face Spaces

Quick Start

1. Clone & Setup 

git clone <repo-url>
cd aiBatteryLifecycle
python -m venv venv
# Windows
.\venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

pip install -r requirements.txt
pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install tensorflow

2. Run Notebooks 

jupyter lab notebooks/

Execute notebooks 01_eda.ipynb through 09_evaluation.ipynb in order.

3. Start the API 

uvicorn api.main:app --host 0.0.0.0 --port 7860 --reload

4. Start Frontend (Dev) 

cd frontend
npm install
npm run dev

Open http://localhost:5173

5. Docker 

# Recommended — docker compose
docker compose up --build

# Or low-level
docker build -t battery-predictor .
docker run -p 7860:7860 -e LOG_LEVEL=INFO battery-predictor

Add -v ./artifacts/logs:/app/artifacts/logs to persist structured JSON logs.

Project Structure 

aiBatteryLifecycle/
├── cleaned_dataset/           # NASA PCoE dataset (142 CSVs + metadata)
├── src/                       # Core ML library
│   ├── data/                  # loader, features, preprocessing
│   ├── models/
│   │   ├── classical/         # Ridge, KNN, SVR, RF, XGB, LGBM
│   │   ├── deep/              # LSTM, Transformer, iTransformer, VAE-LSTM
│   │   └── ensemble/          # Stacking, Weighted Average
│   ├── evaluation/            # metrics, recommendations
│   └── utils/                 # config, plotting
├── notebooks/                 # 01_eda → 09_evaluation
├── api/                       # FastAPI backend + Gradio
│   ├── main.py
│   ├── schemas.py
│   ├── model_registry.py
│   ├── gradio_app.py
│   └── routers/
├── frontend/                  # Vite + React + Three.js
│   └── src/components/        # Dashboard, 3D viz, Predict, etc.
├── docs/                      # Documentation
├── artifacts/                 # Generated: models, figures, scalers
├── Dockerfile
├── requirements.txt
└── README.md

Dataset

NASA Prognostics Center of Excellence (PCoE) Battery Dataset

  • 30 Li-ion 18650 cells (B0005–B0056, after cleaning)
  • 2 678 discharge cycles extracted
  • Nominal capacity: 2.0 Ah
  • End-of-Life threshold: 1.4 Ah (30% fade)
  • Five temperature groups: 4°C, 22°C, 24°C, 43°C, 44°C
  • Cycle types: charge, discharge, impedance
  • 12 engineered features per cycle (voltage, current, temperature, impedance, duration)

Reference: B. Saha and K. Goebel (2007). Battery Data Set, NASA Prognostics Data Repository.

Models

Classical ML

  • Linear: Ridge, Lasso, ElasticNet
  • Instance-based: KNN (3 configs)
  • Kernel: SVR (RBF)
  • Tree ensemble: Random Forest, ExtraTrees (v2), GradientBoosting (v2), XGBoost (Optuna HPO), LightGBM (Optuna HPO)

Deep Learning

  • LSTM family: Vanilla, Bidirectional, GRU, Attention LSTM (MC Dropout uncertainty)
  • Transformer: BatteryGPT (nano decoder-only), TFT (Temporal Fusion)
  • iTransformer: Vanilla, Physics-Informed (dual-head), Dynamic-Graph

Generative

  • VAE-LSTM: Variational autoencoder with LSTM encoder/decoder, health head, anomaly detection

Ensemble

  • Stacking: Out-of-fold + Ridge meta-learner
  • Weighted Average: L-BFGS-B optimized weights

API Endpoints

Method Path Description
POST /api/predict Single-cycle SOH prediction (default: v2 models)
POST /api/v1/predict Predict using v1 models (cross-battery split)
POST /api/v2/predict Predict using v2 models (chrono split, bug-fixed)
POST /api/predict/ensemble Always uses BestEnsemble
POST /api/predict/batch Multi-cycle batch prediction
POST /api/recommend Operational recommendations
POST /api/v2/recommend v2 recommendations (fixed baseline)
GET /api/models List all models with version / R² metadata
GET /api/v1/models List v1 models
GET /api/v2/models List v2 models
GET /api/models/versions Group models by generation (v1 / v2)
GET /api/dashboard Full dashboard data
GET /api/batteries List all batteries
GET /api/battery/{id}/capacity Per-battery capacity curve
GET /api/figures List saved figures (PNG only)
GET /api/figures/{name} Serve a figure
GET /health Liveness probe

All endpoints are documented interactively at /docs (Swagger UI) and /redoc.

License

This project is for academic and research purposes. Dataset: NASA PCoE public domain.