BatteryPack

BatteryPack is a Python framework that simulates how a lithium-ion battery pack behaves electrically and thermally under charge, discharge, and load—so you can estimate efficiency, temperature rise, power limits, and safety margins before hardware sign-off.

It couples a first-order equivalent-circuit cell model with pack-level series/parallel topology, lumped (and optional multi-node) thermal dynamics, configurable cell chemistries, drive-cycle profiles, and Python-based failure-mode / thermal-runaway screening.

---

Key capabilities

• Electro-thermal modeling — ECM cell (R₀ + R₁‖C₁), Ns×Np pack, thermal network, temperature-dependent resistance
• DC power & efficiency — Pack V/I/P/SoC time series; round-trip energy efficiency (RTE)
• Configurable chemistries — LFP, NMC811, NCA, LCO presets (cell_params_for_chemistry())
• Load & charge profiles — Synthetic cycles, CSV velocity profiles, fast-charge curve models (CCS / CHAdeMO / Supercharger-style)
• Automotive-style cycles — Parametric EPA UDDS, WLTP, NEDC generators (see FEATURES.md for limits)
• BMS & safety — Protection limits, thermal-runaway triggers, hazard index, FMEA table
• Analysis extras — Mission profiles, Monte Carlo sweeps, economics/LCOE, UPS backup sizing, metrics export (CSV/JSON/HDF5)
• DSC (Differential Scanning Calorimetry) — (T_g), phase transitions, and thermal-damage onset from heat-flow traces; cross-check simulated peak temperatures (docs/DSC.md)
• CI — pytest on Python 3.10–3.12, Black formatting

Full module-by-module inventory (including what is not built): FEATURES.md

---

Screenshots

Time series — pack current, voltage, power, SoC during discharge:

Thermal — temperature through charge/discharge:

Round-trip efficiency:

Charge / load profile:

Chemistry comparison — RTE across cell presets (same pack topology):

Safety — thermal-runaway hazard vs pack temperature:

Power limits — max charge/discharge vs SoC:

DSC — heat flow vs temperature with (T_g), exotherm onset, and simulated pack peak (see docs/DSC.md):

python scripts/run_dsc_demo.py
python scripts/generate_readme_plots.py   # refreshes assets/dsc_analysis.png

---

Project layout

battery_pack/
  cell.py, pack.py, thermal.py   # ECM + pack + thermal
  simulation.py                  # charge/discharge, RTE
  drive_cycles.py                # synthetic / dataframe cycles
  drive_cycles_real.py           # EPA/WLTP/NEDC-style generators
  charging.py, bms.py, safety.py
  config.py                      # chemistry presets
scripts/
  generate_readme_plots.py       # figures in assets/
  run_demo.py, run_sweeps.py, run_ups_demo.py
tests/

More examples: EXAMPLES.md

---

Quickstart

git clone https://github.com/chaffybird56/BatteryPack.git && cd BatteryPack
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

pytest tests/ -q
python scripts/generate_readme_plots.py   # refresh assets/*.png

from battery_pack.config import cell_params_for_chemistry
from battery_pack.pack import BatteryPack

cell = cell_params_for_chemistry("LFP")  # or NMC811, NCA, LCO
pack = BatteryPack(cell_params=cell, ...)

Topics

Search-friendly tags for this project:

battery-simulation · lithium-ion · battery-pack · battery-modeling · equivalent-circuit-model · electro-thermal · bms · thermal-runaway · state-of-charge · round-trip-efficiency · drive-cycle · fast-charging · electric-vehicle · energy-storage · grid-storage · ups-backup · monte-carlo · python · open-source

GitHub Topics for this repo are defined in .github/repository-topics.json. Re-apply after edits: bash scripts/set_github_topics.sh (uses your existing git GitHub credentials).

License

MIT — see LICENSE.