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

closember photovoltaic jax pde solar astropy cookiecutter-template cookiecutter-python cookiecutter partial-differential-equations

Last synced: about 16 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 7 years ago)
Default Branch: main
Last Pushed: 2026-07-01T20:00:05.000Z (3 days ago)
Last Synced: 2026-07-03T21:35:17.611Z (about 16 hours ago)
Topics: batteries, battery-models, hacktoberfest, pybamm, python, simulation, solvers
Language: Python
Homepage: https://www.pybamm.org/
Size: 197 MB
Stars: 1,603
Watchers: 28
Forks: 784
Open Issues: 239
Releases: 71
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)
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 main branch are tested on the latest commit. If you are using an older version of PyBaMM from pip, you can switch to the corresponding release tag on GitHub to see the version of the examples that is compatible with that release.

Versioning

PyBaMM uses CalVer. Version numbers take the form YY.MM.N.P, where YY.MM is the year and month of the release, N is the feature release within that month (0 for the first), and P is the patch level (0 for the feature release itself). For example, 27.1.0.1 is the first patch of the first feature release in January 2027.

Releases ship when there's something worth releasing, not on a fixed schedule. Any release may contain breaking changes; when it does, they appear under a ## Breaking changes section at the top of CHANGELOG.md. Public APIs that are removed or renamed ship a DeprecationWarning for at least two prior feature releases first, where technically possible.

See RELEASE.md for the full release policy, including how we define "public API" and what counts as a breaking change.

🚀 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.

[!NOTE]
PyBaMM versions between 24.11.2 and 25.6 (not including these boundary versions) are not available on conda-forge.

# for no extra dependencies
conda install -c conda-forge pybamm-base
# for all extra dependencies except jax
conda install -c conda-forge pybamm
# optionally install jax >=0.7.0, <0.9.0 on python >=3.11
conda install -c conda-forge "jax>=0.7.0,<0.9.0"

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.

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: "26.4.3"
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: 24
Last ynced at: 2026-05-03T19:33:42.471Z
Profile URL: https://github.com/pybamm-team

GitHub Events

Total

Create event: 166
Release event: 8
Issues event: 300
Watch event: 262
Delete event: 154
Member event: 1
Issue comment event: 1534
Push event: 587
Pull request review comment event: 990
Pull request review event: 1308
Pull request event: 661
Fork event: 120

Last Year

Create event: 166
Release event: 8
Issues event: 300
Watch event: 262
Delete event: 154
Member event: 1
Issue comment event: 1534
Push event: 587
Pull request review comment event: 990
Pull request review event: 1308
Pull request event: 661
Fork event: 120

Committers metadata

Last synced: 3 days ago

Total Commits: 12,303
Total Committers: 146
Avg Commits per committer: 84.267
Development Distribution Score (DDS): 0.689

Commits in past year: 467
Committers in past year: 31
Avg Commits per committer in past year: 15.065
Development Distribution Score (DDS) in past year: 0.814

Name	Email	Commits
Valentin Sulzer	v**r@h**m	3832
Martin Robinson	m**s@g**m	884
Robert Timms	t**s@m**k	866
Scottmar93	m**s@m**k	820
Ferran Brosa Planella	F**a@w**k	792
Agriya Khetarpal	7****l	719
Thibault Lestang	t**g@c**k	434
Saransh Chopra	s**1@g**m	365
pre-commit-ci[bot]	6****]	328
arjxn.py	a**y@g**m	297
Eric G. Kratz	k****n	220
Priyanshu Agarwal	p**6@g**m	212
allcontributors[bot]	4****]	192
DrSOKane	s**e@i**k	155
Elias Hohl	e**l@a**m	137
dependabot[bot]	4****]	126
John Brittain	j**2@g**m	115
Brady Planden	5****n	108
tobykirk	t**k@m**k	92
tomtranter	t**r@g**m	91
Marc Berliner	3****r	90
Pip Liggins	p**s@d**k	90
Alec Bills	4****s	81
Valentin Sulzer	s**r@m**k	81
Weilong	w**i@i**k	77
Vaibhav	n**t@g**m	70
Alexander Bills	a**s@a**u	65
medha-14	m**4@g**m	58
Diego	d**z@i**k	50
Jerom Palimattom Tom	8****m	49
and 116 more...

Committer domains:

Issue and Pull Request metadata

Last synced: about 16 hours ago

Total issues: 1,686
Total pull requests: 3,237
Average time to close issues: 3 months
Average time to close pull requests: 14 days
Total issue authors: 253
Total pull request authors: 159
Average comments per issue: 2.61
Average comments per pull request: 2.66
Merged pull request: 2,680
Bot issues: 18
Bot pull requests: 601

Past year issues: 52
Past year pull requests: 243
Past year average time to close issues: 10 days
Past year average time to close pull requests: 5 days
Past year issue authors: 33
Past year pull request authors: 33
Past year average comments per issue: 1.02
Past year average comments per pull request: 1.49
Past year merged pull request: 133
Past year bot issues: 1
Past year bot pull requests: 64

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

Top Issue Authors

tinosulzer (369)
rtimms (172)
martinjrobins (152)
brosaplanella (127)
Scottmar93 (102)
Saransh-cpp (62)
agriyakhetarpal (61)
TomTranter (37)
ejfdickinson (21)
gyouhoc (18)
BradyPlanden (16)
github-actions[bot] (16)
valentinsulzer (15)
kratman (14)
DavidMStraub (12)

Top Pull Request Authors

tinosulzer (544)
kratman (267)
rtimms (210)
pre-commit-ci[bot] (200)
allcontributors[bot] (176)
dependabot[bot] (164)
agriyakhetarpal (134)
martinjrobins (133)
brosaplanella (109)
Saransh-cpp (87)
MarcBerliner (82)
aabills (69)
prady0t (63)
Scottmar93 (62)
github-actions[bot] (61)

Top Issue Labels

bug (372)
feature (215)
difficulty: easy (215)
priority: low (74)
difficulty: medium (58)
priority: medium (50)
priority: high (40)
priority:medium (36)
hacktoberfest (33)
difficulty: hard (28)
priority:high (24)
priority:low (23)
in-progress (21)
needs-reply (14)
solver (14)
CI/CD (8)
release blocker (8)
help needed (5)
ongoing (5)
hackathon (5)
dependencies (4)
refactor (4)
good first issue (3)
optimization (2)
github_actions (1)

Top Pull Request Labels

dependencies (166)
github_actions (52)
release blocker (28)
python:uv (13)
GSoC 2025 (5)
feature (3)
infrastructure (2)
bug (2)
needs-reply (1)

Package metadata

Total packages: 4
Total downloads:
- conda: 379,892 total
- pypi: 122,902 last-month
Total dependent packages: 4 (may contain duplicates)
Total dependent repositories: 13 (may contain duplicates)
Total versions: 170
Total maintainers: 1

pypi.org: pybamm

Python Battery Mathematical Modelling

Homepage: https://pybamm.org
Documentation: https://docs.pybamm.org
Licenses: BSD License
Latest release: 26.5.0 (published about 1 month ago)
Last Synced: 2026-07-01T21:02:46.371Z (3 days ago)
Versions: 85
Dependent Packages: 4
Dependent Repositories: 13
Downloads: 122,902 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

proxy.golang.org: github.com/pybamm-team/pybamm

Homepage:
Documentation: https://pkg.go.dev/github.com/pybamm-team/pybamm#section-documentation
Licenses: bsd-3-clause
Latest release: v26.5.0+incompatible (published about 1 month ago)
Last Synced: 2026-07-01T21:02:46.145Z (3 days ago)
Versions: 36
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 5.395%
- Average: 5.576%
- Dependent repos count: 5.758%

proxy.golang.org: github.com/pybamm-team/PyBaMM

Homepage:
Documentation: https://pkg.go.dev/github.com/pybamm-team/PyBaMM#section-documentation
Licenses: bsd-3-clause
Latest release: v26.5.0+incompatible (published about 1 month ago)
Last Synced: 2026-07-01T21:02:46.427Z (3 days ago)
Versions: 36
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Dependent packages count: 5.395%
- Average: 5.576%
- Dependent repos count: 5.758%

conda-forge.org: pybamm

Homepage: https://pybamm.org/
Licenses: BSD-3-Clause
Latest release: 0.2.0 (published about 6 years ago)
Last Synced: 2026-03-19T23:15:57.309Z (4 months ago)
Versions: 13
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 379,892 Total
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: 25.63018546028547

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

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

proxy.golang.org: github.com/pybamm-team/pybamm

proxy.golang.org: github.com/pybamm-team/PyBaMM

conda-forge.org: pybamm

Dependencies