BatteryDRT

Interpretable DRT peak tracking for battery degradation diagnostics.

Applies Modal Assurance Criterion (MAC), Optimal Transport, and Hungarian algorithm to track Distribution of Relaxation Times (DRT) peaks across the battery lifecycle.

Positioning: BatteryDRT is a benchmarking framework for DRT-based degradation monitoring, not a single tracking method. End-to-end ML on raw EIS (CNN/Transformer) achieves higher accuracy for SoH estimation (>90%), but cannot show which peaks are changing. DRT peak tracking provides physically traceable degradation genealogies — relevant for anomaly detection and regulated domains where explainability is required.

Caveat: DRT tracking monitors what changes (which peaks grow/shift/split), but cannot reliably assign why (which mechanism) — tau-band-based mechanism assignment was shown to be lambda-unstable and no better than random boundaries.

Validated Results

• 179 real cells benchmarked (24 NCM Calendar+Cycling, 131 NMC/C-SiO, 24 Warwick NMC811 cross-sectional)

• 12 tracking methods compared (MAC, Euclidean, NN, Wasserstein/OT, MCF, NMF, PHD-GM)

• 900 ground-truth runs (300 per lambda-strategy: fixed 1e-3, auto L-curve, auto GCV; 10 scenarios x 3 noise levels x 10 seeds)

• GT-score ranking (auto L-curve, averaged over 10 base scenarios):

  Rank	Method	GT-score
  1	MAC-H ~30D	0.530
  2	MAC-MCF 9D	0.525
  3	MAC-H 9D	0.524
  4	MAC-H 4D	0.521
  5	OT-DRT	0.517
  6	NN-E 9D	0.505
  7	NN-tau 1D	0.503
  ..	...	...
  11	PHD-GM	0.404
  12	NMF-Auto	0.391

• Real-data best tracker: NN-tau (threshold=0.5) — literature standard, most stable families

• Curve features (~30D) best on synthetic GT, but harmful on real data (overfits noise)

• OT-DRT split/merge: natively detected via transport-plan mass flow; however, on real data most detected events are tracking artifacts

• ECM-proxy GT: real-data ground truth via R-RC fitting + Hungarian tracking

• Mechanism validation: tau-band-based mechanism assignment is lambda-unstable (null-test failed). DRT peak tracking monitors degradation effectively, but cannot reliably assign mechanisms via tau-bands.

SotA Positioning

Task	Actual SotA	BatteryDRT
Battery SoH from EIS	End-to-end ML (CNN/Transformer): >90% accuracy	Not competitive (best GT-score 0.530)
DRT peak tracking (niche)	NN-tau / manual (Wan, Iurilli, Schindler)	Benchmarking framework: 12 methods compared, MAC-H ~30D #1 on GT; NN-tau best on real data

Features

• DRT Extraction: Tikhonov-regularized DRT with automatic lambda selection (L-curve, GCV) or manual; series elements (inductance, CPE, Warburg); configurable peak detection; reg_order 0/1/2
• 3 Feature Representations: Basic 4D, Extended 9D (area, prominence, slopes, curvature), Curve Segment ~30D
• Feature Normalization: FeatureScaler (z_score, min_max, log_z_score) eliminates tau-dominance in MAC dot-products
• 4 Similarity Metrics: MAC (cos-squared), Euclidean distance, Wasserstein/OT (Sinkhorn), Min-Cost-Flow LP
• 3 Assignment Strategies: Hungarian (globally optimal), Greedy Nearest-Neighbor, Sinkhorn transport plan
• 12-Method Benchmark: Systematic comparison with composite scoring, 6-panel visualization, ground-truth accuracy
• Split/Merge Tracking: OT-native via transport-plan mass flow (OT-DRT); physics heuristic for all other methods (amplitude conservation, tau-proximity)
• Nonlinear Risk Scoring: 3 trend models (linear/sqrt/exp) with AIC-based selection; multi-chemistry tau-bands (NMC, LFP, NCA); percentile normalization
• Bootstrap Uncertainty: Perturbation-based DRT confidence intervals per peak (tau_std, amp_std, CI_95, detection_rate)
• DRT Reconstruction: Reconstruct Z(f) from DRTResult with quality metrics
• Visualization: Nyquist, DRT spectra, MAC heatmaps, genealogy graphs with error bars, benchmark 6-panel, reconstruction overlay

Requirements

• Python >= 3.12
• Core: numpy, scipy, matplotlib

Quick Start

# Install
uv sync --extra dev

# Run tests
uv run python -X utf8 -m pytest

# Full verification (179 cells, auto-lambda)
uv run python -X utf8 scripts/verification_study.py

# Quick smoke-test (3 cells per dataset)
uv run python -X utf8 scripts/verification_study.py --n-cells 3

# Ground-truth validation (900 runs)
uv run python -X utf8 scripts/ground_truth_validation.py

# ECM-proxy GT on real cells
uv run python -X utf8 scripts/real_data_gt_validation.py
uv run python -X utf8 scripts/real_data_gt_validation.py --n-cells 5   # quick test

Optional Dependencies

uv sync --extra data       # openpyxl + xlrd (NCM xlsx / Warwick xls loading)
uv sync --extra drt        # pyDRTtools (alternative DRT extraction)
uv sync --extra eis        # impedance.py (EIS analysis tools)
uv sync --extra graph      # networkx + plotly (graph visualization)
uv sync --extra surrogate  # scikit-learn (surrogate models)

CLI

batterydrt --help

Pipeline

EIS Spectrum (.csv/.json)
  -> DRT Extraction (Tikhonov, auto-lambda via L-curve/GCV)
  -> Peak Detection -> Feature Engineering (4D / 9D / ~30D)
  -> Optional: Feature Normalization (FeatureScaler)
  -> Similarity Matrix (MAC / Euclidean / Wasserstein / MCF)
  -> Assignment (Hungarian / Greedy-NN / Sinkhorn / MCF-LP)
  -> Peak Families (genealogy) + Split/Merge Detection
  -> Benchmark Comparison (12 methods, composite score, GT accuracy)
  -> Nonlinear Risk Ranking (AIC model selection, multi-chemistry bands)
  -> Bootstrap Uncertainty (CI_95 per peak)
  -> Visualization (Nyquist, DRT, MAC heatmap, genealogy, reconstruction)

Notebooks

Notebook	Description	Runtime
Pipeline Walkthrough	Full pipeline: synthetic EIS -> DRT -> reconstruction -> tracking -> split/merge -> 12-method benchmark -> small-peak sensitivity -> real data (3 chemistries)	~5-10 min
Parameter Tuning	Grid search (515 runs, 5 NMC cells): optimal parameters per method, sensitivity heatmaps, radar chart	~2 min
Peak Families Exploration	Deep-dive into peak families on real NMC data: 4-method comparison, tau-jump quantification, multi-cell benchmark	~5 min

All notebooks work without data for synthetic examples. For real-data sections, download datasets to data/raw/:

• NCM Calendar & Cycling: Beelen et al., Data in Brief 2020 -> data/raw/NCM_Calendar_and_Cycling_Dataset/
• KIT NMC/C-SiO: KIT Dataset 10.35097/1947 -> data/raw/10.35097-1947/
• Warwick NMC811: Faraji-Niri et al., Data in Brief 2023 -> data/raw/Warwick NMC811 (Faraji-Niri 2023)/

Contributing

See CONTRIBUTING.md for setup instructions, code style, and how to run the tests.

License

PolyForm Noncommercial License 1.0.0 — free for non-commercial use. For commercial licensing, contact Linked Engineering GmbH.