A small Python library that simulates battery management for electric scooters, retrofitted cars and buses, so you can watch charge level, ageing, heat and faults on your laptop before any hardware exists.
Open-source tools · How-to · Mobility & EV
How to use bms-battery-management: simulate an EV battery pack in Python
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/bms-battery-management
Watch the walkthrough
Watch on YouTube: youtu.be/WK-4ghCppHs
What it is for
A battery pack needs software to track how full it is (state of charge) and how worn it is (state of health), because neither can be measured directly. The software must also balance cells, limit power, manage temperature and cut the contactor on a fault.
This library puts those pieces in one package: a two-RC Thevenin cell model, an Extended Kalman Filter for charge level, a wear model, passive cell balancing, thermal control, power limits and a supervisor with fault codes. It is for simulation and learning.
Who it is for
- Engineers and students learning how a battery management system works
- EV and e-mobility analysts who want a runnable reference
- Non-programmers who want an AI assistant to explain each part
- Running a real battery pack. This is a simulation, not firmware.
- Predicting the life of a specific real cell. The ageing model is a simple linear fade.
- Treating the validation numbers as real-world accuracy. They come from synthetic data.
What you need
| Requirement | Why | How to get it |
|---|---|---|
| Python 3 | runs the simulation | python.org or brew install python (the README does not state a minimum version) |
| numpy and pytest | core library and tests | installed by requirements.txt |
| pandas | needed by the --datasets validation but missing from requirements.txt | pip install pandas |
| matplotlib | only for the --plot comparison chart, also not listed | pip install matplotlib |
| Optional: Kaggle battery datasets | real data for validation | download_kaggle_datasets.sh fetches them. Without them the tool uses synthetic data. |
| Not needed | no GPU, no hardware, no API key, no database | runs on a normal laptop |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/bms-battery-management.git
cd bms-battery-management
claude # or: geminiInstall
- Get the code
git clone https://github.com/herrrickshaw/bms-battery-management.git cd bms-battery-management - Create an environment
python3 -m venv .venv && source .venv/bin/activate - Install the listed requirements (numpy, pytest) plus the two packages the README leaves out
pip install -r requirements.txt pandas matplotlib
Quick start: commands and what you should see
Compare the vehicle classes
python -m bms.simulationA comparison table: 2-wheeler LFP 15S1P 48 V, 4W retrofit lead-acid 36S1P 72 V, 4W modern LFP 32S1P 102 V, bus LFP 128S2P 409 V (163.8 kWh), with the algorithms and chemistries supported. The plot run (--plot) did not finish within two minutes in the demo.
Simulate a 2-wheeler charge and discharge (use 2W, not two_wheeler)
python -m bms.simulation --vehicle 2WA time table of state, charge percent, pack voltage, current, hottest cell and fan speed. Charging started at 15.0% and reached 56.8% at 52.2 V and 47.1 C. After discharge: SOC 53.4%, no fault, SOH 99.99%.
Run the 300-cycle degradation model
python -m bms.simulation --degradationHealth falls 0.1% per cycle: 95.0% at cycle 50, 80.0% at cycle 200, 70.0% at cycle 300, with resistance rising from 2.00 to 2.60 mOhm. WARNING status from cycle 225. End of life at 80% is about cycle 200.
Validate against dataset-shaped data
python -m bms.simulation --datasetsOn synthetic data: charge-estimate RMSE 0.117% (target below 3%, PASS), voltage-model RMSE 1.07 mV (target below 20 mV, PASS), remaining-life RMSE 4.2 cycles, and one degraded module found out of several.
Run the test suite
pytest tests/112 passed in 10.33s.
Ways to use it
| Method | How it works |
|---|---|
| Command line | python -m bms.simulation with --vehicle (2W, 4W_RETRO or BUS), --degradation, --cold, --driving, --manufacturers, --datasets or --plot. |
| Library import | Import modules from the bms package, such as soc_estimator, soh_estimator, cell_balancer, thermal, power_limits, bms_controller and supervisor. |
| Notebook | nasa-battery-life-prediction-dataset-cleaning.ipynb is the exploratory notebook the NASA data loader came from. |
| Through an AI assistant | Open the cloned folder in Claude Code or Gemini CLI and ask it to run a scenario or explain a module. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Explain this repo in plain English. What do state of charge and state of health mean, and how does this code estimate them?
- Run the 2-wheeler simulation and explain each column of the output table.
- Change the degradation rate in the simulation and show me how the end-of-life cycle moves.
- Help me describe my own pack ([cells in series]S[cells in parallel]P, [chemistry]) as a vehicle profile in bms/vehicles.py.
- What are the limits of the linear ageing model, and what real data would I need to improve it?
- Fix the README install gaps: tell me every package I need that requirements.txt omits.
Limits and honest caveats
- The validation numbers come from synthetic data matching Kaggle dataset layouts. Real Kaggle files are optional and downloaded separately.
- The degradation model is a simple accelerated linear fade, not a measured cell model.
- README gaps found in the demo: requirements.txt lists only numpy and pytest, but --datasets also needs pandas and the plot needs matplotlib.
- The README example uses --vehicle two_wheeler, but the CLI accepts 2W, 4W_RETRO or BUS.
- The all-vehicle plot run did not finish within two minutes in the demo, so no plot is shown.
- This is simulation code, not battery firmware, and it has not been validated on a physical pack.
Sources: the repository README (herrrickshaw/bms-battery-management), requirements.txt, bms/simulation.py and the demo run of 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
