Battery SOH & RUL Estimator (BMS)

This repository contains code, data utilities, and documentation for a hybrid battery State-of-Health (SoH) and Remaining Useful Life (RUL) estimator that combines a Square-Root Dual Unscented Kalman Filter (SR-DUKF) for robust state and parameter estimation with an LSTM-based Open-Circuit-Voltage (OCV) model.

Contents

• cleaned_dataset/ — per-discharge CSV files and metadata.csv describing EKF parameters and labels.
• scripts/ — training, inference, EKF, and validation scripts (see scripts/README.md or inline scripts docstrings).
• outputs/ — generated models, validation reports, and plots.
• docs/ and documentation/ — detailed reports, validation summaries, and quick references.

Key files

• scripts/train_dekf_lstm.py — main training pipeline that trains the OCV-LSTM model.
• scripts/infer_ukf.py — single-file inference using UKF + trained LSTM OCV model.
• scripts/ukf_soc.py — UKF implementation.
• scripts/metadata_loader.py — utilities to load per-file UKF parameters from cleaned_dataset/metadata.csv.
• outputs/eda/hybrid_lstm_model.keras — canonical trained OCV model (if present).

Quick start

1. Create a Python environment and install dependencies (see requirements.txt):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Run a short training run (example):

# train on a subset (set --max-files to limit); tune epochs/batch/seq-len as needed
python3 scripts/train_dekf_lstm.py --max-files 200 --epochs 10 --batch-size 64 --seq-len 50

3. Run inference on a single discharge file:

python3 scripts/infer_ukf.py --input-file cleaned_dataset/data/00001.csv --model outputs/eda/hybrid_lstm_model.keras

4. Run the validation workflow (example uses 100 random files):

python3 scripts/test_metadata_based_model.py --n-samples 100 --out-dir outputs/eda

Repository structure

bms/
├─ cleaned_dataset/
│  ├─ metadata.csv
│  └─ data/ (per-discharge CSVs: 00001.csv ...)
├─ scripts/
│  ├─ train_dekf_lstm.py
│  ├─ infer_ukf.py
│  ├─ ukf_soc.py
│  └─ metadata_loader.py
├─ outputs/
│  └─ eda/ (models, predictions, reports)
├─ documentation/
└─ README.md

Model & outputs

• Trained models are saved under outputs/eda/ by default (file hybrid_lstm_model.keras).
• Validation reports and per-file predictions are saved into outputs/eda/ during validation runs.

Contributing and development notes

• Use scripts/ utilities to reproduce training and validation. The code is organized for research workflows; small edits and experiments are expected.
• Tests and validation harnesses are in scripts/ and documentation/.

Or use the GitHub CLI (if installed and authenticated):

# interactive create + push
gh repo create bms-soh-estimator --public --source=. --remote=origin --push

License

• This project is released under the MIT License. See LICENSE for details.

Where to go next

• Train model to predict soh and rul based on soc and temperature.
• make an web app to take live data and predict based on that.
• Improve the model accuracy.