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 6 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 (about 8 years ago)
Default Branch: main
Last Pushed: 2026-11-06T20:16:30.000Z (2 days ago)
Last Synced: 2026-11-08T08:32:24.324Z (about 6 hours ago)
Topics: batteries, battery-models, hacktoberfest, pybamm, python, simulation, solvers
Language: Python
Homepage: https://www.pybamm.org/
Size: 209 MB
Stars: 1,726
Watchers: 28
Forks: 834
Open Issues: 316
Releases: 88
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
- Code of conduct: CODE-OF-CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
- Claude: CLAUDE.md
- Gemini: GEMINI.md
- Cursor: .cursorrules
- Copilot: .github/copilot-instructions.md

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 (https://github.com/pybamm-team/PyBaMM/blob/main/)

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: 25
Last ynced at: 2026-11-06T16:13:35.778Z
Profile URL: https://github.com/pybamm-team

GitHub Events

Total

Release event: 12
Delete event: 248
Member event: 1
Pull request event: 758
Fork event: 130
Issues event: 363
Watch event: 314
Issue comment event: 1638
Push event: 985
Pull request review comment event: 1036
Pull request review event: 1409
Create event: 277

Last Year

Release event: 4
Delete event: 103
Pull request event: 137
Fork event: 20
Issues event: 73
Watch event: 75
Issue comment event: 150
Push event: 437
Pull request review event: 135
Pull request review comment event: 66
Create event: 121

Committers metadata

Last synced: 1 day ago

Total Commits: 12,516
Total Committers: 156
Avg Commits per committer: 80.231
Development Distribution Score (DDS): 0.694

Commits in past year: 502
Committers in past year: 37
Avg Commits per committer in past year: 13.568
Development Distribution Score (DDS) in past year: 0.721

Name	Email	Commits
Valentin Sulzer	v**r@h**m	3833
Robert Timms	t**s@m**k	894
Martin Robinson	m**s@g**m	887
Scottmar93	m**s@m**k	820
Ferran Brosa Planella	F**a@w**k	795
Agriya Khetarpal	7****l	719
Thibault Lestang	t**g@c**k	434
Saransh Chopra	s**1@g**m	366
pre-commit-ci[bot]	6****]	342
arjxn.py	a**y@g**m	297
Eric G. Kratz	k****n	220
Priyanshu Agarwal	p**6@g**m	212
allcontributors[bot]	4****]	192
Brady Planden	5****n	167
dependabot[bot]	4****]	166
DrSOKane	s**e@i**k	155
Elias Hohl	e**l@a**m	137
John Brittain	j**2@g**m	115
Alec Bills	4****s	104
Marc Berliner	3****r	100
Pip Liggins	p**s@d**k	93
tobykirk	t**k@m**k	92
tomtranter	t**r@g**m	92
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 126 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 1,758
Total pull requests: 3,629
Average time to close issues: 3 months
Average time to close pull requests: 17 days
Total issue authors: 270
Total pull request authors: 190
Average comments per issue: 2.56
Average comments per pull request: 2.56
Merged pull request: 2,953
Bot issues: 19
Bot pull requests: 684

Past year issues: 88
Past year pull requests: 535
Past year average time to close issues: 30 days
Past year average time to close pull requests: 11 days
Past year issue authors: 35
Past year pull request authors: 64
Past year average comments per issue: 0.94
Past year average comments per pull request: 1.65
Past year merged pull request: 352
Past year bot issues: 1
Past year bot pull requests: 123

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

Top Issue Authors

tinosulzer (369)
rtimms (182)
martinjrobins (152)
brosaplanella (134)
Scottmar93 (102)
Saransh-cpp (62)
agriyakhetarpal (61)
TomTranter (37)
BradyPlanden (26)
ejfdickinson (23)
gyouhoc (18)
github-actions[bot] (17)
valentinsulzer (15)
kratman (14)
mleot (13)

Top Pull Request Authors

tinosulzer (544)
kratman (267)
rtimms (255)
dependabot[bot] (223)
pre-commit-ci[bot] (219)
allcontributors[bot] (176)
BradyPlanden (148)
martinjrobins (137)
agriyakhetarpal (134)
aabills (121)
brosaplanella (115)
MarcBerliner (110)
Saransh-cpp (89)
github-actions[bot] (66)
prady0t (64)

Top Issue Labels

bug (406)
feature (223)
difficulty: easy (215)
priority: low (74)
difficulty: medium (59)
priority: medium (52)
priority: high (40)
priority:medium (36)
hacktoberfest (33)
difficulty: hard (28)
priority:high (24)
priority:low (23)
in-progress (21)
solver (17)
needs-reply (14)
CI/CD (8)
release blocker (8)
ongoing (5)
help needed (5)
hackathon (5)
refactor (4)
dependencies (4)
good first issue (3)
optimization (2)
area: feature request :bulb: (1)
theme: front (1)
github_actions (1)
resolution: should go to blueprint (1)
area: stale (1)

Top Pull Request Labels

dependencies (225)
github_actions (76)
python:uv (47)
release blocker (28)
GSoC 2025 (5)
feature (3)
infrastructure (3)
bug (2)
docker (1)
needs-reply (1)
solver (1)

Package metadata

Total packages: 4
Total downloads:
- conda: 379,892 total
- pypi: 54,254 last-month
Total dependent packages: 4 (may contain duplicates)
Total dependent repositories: 13 (may contain duplicates)
Total versions: 177
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.10.1.1 (published 19 days ago)
Last Synced: 2026-11-06T16:17:50.447Z (2 days ago)
Versions: 92
Dependent Packages: 4
Dependent Repositories: 13
Downloads: 54,254 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 5 months ago)
Last Synced: 2026-11-07T08:14:27.289Z (1 day 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 5 months ago)
Last Synced: 2026-11-07T08:22:18.156Z (1 day 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 over 6 years ago)
Last Synced: 2026-03-19T23:15:57.309Z (8 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/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/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/validation_benchmarks.yml actions

mvasigh/dispatch-action main composite

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

.github/workflows/benchmarks_track.yml actions

actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
actions/github-script 3a2844b7e9c422d3c10d287c895573f7108da1b3 composite
bencherdev/bencher 4c83b25441d145ee273adaf74be30f2382e6ba85 composite

.github/workflows/benchmarks_pr.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
actions/upload-artifact 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a composite
dorny/paths-filter 7b450fff21473bca461d4b92ce414b9d0420d706 composite

.github/workflows/benchmarks_main.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
bencherdev/bencher 4c83b25441d145ee273adaf74be30f2382e6ba85 composite

packages/pybamm/tests/benchmarks/Dockerfile docker

python 3.13-slim-bookworm build

packages/pybammsolvers/pyproject.toml pypi

casadi ==3.7.2
numpy >=2.0.0

.github/workflows/_build_solver_wheels.yml actions

actions/cache 55cc8345863c7cc4c66a329aec7e433d2d1c52a9 composite
actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/setup-python 5fda3b95a4ea91299a34e894583c3862153e4b97 composite
actions/upload-artifact 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a composite

.github/workflows/discussion_autoresponder.yml actions

actions/github-script 3a2844b7e9c422d3c10d287c895573f7108da1b3 composite

pyproject.toml pypi

uv.lock pypi

225 dependencies

.github/workflows/_nox.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
actions/setup-python 5fda3b95a4ea91299a34e894583c3862153e4b97 composite
astral-sh/setup-uv c771a70e6277c0a99b617c7a806ffedaca235ff9 composite
awalsh128/cache-apt-pkgs-action 553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 composite
codecov/codecov-action fb8b3582c8e4def4969c97caa2f19720cb33a72f composite

.github/workflows/docker.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
docker/build-push-action 53b7df96c91f9c12dcc8a07bcb9ccacbed38856a composite
docker/login-action dbcb813823bdd20940b903addbd779551569679f composite
docker/setup-buildx-action bb05f3f5519dd87d3ba754cc423b652a5edd6d2c composite
docker/setup-qemu-action 96fe6ef7f33517b61c61be40b68a1882f3264fb8 composite

.github/workflows/scorecard.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/upload-artifact 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a composite
github/codeql-action/upload-sarif 5595ccaf912efad79be6eef63a5619ff05969be3 composite
ossf/scorecard-action 2d1146689b8cda280b9bc96326124645441f03bc composite

packages/pybamm/pyproject.toml pypi

anytree >=2.8.0
black *
numpy >=2.0.0
pandas >=1.5.0
platformdirs *
pooch >=1.8.1
posthog *
pybammsolvers >=0.9.0,<0.10.0
pyyaml *
scipy >=1.11.4,!=1.18.0
sympy >=1.12
typing-extensions >=4.16.0
xarray >=2022.6.0

packages/pybammsolvers/vcpkg.json vcpkg

casadi *
sundials *

.github/workflows/release_solvers.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
pypa/gh-action-pypi-publish dc37677b2e1c63e2034f94d8a5b11f265b73ba33 composite

.github/workflows/model_zoo_status.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c composite
actions/setup-python 5fda3b95a4ea91299a34e894583c3862153e4b97 composite
actions/upload-artifact 043fb46d1a93c77aae656e7c1c64a875d1fc6a0a composite
astral-sh/setup-uv c771a70e6277c0a99b617c7a806ffedaca235ff9 composite
awalsh128/cache-apt-pkgs-action 553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 composite

packages/pybamm-model-zoo/pyproject.toml pypi

packaging >=23.0
pybamm *
tomli >=2.0.1; python_version < '3.11'

.github/workflows/release_model_zoo.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/download-artifact 9000827ccba6bdab643e8b6fd33ac0654aef8333 composite
actions/upload-artifact cf430e030ddbb5b0abf93d22962f4752f3646cd9 composite
astral-sh/setup-uv c18668ad3cf93ea998bef934396af7bb5c839dc7 composite
pypa/gh-action-pypi-publish dc37677b2e1c63e2034f94d8a5b11f265b73ba33 composite

.github/workflows/clang_tidy.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
actions/setup-python 5fda3b95a4ea91299a34e894583c3862153e4b97 composite
astral-sh/setup-uv 1c37ad07a6a961277cf70c0d37d6f313000f5884 composite
github/codeql-action/upload-sarif 24c54180a607b1449ed407dd24f251e4e9147c8d composite

.github/workflows/codeql.yml actions

actions/checkout 3d3c42e5aac5ba805825da76410c181273ba90b1 composite
github/codeql-action/analyze 24c54180a607b1449ed407dd24f251e4e9147c8d composite
github/codeql-action/init 24c54180a607b1449ed407dd24f251e4e9147c8d composite

Score: 25.651738715975938

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 (https://github.com/pybamm-team/PyBaMM/blob/main/)

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