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.
- Electro-thermal modeling
- DC power & efficiency
- Configurable chemistries
- Load & charge profiles
- Automotive-style cycles
- BMS & safety
- Analysis extras
- CI
Full module-by-module inventory: FEATURES.md
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:
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
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/*.pngfrom 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, ...)MIT — see LICENSE.