A command-line tool and Python library that measures how lithium-ion cells wear out, from real laboratory cycling data: capacity fade, state of health, resistance growth, the ageing knee, the degradation mode behind the loss, and what the spread between cells does to the life of a pack built from them.
It is built around the Oxford Battery Degradation Dataset 1: eight 740 mAh pouch cells aged at 40 C with the ARTEMIS urban drive cycle, characterised every 100 cycles for two years. That is an electric vehicle duty cycle, not a laboratory square wave.
Eight cells, one batch, one test bench. A series pack is empty when its first cell is
empty, so the lower edge of the band is the pack: cell-to-cell spread alone costs this pack
1050 drive cycles, about 19 % of its life. Generated with cellage plot fleet.
- How much capacity is left, and how fast is it going?
- Is the cell just losing capacity, or is it also losing the ability to deliver current?
- Why is it fading -- lost lithium, or lost active material?
- When does fade stop being a straight line and accelerate (the knee)?
- What does the worst cell in a batch do to the life of the pack?
Measured by this tool from the 519 characterisations in the dataset:
| Cell | Cycles | Capacity new | Capacity end | SOH | Fade / 1000 | R new | R end | R growth | 80 % at |
|---|---|---|---|---|---|---|---|---|---|
| Cell1 | 8200 | 739 mAh | 561 mAh | 75.9 % | 2.8 % | 62 mOhm | 97 mOhm | +56 % | 5764 |
| Cell2 | 7700 | 735 mAh | 545 mAh | 74.2 % | 3.3 % | 64 mOhm | 124 mOhm | +92 % | 4882 |
| Cell3 | 8100 | 735 mAh | 566 mAh | 77.0 % | 2.8 % | 62 mOhm | 97 mOhm | +56 % | 6245 |
| Cell4 | 5100 | 734 mAh | 581 mAh | 79.2 % | 4.1 % | 63 mOhm | 84 mOhm | +33 % | 4634 |
| Cell5 | 5000 | 735 mAh | 456 mAh | 62.0 % | 4.0 % | 61 mOhm | 140 mOhm | +129 % | 4823 |
| Cell6 | 5000 | 733 mAh | 579 mAh | 79.0 % | 3.8 % | 63 mOhm | 84 mOhm | +31 % | 4599 |
| Cell7 | 8100 | 729 mAh | 583 mAh | 80.0 % | 2.3 % | 61 mOhm | 97 mOhm | +58 % | 7993 |
| Cell8 | 8100 | 728 mAh | 559 mAh | 76.8 % | 2.8 % | 63 mOhm | 99 mOhm | +54 % | 6336 |
Three things stand out, and none of them are visible in a datasheet:
- Identical cells do not age identically. At 5000 cycles the batch ranges from 85.5 % down to 62.0 % capacity: a spread of 23.5 points between the best and the worst cell.
- Cell5 failed differently, not just faster. Its resistance more than doubled (+129 %) and its fade curve has a sharp knee at 4800 cycles, while cells 4 and 6, with almost the same capacity fade, grew only ~32 % in resistance. Capacity alone would have missed it.
- The pack pays for the spread. The average cell reaches 80 % at 5659 cycles; a series pack of these eight reaches it at 4609. That gap is the argument for cell matching, and for a BMS that watches every cell instead of the pack total.
Requires Python 3.10 or newer.
git clone https://github.com/zero705/cell-ageing-analyzer.git
cd cell-ageing-analyzer
python -m pip install . # analysis only
python -m pip install ".[plot]" # plus charts (adds matplotlib)The dataset is 250 MB and published under the Open Database License, so it is not part of this repository.
- Open the Oxford Battery Degradation Dataset 1 page.
- Download
Oxford_Battery_Degradation_Dataset_1.mat. - Turn it into a small history file once:
$ cellage ingest Oxford_Battery_Degradation_Dataset_1.mat -o ageing.npz
Read 8 cells and 519 characterisations from Oxford_Battery_Degradation_Dataset_1.mat
Saved ageing.npzageing.npz is about 1.5 MB and loads instantly, so the 250 MB file is read exactly once.
Every other command works on the small file.
$ cellage cells ageing.npz
Cell Points Cycles Capacity SOH
Cell1 78 8200 561 mAh 75.9%
Cell2 73 7700 545 mAh 74.2%
Cell3 76 8100 566 mAh 77.0%
Cell4 47 5100 581 mAh 79.2%
Cell5 46 5000 456 mAh 62.0%
Cell6 46 5000 579 mAh 79.0%
Cell7 77 8100 583 mAh 80.0%
Cell8 76 8100 559 mAh 76.8%$ cellage summary ageing.npz --cell Cell5
Cell Cell5: 46 characterisations over 5000 drive cycles
Capacity 735 -> 456 mAh (62.0% of new)
Fade rate 4.0% per 1000 cycles
Resistance 61 -> 140 mOhm (+129%)
Rate loss -1.6 -> 56.8 mAh lost at 1C versus the slow discharge
dQ/dV peak 3.792 -> 3.785 V (-7 mV), height -53%
End of life 4823 cycles at 80% capacity
Ageing knee 4800Read that as a story: the cell lost 38 % of its capacity, but it lost far more than that in usable capacity at 1C -- 56.8 mAh of what remains can no longer be delivered at the rate a vehicle asks for, because the resistance more than doubled.
$ cellage summary ageing.npz
Fleet of 8 cells at cycle 5000
Mean capacity 78.9% of new
Best Cell7: 85.5%
Worst Cell5: 62.0%
Spread 23.5% between best and worst
Mean cell reaches end of life at 5659 cycles
A series pack of these cells reaches it at 4609 cycles
Cell spread costs the pack 1050 cycles of life--format markdown writes a report to paste into a document, and --format json gives the
same numbers for another script to read.
cellage plot fade ageing.npz -o fade.png
cellage plot resistance ageing.npz -o resistance.png
cellage plot ica ageing.npz -o ica.png --cell Cell1
cellage plot fleet ageing.npz -o fleet.png --theme darkThe file extension picks the format (.png, .svg or .pdf) and --theme dark switches
the palette. The colours are checked for colour-vision deficiency in both themes.
Differentiating a slow charge turns each electrode plateau into a peak. For Cell1 the main peak slides 21 mV down (lithium is being lost) and loses 60 % of its height (active material is being lost), while the small peak near 3.5 V fades away almost completely. This is the difference between "the cell is worn out" and knowing what wore out.
Six cells grow their resistance along one tight line. Cell5 and Cell2 leave it -- the same two cells whose capacity later collapses. Resistance sees the problem before capacity does.
from cellage import AgeingHistory, build_history, render, summarise_fleet
history = build_history("Oxford_Battery_Degradation_Dataset_1.mat")
history.save("ageing.npz")
history = AgeingHistory.load("ageing.npz")
cell = history.get("Cell1")
print(cell.final.capacity_mah) # 560.6
print(cell.final.state_of_health) # 0.7585
print(cell.resistance_growth) # 0.562 -> +56 %
print(cell.end_of_life_cycle) # 5764.5
print(cell.knee_cycle) # None: this cell fades in a straight line
fleet = summarise_fleet(history)
print(fleet.worst_cell, fleet.pack_life_lost) # Cell5 1050.3
print(render(history, fmt="markdown"))Every equation is written out in docs/method.md, with a worked example from the dataset. In short:
| Step | What happens |
|---|---|
oxford.py |
Reads the nested MATLAB file into characterisation records, one per pause in the test |
metrics.py |
Pure functions: capacity, state of health, resistance, dQ/dV, threshold crossing, knee, fade rate |
history.py |
Turns 250 MB of curves into a 1.5 MB history file, and answers questions about one cell |
fleet.py |
Compares the cells on a common cycle grid and derives the pack life |
report.py |
Text, Markdown and JSON output |
plots.py |
The four charts, in a light and a dark theme |
cli.py |
The cellage command |
The resistance estimate deserves one line here, because it is the part most people ask
about: there is no pulse test in this dataset, but a charge and a discharge at the same
current sit symmetrically above and below the same equilibrium voltage, so their gap at a
matched depth of charge is 2*I*R.
The tool is honest about what this data can and cannot tell you. The full list is in docs/method.md; the three that matter most:
- One temperature and one drive cycle. Everything here describes 40 C and ARTEMIS urban. It does not extrapolate to other conditions.
- Resistance is a DC estimate over an hour-long step, so it reads higher than a 1 kHz datasheet impedance. Its growth is what carries meaning.
- Eight cells describe these eight cells, not a production distribution, and calendar ageing is mixed in with cycle ageing over the two years of the test.
Both file formats the tool reads can come from somewhere else, so both are treated as untrusted input. The details are in SECURITY.md; the short version:
- History files are never unpickled (
allow_pickle=False). With pickling enabled, opening a file would be enough to run whatever came with it. - Size is checked before anything is unpacked. A
.npzis a zip archive, so a small file can declare enormous arrays; one that claims to unpack into hundreds of megabytes is refused rather than loaded. - Every field is validated. Cell names must be plain names, numbers must be finite numbers, and curves must match the characterisations they belong to.
- Nothing from a file can rewrite your terminal. Text taken from a file is stripped of control characters before it is printed, and cell names carrying escape sequences are rejected outright.
- Damaged files give an error, not a traceback. Whatever the MATLAB parser throws is turned into a message that names the cell and cycle it failed on.
There is no network access, no subprocess, and no code in the repository that evaluates
anything it reads. tests/test_security.py holds a file for each of these cases.
src/cellage/ the package: oxford, metrics, history, fleet, report, plots, cli
tests/ 180 tests, 100 % coverage, all on synthetic or crafted files
docs/method.md every equation, with worked examples
docs/images/ the charts in this README, light and dark
SECURITY.md how untrusted files are handled, and how to report a problem
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
pytest --cov # 180 tests, 100 % coverage
ruff check . && ruff format --check .
mypyThe tests never touch the 250 MB dataset. They build small cells whose ageing is known exactly -- a known resistance, a known fade rate, a known knee -- and check that the tool recovers those numbers, plus synthetic MATLAB and history files, including damaged and deliberately hostile ones, to exercise the readers. That keeps the suite fast enough to run on every commit, on Linux and Windows, on Python 3.10 to 3.14. A separate CI job audits the dependencies for known vulnerabilities.
The Oxford Battery Degradation Dataset 1 is published by the University of Oxford under the Open Database License (ODbL); its contents are licensed under the Database Contents License. This repository contains no dataset files, only code that reads them.
Christoph R. Birkl (2017). Oxford Battery Degradation Dataset 1. University of Oxford. https://ora.ox.ac.uk/objects/uuid:03ba4b01-cfed-46d3-9b1a-7d4a7bdf6fac
Ömer Faruk Şenol, Hybrid and Electric Vehicles Technology, İnönü University