README.md

---
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):
```python
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:

```python
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**:
   ```python
   !pip install xgboost lightgbm scipy requests
   ```

3. **Choose a data source** (see Step 1 in the notebook):
   - **Option A**: Download public datasets
     ```python
     from download_battery_datasets import download_nasa_dataset
     file_path = download_nasa_dataset('B0005')
     ```
   - **Option B**: Generate sample data
     ```python
     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
     ```python
     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**:
   ```bash
   pip install pandas numpy scikit-learn matplotlib seaborn xgboost lightgbm scipy requests
   ```

2. **Download datasets** (optional):
   ```python
   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**:
   ```bash
   python battery_soh_prediction.py
   ```
   
   **Or use Jupyter**:
   ```bash
   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.