Skip to content

About

Measure lithium-ion cell ageing from laboratory cycling data: capacity fade, resistance growth and degradation modes

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Cell Ageing Analyzer

CI Python License Coverage Typed Lint

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.

Capacity against drive cycles for eight cells. The band between the best and worst cell widens with age; the weakest cell crosses 80 % capacity at 4609 cycles, 1050 cycles before the average cell.

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.

What it answers

  • 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?

Findings from the dataset

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:

  1. 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.
  2. 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.
  3. 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.

Installation

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)

Getting the data

The dataset is 250 MB and published under the Open Database License, so it is not part of this repository.

  1. Open the Oxford Battery Degradation Dataset 1 page.
  2. Download Oxford_Battery_Degradation_Dataset_1.mat.
  3. 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.npz

ageing.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.

Using it

List the batch

$ 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%

Look at one cell

$ 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   4800

Read 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.

Report the whole batch

$ 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.

Charts

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 dark

The 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.

Where the capacity went

dQ/dV curves of Cell1 at five ages. The main peak at 3.8 V slides 21 mV downwards and loses 60 % of its height as the cell ages, and a second peak near 3.5 V shrinks almost to nothing.

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.

Capacity and resistance together

Resistance against drive cycles for eight cells, and resistance against remaining capacity. Most cells rise from about 62 to 97 mOhm; Cell5 and Cell2 break away from the group.

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.

Python API

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"))

How it works

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.

Limitations

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.

Handling files you did not write

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 .npz is 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.

Project structure

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

Development

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 .
mypy

The 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.

Data licence and citation

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

Author

Ömer Faruk Şenol, Hybrid and Electric Vehicles Technology, İnönü University

GitHub · LinkedIn

License

MIT

About

Measure lithium-ion cell ageing from laboratory cycling data: capacity fade, resistance growth and degradation modes

Topics

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages