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.
# 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.
Metadata
Release files for pybamm 26.10.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pybamm-26.10.0.0.tar.gz | 813.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pybamm-26.10.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / pybamm-26.10.0.0.tar.gz
| Download URL | pybamm-26.10.0.0.tar.gz |
|---|---|
| Size | 813.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
09c069fd3a0a1dcf325942b9e9178eb192d1e08efdb2f21ce981458998de5634
|
|
BLAKE2b-256 checksum How to use checksums |
7521024f17fe6a0a09435804d2b1945b571dc59cc9a0c7bae16e35081632ce14
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency logRelease files / pybamm-26.10.0.0-py3-none-any.whl
| Download URL | pybamm-26.10.0.0-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c80ffecad4c1e649b0523ec0b91ed050d7436fdd132fa017e509cbec2cfed91a
|
|
BLAKE2b-256 checksum How to use checksums |
364cb80f9679dd730b71d9be0ed864e4125d80e8b3f15cd6d8e3ee76ff4086f7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 9, 2026.
Transparency log
