BMSLogic

Open-source battery management system (BMS) simulation toolkit for lithium-ion batteries
Python + C++ framework for battery cell models, EV-level simulations, and high-performance solver workflows

BMSLogic © 2024 by Moin Ahmed is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International

Built and Created by Moin Ahmed and Contributers

About • Getting Started • Examples • Architecture Doc • Contributing • Cite

About The Project

This repository contains the source code for performing battery management system related simulations and calculations including battery cell, battery packs, and other system-level simulations.

It combines:

• Electrochemical battery cell models (SPM/SPMe/P2D-style workflows),
• Equivalent circuit models (ECM/ESC),
• Thermal + degradation model components,
• Kalman filtering utilities,
• Application-level electric vehicles (EVs) and drive-cycle simulations,
• Python ergonomics with C++ acceleration via pybind11.

If you are working on lithium-ion battery modeling, lithium-ion state estimation, solver performance studies, BMS prototyping, or Electric vehicle energy consumption and range this repo is designed for you.

🔥 Why this repo is useful

- **Hybrid performance stack**: iterate quickly in Python, accelerate critical paths in C++. - **Research-ready**: includes examples, test suites, and parameter sets for repeatable studies. - **End-to-end flow**: from battery cell physics to EV drive-cycle level analysis. - **Extensible architecture**: add new parameter sets, models, solvers, and workflows with clear module boundaries.

If this project helps your research or product, please ⭐ star the repository and share it with peers in battery/BMS communities.

🧠 Key capabilities

Battery cell simulation

• Cell component abstractions (electrodes, electrolyte, cell).
• Charge/discharge/custom cycling workflows.
• Solver families for concentration, potential, and model-level terminal voltage evolution.

Modeling and estimation

• Single-particle model, enhanced single particle model, and simple pseudo two-dimensional (P2D) models.
• Equivalent-circuit model support.
• Kalman filter support in helper modules.

EV/application layer

• Drive-cycle utilities (e.g., FTP, UDDS, HWFET, US06, etc. where present in data).
• EV drivetrain and pack-level abstractions for systems-oriented simulations.

Developer productivity

• CMake build pipeline for native + Python-extension targets.
• Python and C++ tests.
• Rich examples in both languages.

(back to top)

Getting Started

The following contains the instructions for running this repository locally in this machine.

While installing, it is important to keep in mind that the source code contains both C++ and Python code. Hence, after cloning the repository from Github, C++ code is built using CMake. Then the Python virtual environment is setup and required Python packages are installed.

Prerequisites

• Ensure your system has the following
  • Python with pip and venv installed
  • C++ Compilers and CMake

Installation

Option 1: Using pip installer (easier, tested on Ubuntu)

1. It is highly recommended to setup and activate Python virtual environment for your project
2. Run the following command in the terminal/command prompt to install this as a Python package for your project.

pip install git+https://github.com/m0in92/bmslogic.git

Option 2: Build from Source

1. Clone the repository

   git clone --recurse-submodules git@github.com:m0in92/bmslogic.git

   Note that when pulling the updates use the following git commands to pull the updates and additional submodules

   git pull origin main
   git submodule init
   git submodule update
   

2. Build the C++ files using cmake

   mkdir build && cd build
   cmake ..
   cmake --build .

   To complie only C++ code (for example in embedded systems), set the cmake variable CPP_ONLY to ON via using the following command (instead of cmake .. above)

   cmake .. -EMBEDDED=ON

   • Install Python project dependencies.
     It is recommended to create a virtual Python environment for this project, especially if the functionalities supported by Python Language are to be used. For this purpose, follow the steps below:

3. Create the Python virtual environment

   python -m venv venv

4. Activate the virtual envinronment
   On Windows:

   venv\Scripts\activate

   On macOS and Linux:

   source venv/bin/activate

5. Verify Activation
   Once activated, your command line prompt should prepend the name of the virtual environment, indicating that it's active. For example:

   (venv) user@hostname:~/path/to/repository$

6. Install Python dependencies

   pip install -r requirements.txt

Tests

3. For python tests, run the following on the command line

   pytest tests

4. Google tests is used for testing the C++ code. Use the following to run the existing tests.

   cd cpp_tests
   ./bmslogic_tests   (on Linux)
   bmslogic.exe       (on Windows)

(back to top)

Examples

Explore runnable examples under:

• examples/simulations/cell/
• examples/calc_helpers/
• examples/simulations/cell/pure_cpp/
• examples/simulations/cell/pure_python/

These cover simulation runs, solver variants, kalman-filter-related workflows, and plotting scripts.

(back to top)

Developer architecture doc

A detailed architecture walkthrough (module boundaries, runtime flow, build targets, extension points) can be found at the following link:

• doc/developer_guidelines/architecture.md

(back to top)

Contributing

Contributions are welcome from battery researchers, controls engineers, and simulation developers.

Useful places to start:

• run tests locally,
• pick an example and reproduce results,
• add a new parameter set,
• improve solver performance,
• improve docs and onboarding.

(back to top)

📚 How to Cite

If you want to use this codebase in your research and cite it in your work, please cite the following works:

1. Ahmed, M., Mao, Z., Liu, Y., Yu, A., Fowler, M., & Chen, Z. (2024). Comparative Analysis of Computational Times of Lithium-Ion Battery Management Solvers and Battery Models Under Different Programming Languages and Computing Architectures. Batteries 2024, Vol. 10, Page 439, 10(12), 439. https://doi.org/10.3390/BATTERIES10120439
2. Ahmed, M. (2024). Applications of Mathematical Models for Lithium-Ion Battery Management Systems. University of Waterloo. https://hdl.handle.net/10012/21242

(back to top)

Road Map

Coming soon!

(back to top)