PyBaMM

Fast and flexible physics-based battery models in Python.
https://github.com/pybamm-team/pybamm

Category: Energy Storage
Sub Category: Battery

Keywords

batteries battery-models hacktoberfest pybamm python simulation solvers

Keywords from Contributors

transformer profiles simulator observability blog closember trace charts routing measure

Last synced: about 11 hours ago
JSON representation

Repository metadata

Fast and flexible physics-based battery models in Python

Host: GitHub
URL: https://github.com/pybamm-team/pybamm
Owner: pybamm-team
License: bsd-3-clause
Created: 2018-10-31T10:26:29.000Z (over 6 years ago)
Default Branch: develop
Last Pushed: 2025-04-18T19:45:38.000Z (8 days ago)
Last Synced: 2025-04-18T23:18:39.220Z (8 days ago)
Topics: batteries, battery-models, hacktoberfest, pybamm, python, simulation, solvers
Language: Python
Homepage: https://www.pybamm.org/
Size: 185 MB
Stars: 1,249
Watchers: 29
Forks: 614
Open Issues: 186
Releases: 52
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE-OF-CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS

PyBaMM

PyBaMM (Python Battery Mathematical Modelling) is an open-source battery simulation package
written in Python. Our mission is to accelerate battery modelling research by
providing open-source tools for multi-institutional, interdisciplinary collaboration.
Broadly, PyBaMM consists of
(i) a framework for writing and solving systems
of differential equations,
(ii) a library of battery models and parameters, and
(iii) specialized tools for simulating battery-specific experiments and visualizing the results.
Together, these enable flexible model definitions and fast battery simulations, allowing users to
explore the effect of different battery designs and modeling assumptions under a variety of operating scenarios.

PyBaMM uses an open governance model
and is fiscally sponsored by NumFOCUS. Consider making
a tax-deductible donation to help the project
pay for developer time, professional services, travel, workshops, and a variety of other needs.

💻 Using PyBaMM

The easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:

import pybamm

model = pybamm.lithium_ion.DFN()  # Doyle-Fuller-Newman model
sim = pybamm.Simulation(model)
sim.solve([0, 3600])  # solve for 1 hour
sim.plot()

or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:

import pybamm

experiment = pybamm.Experiment(
    [
        (
            "Discharge at C/10 for 10 hours or until 3.3 V",
            "Rest for 1 hour",
            "Charge at 1 A until 4.1 V",
            "Hold at 4.1 V until 50 mA",
            "Rest for 1 hour",
        )
    ]
    * 3,
)
model = pybamm.lithium_ion.DFN()
sim = pybamm.Simulation(model, experiment=experiment, solver=pybamm.IDAKLUSolver())
sim.solve()
sim.plot()

However, much greater customisation is available. It is possible to change the physics, parameter values, geometry, submesh type, number of submesh points, methods for spatial discretisation and solver for integration (see DFN script or notebook).

For new users we recommend the Getting Started guides. These are intended to be very simple step-by-step guides to show the basic functionality of PyBaMM, and can either be downloaded and used locally, or used online through Google Colab.

Further details can be found in a number of detailed examples, hosted here on
github. In addition, there is a full API documentation,
hosted on Read The Docs.
Additional supporting material can be found
here.

Note that the examples on the default develop branch are tested on the latest develop commit. This may sometimes cause errors when running the examples on the pybamm pip package, which is synced to the main branch. You can switch to the main branch on github to see the version of the examples that is compatible with the latest pip release.

Versioning

PyBaMM makes releases every four months and we use CalVer, which means that the version number is YY.MM. The releases happen, approximately, at the end of January, May and September. There is no difference between releases that increment the year and releases that increment the month; in particular, releases that increment the month may introduce breaking changes. Breaking changes for each release are communicated via the CHANGELOG, and come with deprecation warnings or errors that are kept for at least one year (3 releases). If you find a breaking change that is not documented, or think it should be undone, please open an issue on GitHub.

🚀 Installing PyBaMM

PyBaMM is available on GNU/Linux, MacOS and Windows.
We strongly recommend to install PyBaMM within a python virtual environment, in order not to alter any distribution python files.
For instructions on how to create a virtual environment for PyBaMM, see the documentation.

Using pip

pip install pybamm

Using conda

PyBaMM is available as a conda package through the conda-forge channel.

conda install -c conda-forge pybamm

Optional solvers

The following solvers are optionally available:

jax-based solver, see the documentation.

📖 Citing PyBaMM

If you use PyBaMM in your work, please cite our paper

Sulzer, V., Marquis, S. G., Timms, R., Robinson, M., & Chapman, S. J. (2021). Python Battery Mathematical Modelling (PyBaMM). Journal of Open Research Software, 9(1).

You can use the BibTeX

@article{Sulzer2021,
  title = {{Python Battery Mathematical Modelling (PyBaMM)}},
  author = {Sulzer, Valentin and Marquis, Scott G. and Timms, Robert and Robinson, Martin and Chapman, S. Jon},
  doi = {10.5334/jors.309},
  journal = {Journal of Open Research Software},
  publisher = {Software Sustainability Institute},
  volume = {9},
  number = {1},
  pages = {14},
  year = {2021}
}

We would be grateful if you could also cite the relevant papers. These will change depending on what models and solvers you use. To find out which papers you should cite, add the line

pybamm.print_citations()

to the end of your script. This will print BibTeX information to the terminal; passing a filename to print_citations will print the BibTeX information to the specified file instead. A list of all citations can also be found in the citations file. In particular, PyBaMM relies heavily on CasADi.
See CONTRIBUTING.md for information on how to add your own citations when you contribute.

🛠️ Contributing to PyBaMM

If you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at these guidelines first.

📫 Get in touch

For any questions, comments, suggestions or bug reports, please visit:

Our Contact Page
Our Discussion Forum

📃 License

PyBaMM is fully open source. For more information about its license, see LICENSE.

✨ Contributors

This project follows the all-contributors specification. Contributions of any kind are welcome!

Click here to see a full list of our contributors' profiles.

Citation (CITATION.cff)

cff-version: 1.1.0
message: "If you use PyBaMM, please cite it as below."
authors:
  - family-names: Sulzer
    given-names: Valentin
    orcid: "https://orcid.org/0000-0002-8687-327X"
  - family-names: Marquis
    given-names: Scott G.
    orcid: "https://orcid.org/0000-0002-6895-990X"
  - family-names: Timms
    given-names: Robert
    orcid: "https://orcid.org/0000-0002-8858-4818"
  - family-names: Robinson
    given-names: Martin
    orcid: "https://orcid.org/0000-0002-1572-6782"
  - family-names: Chapman
    given-names: S. Jon
    orcid: "https://orcid.org/0000-0003-3347-6024"
journal: "Journal of Open Research Software"
date-released: 2021-06-08
doi: 10.5334/jors.309
keywords:
  - "battery modelling"
  - "expression tree"
  - "python"
  - "symbolic differentiation"
version: "25.4.2"
repository-code: "https://github.com/pybamm-team/PyBaMM"
title: "Python Battery Mathematical Modelling (PyBaMM)"

Owner metadata

Name: PyBaMM Team
Login: pybamm-team
Email:
Kind: organization
Description:
Website: https://www.pybamm.org/
Location:
Twitter: pybamm_
Company:
Icon url: https://avatars.githubusercontent.com/u/48961907?v=4
Repositories: 23
Last ynced at: 2025-04-21T02:17:26.915Z
Profile URL: https://github.com/pybamm-team

GitHub Events

Total

Create event: 117
Release event: 6
Issues event: 235
Watch event: 171
Delete event: 111
Member event: 1
Issue comment event: 1284
Push event: 432
Pull request review comment event: 807
Pull request review event: 1041
Pull request event: 491
Fork event: 78

Last Year

Create event: 117
Release event: 6
Issues event: 235
Watch event: 171
Delete event: 111
Member event: 1
Issue comment event: 1284
Push event: 432
Pull request review comment event: 807
Pull request review event: 1041
Pull request event: 491
Fork event: 78

Committers metadata

Last synced: 3 days ago

Total Commits: 11,722
Total Committers: 134
Avg Commits per committer: 87.478
Development Distribution Score (DDS): 0.673

Commits in past year: 557
Committers in past year: 52
Avg Commits per committer in past year: 10.712
Development Distribution Score (DDS) in past year: 0.849

Name	Email	Commits
Valentin Sulzer	v**r@h**m	3828
Martin Robinson	m**s@g**m	871
Robert Timms	t**s@m**k	824
Scottmar93	m**s@m**k	820
Ferran Brosa Planella	F**a@w**k	790
Agriya Khetarpal	7****l	710
Thibault Lestang	t**g@c**k	434
Saransh Chopra	s**1@g**m	353
arjxn.py	a**y@g**m	297
pre-commit-ci[bot]	6****]	283
Priyanshu Agarwal	p**6@g**m	212
allcontributors[bot]	4****]	192
Eric G. Kratz	k****n	166
DrSOKane	s**e@i**k	152
Elias Hohl	e**l@a**m	137
John Brittain	j**2@g**m	115
tobykirk	t**k@m**k	92
tomtranter	t**r@g**m	91
Valentin Sulzer	s**r@m**k	81
Pip Liggins	p**s@d**k	80
Weilong	w**i@i**k	77
Vaibhav	n**t@g**m	70
Alexander Bills	a**s@a**u	65
dependabot[bot]	4****]	64
Diego	d**z@i**k	50
Jerom Palimattom Tom	8****m	49
felipe-salinas	6****s	49
Nwanoro	n**o@l**k	46
Tanner Leo	t**o@s**m	34
Alec Bills	a**s@g**m	34
and 104 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 1,720
Total pull requests: 2,498
Average time to close issues: 2 months
Average time to close pull requests: 12 days
Total issue authors: 229
Total pull request authors: 143
Average comments per issue: 2.88
Average comments per pull request: 2.8
Merged pull request: 2,162
Bot issues: 20
Bot pull requests: 415

Past year issues: 304
Past year pull requests: 637
Past year average time to close issues: 27 days
Past year average time to close pull requests: 6 days
Past year issue authors: 81
Past year pull request authors: 55
Past year average comments per issue: 2.56
Past year average comments per pull request: 3.22
Past year merged pull request: 496
Past year bot issues: 14
Past year bot pull requests: 150

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/pybamm-team/pybamm

Top Issue Authors

tinosulzer (371)
rtimms (175)
martinjrobins (149)
brosaplanella (126)
Scottmar93 (102)
agriyakhetarpal (71)
Saransh-cpp (70)
TomTranter (37)
ejfdickinson (22)
github-actions[bot] (20)
gyouhoc (18)
kratman (17)
BradyPlanden (16)
valentinsulzer (14)
arjxn-py (14)

Top Pull Request Authors

tinosulzer (540)
rtimms (167)
allcontributors[bot] (159)
kratman (149)
pre-commit-ci[bot] (118)
agriyakhetarpal (115)
martinjrobins (108)
brosaplanella (100)
Saransh-cpp (85)
dependabot[bot] (80)
Scottmar93 (62)
github-actions[bot] (58)
priyanshuone6 (54)
prady0t (46)
tlestang (45)

Top Issue Labels

bug (394)
difficulty: easy (238)
feature (205)
priority: low (82)
difficulty: medium (68)
priority: medium (61)
priority: high (51)
priority:medium (39)
difficulty: hard (30)
priority:high (26)
priority:low (25)
in-progress (21)
release blocker (13)
needs-reply (12)
CI/CD (10)
hacktoberfest (10)
solver (10)
ongoing (5)
hackathon (5)
help needed (5)
refactor (4)
dependencies (4)
plotting (2)
optimization (1)

Top Pull Request Labels

dependencies (82)
release blocker (18)
github_actions (6)
feature (2)
bug (2)
infrastructure (2)

Package metadata

Total packages: 2
Total downloads:
- pypi: 35,074 last-month
Total dependent packages: 4 (may contain duplicates)
Total dependent repositories: 13 (may contain duplicates)
Total versions: 78
Total maintainers: 1

pypi.org: pybamm

Python Battery Mathematical Modelling

Homepage: https://pybamm.org
Documentation: https://docs.pybamm.org
Licenses: Copyright (c) 2018-2025, the PyBaMM team. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Latest release: 25.4.2 (published 9 days ago)
Last Synced: 2025-04-26T15:03:12.845Z (about 11 hours ago)
Versions: 65
Dependent Packages: 4
Dependent Repositories: 13
Downloads: 35,074 Last month
Rankings:
- Stargazers count: 2.371%
- Forks count: 2.772%
- Average: 3.181%
- Dependent packages count: 3.242%
- Downloads: 3.453%
- Dependent repos count: 4.067%
Maintainers (1)
- pybamm-team

conda-forge.org: pybamm

Homepage: https://pybamm.org/
Licenses: BSD-3-Clause
Latest release: 0.2.0 (published about 5 years ago)
Last Synced: 2025-04-25T14:37:54.867Z (1 day ago)
Versions: 13
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Forks count: 10.691%
- Stargazers count: 16.471%
- Average: 28.091%
- Dependent repos count: 34.025%
- Dependent packages count: 51.175%

Dependencies

.github/workflows/benchmark_on_push.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite

.github/workflows/periodic_benchmarks.yml actions

actions/checkout v3 composite
actions/download-artifact v2 composite
actions/setup-python v4 composite
actions/upload-artifact v2 composite

.github/workflows/publish_pypi.yml actions

actions/cache v2 composite
actions/checkout v3 composite
actions/download-artifact v3 composite
actions/setup-python v4 composite
actions/upload-artifact v3 composite
pypa/gh-action-pypi-publish release/v1 composite

.github/workflows/run_benchmarks_over_history.yml actions

actions/checkout v3 composite
actions/download-artifact v3 composite
actions/setup-python v4 composite
actions/upload-artifact v3 composite

.github/workflows/test_on_push.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite
codecov/codecov-action v2.1.0 composite
fkirc/skip-duplicate-actions master composite

.github/workflows/update_license.yml actions

FantasticFiasco/action-update-license-year v2 composite
actions/checkout v3 composite

.github/workflows/update_version.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite
peter-evans/create-pull-request v3 composite
repo-sync/pull-request v2 composite

.github/workflows/validation_benchmarks.yml actions

mvasigh/dispatch-action main composite

.github/workflows/work_precision_sets.yml actions

actions/checkout v3 composite
actions/setup-python v4 composite
peter-evans/create-pull-request v3 composite

build_manylinux_wheels/action.yml actions

Dockerfile * docker

build_manylinux_wheels/Dockerfile docker

quay.io/pypa/manylinux2014_x86_64 2020-11-11-bc8ce45 build

setup.py pypi

Note *
Should *
anytree >=2.4.3
autograd >=1.2
bpx *
casadi >=3.5.0
imageio >=2.9.0
jupyter *
matplotlib >=2.0
numpy >=1.16
on *
outside *
pandas >=0.24
pybtex >=0.24.0
scikit-fem >=0.2.0
scipy >=1.3
sympy >=1.8

vcpkg.json vcpkg

casadi *
sundials *

.github/workflows/lychee_url_checker.yml actions

actions/cache v3 composite
actions/checkout v4 composite
lycheeverse/lychee-action v1.8.0 composite

.github/workflows/need_reply_remove.yml actions

octokit/request-action v2.x composite

.github/workflows/needs_reply.yml actions

dwieeb/needs-reply v2 composite

.github/workflows/release_reminder.yml actions

JasonEtco/create-an-issue v2 composite
actions/checkout v3 composite

.github/workflows/run_periodic_tests.yml actions

actions/checkout v4 composite
actions/setup-python v4 composite
codecov/codecov-action v3.1.4 composite
fkirc/skip-duplicate-actions master composite

scripts/Dockerfile docker

continuumio/miniconda3 latest build

docs/_static/versions.json meteor

Score: 22.632488391392908

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Sustainable Technology

PyBaMM

Keywords

Keywords from Contributors

Repository metadata

README.md

PyBaMM

💻 Using PyBaMM

Versioning

🚀 Installing PyBaMM

Using pip

Using conda

Optional solvers

📖 Citing PyBaMM

🛠️ Contributing to PyBaMM

📫 Get in touch

📃 License

✨ Contributors

Citation (CITATION.cff)

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

pypi.org: pybamm

conda-forge.org: pybamm

Dependencies