Skip to article content

Revised 23 October 2026 · v1.0.0 · what changed

Code: github.com/herrrickshaw/ev-battery-management-sim

Watch the walkthrough

Watch on YouTube: youtu.be/e5MgJPizoEo

Why it is useful

• Who benefits: students, e-mobility analysts and engineers who want a runnable reference of a battery management system (charge estimate, ageing, balancing, thermal limits, fault handling).
• What it replaces: stitching together a cell model, a Kalman filter and a wear model from scratch. The vehicle comparison, degradation, cold-weather and 10-year projection runs are one command each.
• Evidence from the run: 112 tests passed in 4.2 seconds, and the dataset validation printed a five-part report in about 8 seconds on a laptop.
• It also ships a cleaning notebook that turns the NASA battery .mat files into CSVs, which is useful if you download the NASA data yourself.

What it is for

The bms package models a lithium or lead-acid pack: a two-RC equivalent-circuit cell, an Extended Kalman Filter for state of charge, capacity and resistance fade for state of health, passive balancing, thermal control, power limits and a supervisor that opens the contactor on faults. Run python -m bms.simulation with a flag to see each part.

It is a teaching and prototyping tool. It is simulation only, not engineering design: do not use it to size or certify a real pack.

Who it is for

• Students and engineers learning how a BMS works
• EV and e-mobility analysts who want a runnable reference
• Non-programmers who want an AI assistant to explain each algorithm

What you need

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:

git clone https://github.com/herrrickshaw/ev-battery-management-sim.git
cd ev-battery-management-sim
claude      # or: gemini

Install

1. Get the code

   git clone https://github.com/herrrickshaw/ev-battery-management-sim.git
   cd ev-battery-management-sim

2. Create an environment and install

   python3 -m venv .venv && source .venv/bin/activate
   pip install numpy pandas pytest scipy matplotlib

Quick start: commands and what you should see

Run the tests

python -m pytest -q

112 passed.

Compare the vehicle classes

python -m bms.simulation --vehicle 2W

A comparison table of the four vehicle classes, then the scooter run.

Run the degradation simulation

python -m bms.simulation --degradation

Cycle-by-cycle table of capacity and resistance fade for a scooter and a bus.

Run the dataset validation (synthetic)

python -m bms.simulation --datasets

Six synthetic datasets are generated and a five-part validation report is printed.

Sample outputs

Real output from a run on the date shown in the sources line; trimmed to fit.

Vehicle comparison table

python -m bms.simulation
2-Wheeler (Scooter)  LFP        15S1P   48V   1.4 kWh   1.5 kW  CC-CV
4W Retrofit (PbA)    Lead-Acid  36S1P   72V   9.4 kWh   10 kW   CC-CV-Float
4W Modern LFP        LFP        32S1P   102V  6.1 kWh   30 kW   CC-CV
Electric Bus         LFP        128S2P  409V  163.8 kWh 150 kW  CC-CV

Trimmed columns.

Degradation run, 48 V scooter pack (accelerated model)

python -m bms.simulation --degradation
Cycle  SOH-Q%  Cap(Ah)  SOH-R%  R0(mOhm)  Status
  100    90.0    90.0    90.9    2.20     OK
  200    80.0    80.0    83.3    2.40     OK
  250    75.0    75.0    80.0    2.50     WARNING
  300    70.0    70.0    76.9    2.60     WARNING
EOL at SOH=80.0% : ~200 cycles

A straight-line fade of 0.1% per cycle; the script itself labels it an accelerated model.

Validation report (synthetic data matching Kaggle schemas)

python -m bms.simulation --datasets
1. EKF SOC estimation   RMSE 0.117 %   MAE 0.113 %   PASS (target < 3 %)
2. Capacity fade        SOH RMSE 0.0504 %   fitted fade 0.1001 %/cycle   EOL cycle 199
3. 2-RC voltage model   RMSE 1.07 mV   MAPE 0.027 %   PASS (target < 20 mV)
4. RUL estimation       RMSE 4.2 cycles   MAPE 4.28 %
5. Multi-module health  degraded module [3], avg SOH 85.0 % vs 97.3 %
NOTE: Results above use synthetic data matching Kaggle dataset schemas.

Run on 19 October 2026.

NASA battery-life notebook

nasa-battery-life-prediction-dataset-cleaning.ipynb
Not run. The notebook reads .mat files from /kaggle/input/nasa-battery-dataset, which needs a Kaggle login and download.

Its cells convert each NASA cycle into a CSV plus a metadata.csv; I read them but did not execute them.

Ways to use it

Sample prompts for your AI assistant

Copy, paste and edit the parts in [brackets].

• Claude: Read bms/soc_estimator.py and explain in plain language how the Kalman filter estimates state of charge.
• Gemini: Run python -m bms.simulation --cold and describe at what temperature the first fault appears.
• ChatGPT: I uploaded the output of --datasets. Which of the five checks are circular because the data were generated by the same model?
• GitHub (Copilot Chat): Add a requirements.txt listing numpy, pandas, scipy, matplotlib and pytest, and check the tests still pass.
• Claude: Walk me through the NASA cleaning notebook cell by cell and list what files it produces.

Limits and honest caveats

Sources: Ran pytest and python -m bms.simulation (default, --degradation, --datasets) from a fresh clone of github.com/herrrickshaw/ev-battery-management-sim (commit b6d37cd) in a throwaway virtualenv on 19 October 2026. The NASA notebook and Kaggle downloads were not run.

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.