This repository consolidates exploratory data analyses, physics-informed models, and digital-twin workflows that characterize lithium-ion battery degradation. Each subdirectory encapsulates a focused research thread—from curated public datasets through knee-point diagnostics and mechanistic PyBaMM simulations to neural-network baselines—so experiments remain reproducible and academically traceable.
| Folder | Description |
|---|---|
00_open_data_exploration/ |
Curate, harmonise, and visualise public battery datasets (BatteryArchive, Severson/MIT, NASA PCoE, CALCE, Oxford) |
01_knee_point_detection/ |
Reproducible knee-point and knee-onset detection with Bacon-Watts, Kneedle, curvature, and piecewise linear modelling |
02_pybamm_simulation/ |
Physics-based cycling and aging simulations with PyBaMM to surface SEI and knee-point dynamics |
03_beep_demonstration/ |
BEEP (Battery Evaluation and Early Prediction) pipeline demonstration with standardised preprocessing and feature extraction |
04_neural_network_baselines/ |
Neural-network baselines comparing physics-guided and empirical capacity forecasting |
# Clone
git clone https://github.com/EigenJames/LiB-DigitalTwin.git
cd LiB-DigitalTwin
# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS/Linux
# Install core dependencies
pip install -r requirements.txtThis repository is organized to support academically traceable battery-degradation studies. The workflow separates data curation, knee-point diagnostics, mechanistic simulation, standardized feature extraction, and neural baselines so each layer can be evaluated independently and then connected in a digital-twin pipeline.
Primary contributions
- Curated, harmonized public datasets for cross-study comparability.
- Reproducible knee-point detection benchmarks across heterogeneous data sources.
- Mechanistic PyBaMM simulations to interpret nonlinear degradation regimes.
- BEEP preprocessing and feature extraction for early-life prediction baselines.
- Neural network baselines that contrast empirical and physics-guided priors.
- Open data exploration — Run data ingestion and harmonisation to generate consistent pickles for downstream analyses.
- Knee-point detection — Apply multiple detection paradigms across curated datasets and compare results.
- PyBaMM simulations — Test mechanistic hypotheses for knee onset under controlled protocols.
- BEEP pipeline — Standardise cycler data and extract early-life features.
- Neural baselines — Benchmark data-driven vs physics-guided capacity forecasting models.
Some notebooks require additional packages not listed in the core requirements.txt:
pip install pybamm beep tensorflow keras-tuner plotly- Notebooks are designed to run with repository-local datasets. When downloads are required, the notebooks document the source and expected file placement.
- To reproduce published figures, record package versions and the exact notebook execution order.
- Neural baselines are computationally intensive; run them separately from the data-processing notebooks.
| Source | Reference |
|---|---|
| Severson/MIT | Severson et al., Nature Energy (2019) — 124 cells, fast-charging protocols |
| NASA PCoE | Li-ion 18650 cells cycled at 24 °C & 43 °C |
| BatteryArchive.org | Multi-institution battery aging data |
| CALCE (U. Maryland) | LFP & NMC chemistry comparisons |
| Oxford | High-quality impedance spectroscopy data |
- Severson, K. A. et al. "Data-driven prediction of battery cycle life before capacity degradation." Nature Energy 4, 383–391 (2019).
- Fermín-Cueto, P. et al. "Identification and machine learning prediction of knee-point and knee-onset in capacity degradation curves of lithium-ion cells." Energy and AI 1, 100006 (2020).
- O'Kane, S. E. J. et al. "Lithium-ion battery degradation: how to model it." Phys. Chem. Chem. Phys. 24, 7909 (2022).
If you use this repository in academic work, please cite the relevant dataset papers above and reference this repository at:
LiB-DigitalTwin. https://github.com/EigenJames/LiB-DigitalTwin
MIT