README.md

metadata

title: ZenVolt AI Trust Engine
emoji: 🔋
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false

Battery State of Health (SOH) Prediction - Advanced ML Models

Overview

This project implements an advanced machine learning pipeline for predicting Battery State of Health (SOH) using multiple models (Random Forest, XGBoost, LightGBM) with hyperparameter tuning, uncertainty quantification, and End-of-Life (EOL) prediction.

SOH Definition: current_capacity / initial_capacity

Features

1. Data Cleaning & Preprocessing

• Missing value handling (forward fill, backward fill, median imputation)
• Outlier detection and capping using IQR method
• Duplicate removal

2. Advanced Feature Engineering

• Statistical Features: Mean, std, min, max, range, median per cycle for voltage, current, temperature
• Rolling Features: 5-cycle rolling averages and standard deviations
• Temporal Features: Cycles from start, cycles to end (supports timestamp data if available)
• Physics-Informed Features:
  • Energy throughput per cycle
  • Charge/discharge asymmetry
  • Power (voltage × current)
  • Temperature stress indicators
  • Capacity fade rate and acceleration
• Degradation Features: Capacity degradation rates, cumulative capacity loss

3. Multiple ML Models with Hyperparameter Tuning

• Random Forest: Grid search over n_estimators, max_depth, min_samples_split, min_samples_leaf
• XGBoost: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree
• LightGBM: Grid search over n_estimators, max_depth, learning_rate, subsample, colsample_bytree, num_leaves

4. Uncertainty Quantification

• Prediction intervals (95% confidence) using Random Forest tree predictions
• Standard deviation of predictions across trees

5. Early Stopping Detection (EOL Prediction)

• Predicts when battery reaches 80% SOH (industry standard End-of-Life)
• Remaining Useful Life (RUL) prediction for each cycle
• Linear extrapolation from recent predictions

6. Model Evaluation

• R² Score, MAE, RMSE
• 5-fold cross-validation
• Model comparison table with R² improvements

7. Visualizations

• Model comparison: Predicted vs Actual SOH
• SOH vs Cycle Index (with uncertainty bands)
• Feature importance plots
• Residuals analysis
• EOL prediction visualization
• RUL prediction plots

Dataset Requirements

Expected CSV Format

Columns required:

• cycle_index: Cycle number
• voltage: Battery voltage (V)
• current: Battery current (A, positive for charge, negative for discharge)
• temperature: Battery temperature (°C)
• capacity: Battery capacity (Ah)

Optional columns (for enhanced temporal features):

• timestamp or date: Timestamp for each measurement

Sample Data Format

cycle_index,voltage,current,temperature,capacity
1,4.2,1.5,25.0,2.0
1,4.1,1.5,25.1,2.0
...
2,4.2,1.5,25.0,1.98
...

Public Battery Datasets

NASA PCoE Battery Datasets

Official Source:

• NASA Open Data Portal: https://data.nasa.gov/dataset/Li-ion-Battery-Aging-Datasets/uj5r-zjdb/data
• Datasets: B0005, B0006, B0007, B0018 (run-to-failure cycling data)
• Format: .mat files (MATLAB format)

CSV Conversions:

• GitHub: bnarms/NASA-Battery-Dataset - Contains original .mat files and conversion scripts
• GitHub: RyuMyunggi/NASA-battery-dataset-eda - EDA and CSV conversion examples
• GitHub: huzaifi18/RUL_prediction - Pre-processed CSV files

Conversion Script (if using .mat files):

import scipy.io
import pandas as pd

mat_data = scipy.io.loadmat('B0005.mat')
# Extract data and convert to CSV format
# Refer to NASA dataset documentation for structure

CALCE Battery Datasets

Official Sources:

• Main page: https://calce.umd.edu/battery-data
• Data index: https://calce.umd.edu/data
• Format: Text/CSV files per experiment

Direct Access:

• University of Michigan IoFT mirror: https://ioft-data.engin.umich.edu/calce-battery-datasets/
• Provides CSV-ready cycling data

Stanford Battery Datasets

Sources:

• BEEP Project: https://tri-amdd.github.io/beep/ (includes Stanford aging datasets)
• GitHub: petermattia/revisit-severson-et-al - Conversion scripts
• Format: MATLAB/HDF5 (with CSV export tools)

Access:

1. Download from BEEP project
2. Use BEEP tools to export to CSV
3. Or use conversion scripts from the GitHub repo

Usage

Quick Start (Sample Data)

For testing, you can generate sample data:

from download_battery_datasets import create_sample_battery_data
file_path = create_sample_battery_data('./data/sample_battery_data.csv', n_cycles=100)

Google Colab

1. Upload both files to Google Colab:

   • battery_soh_prediction.ipynb (notebook)
   • download_battery_datasets.py (dataset downloader)

2. Install dependencies:

   !pip install xgboost lightgbm scipy requests
   

3. Choose a data source (see Step 1 in the notebook):

   • Option A: Download public datasets

     from download_battery_datasets import download_nasa_dataset
     file_path = download_nasa_dataset('B0005')
     

   • Option B: Generate sample data

     from download_battery_datasets import create_sample_battery_data
     file_path = create_sample_battery_data('./data/sample_battery_data.csv')
     

   • Option C: Upload your CSV file

     from google.colab import files
     uploaded = files.upload()
     file_path = list(uploaded.keys())[0]
     

4. Run all cells in the notebook

Local Python Environment

1. Install dependencies:

   pip install pandas numpy scikit-learn matplotlib seaborn xgboost lightgbm scipy requests
   

2. Download datasets (optional):

   from download_battery_datasets import download_nasa_dataset, create_sample_battery_data
   
   # Download NASA dataset
   file_path = download_nasa_dataset('B0005')
   
   # Or create sample data
   file_path = create_sample_battery_data('./data/sample_battery_data.csv')
   

3. Run the Python script:

   python battery_soh_prediction.py
   

   Or use Jupyter:

   jupyter notebook battery_soh_prediction.ipynb
   

Output

The pipeline generates:

1. Model Comparison Table: R², MAE, RMSE for all models
2. Best Model Selection: Automatically selects model with highest Test R²
3. Prediction Intervals: 95% confidence intervals (Random Forest)
4. EOL Prediction: Cycle when battery reaches 80% SOH
5. Visualizations: 6 comprehensive plots saved as battery_soh_prediction_results.png

Model Comparison

The code automatically compares:

• Random Forest (baseline)
• XGBoost (if available)
• LightGBM (if available)

Results include:

• Train R², Test R²
• Cross-validation R² (mean ± std)
• Test MAE, Test RMSE
• R² Improvement over baseline

Notes

• Time Series Splitting: The 80/20 train-test split is done without shuffling to preserve time series order
• Cross-Validation: 5-fold CV is used for model evaluation
• Hyperparameter Tuning: Uses GridSearchCV with 3-fold CV
• Feature Engineering: All features are created at the cycle level (aggregated per cycle)
• Uncertainty: Currently implemented for Random Forest only (using tree variance)
• EOL Threshold: Set to 80% SOH (industry standard), can be modified in code

Troubleshooting

XGBoost/LightGBM Not Available

• Install: pip install xgboost lightgbm
• The code will automatically skip unavailable models

Missing Columns Error

• Ensure your CSV has at least: cycle_index, voltage, current, temperature, capacity
• Column names are case-sensitive

Out of Memory

• Reduce hyperparameter grid search space
• Use smaller dataset or sample data
• Reduce number of estimators in models

Citation

If using public datasets, please cite the original sources:

• NASA: "Li-ion Battery Aging Datasets" - NASA Prognostics Center of Excellence
• CALCE: University of Maryland Center for Advanced Life Cycle Engineering
• Stanford: Severson et al. cycle-life prediction datasets

License

This code is provided as-is for research and educational purposes.