pybamm
Fast and flexible physics-based battery models in Python
Science Score: 77.0%
This score indicates how likely this project is to be science-related based on various indicators:
-
✓CITATION.cff file
Found CITATION.cff file -
✓codemeta.json file
Found codemeta.json file -
✓.zenodo.json file
Found .zenodo.json file -
✓DOI references
Found 4 DOI reference(s) in README -
✓Academic publication links
Links to: zenodo.org -
✓Committers with academic emails
22 of 135 committers (16.3%) from academic institutions -
○Institutional organization owner
-
○JOSS paper metadata
-
○Scientific vocabulary similarity
Low similarity (16.2%) to scientific vocabulary
Keywords
Keywords from Contributors
Repository
Fast and flexible physics-based battery models in Python
Basic Info
- Host: GitHub
- Owner: pybamm-team
- License: bsd-3-clause
- Language: Python
- Default Branch: develop
- Homepage: https://www.pybamm.org/
- Size: 188 MB
Statistics
- Stars: 1,361
- Watchers: 29
- Forks: 666
- Open Issues: 189
- Releases: 56
Topics
Metadata Files
README.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:
```python 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:
```python 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 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
bash
pip install pybamm
Using conda
PyBaMM is available as a conda package through the conda-forge channel.
bash
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
python
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.
Owner
- Name: PyBaMM Team
- Login: pybamm-team
- Kind: organization
- Website: https://www.pybamm.org/
- Twitter: pybamm_
- Repositories: 24
- Profile: https://github.com/pybamm-team
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.8.0"
repository-code: "https://github.com/pybamm-team/PyBaMM"
title: "Python Battery Mathematical Modelling (PyBaMM)"
Committers
Last synced: 7 months ago
Top Committers
| Name | Commits | |
|---|---|---|
| Valentin Sulzer | v****r@h****m | 3,828 |
| Martin Robinson | m****s@g****m | 879 |
| Robert Timms | t****s@m****k | 826 |
| Scottmar93 | m****s@m****k | 820 |
| Ferran Brosa Planella | F****a@w****k | 791 |
| 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****] | 296 |
| Priyanshu Agarwal | p****6@g****m | 212 |
| allcontributors[bot] | 4****] | 192 |
| Eric G. Kratz | k****n | 189 |
| 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 | 81 |
| Weilong | w****i@i****k | 77 |
| dependabot[bot] | 4****] | 74 |
| Vaibhav | n****t@g****m | 70 |
| Alexander Bills | a****s@a****u | 65 |
| Alec Bills | a****s@g****m | 53 |
| 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 |
| and 105 more... | ||
Committer Domains (Top 20 + Academic)
Issues and Pull Requests
Last synced: 6 months ago
All Time
- Total issues: 1,659
- Total pull requests: 3,047
- Average time to close issues: 3 months
- Average time to close pull requests: 15 days
- Total issue authors: 241
- Total pull request authors: 143
- Average comments per issue: 2.61
- Average comments per pull request: 2.72
- Merged pull requests: 2,575
- Bot issues: 17
- Bot pull requests: 551
Past Year
- Issues: 203
- Pull requests: 774
- Average time to close issues: 18 days
- Average time to close pull requests: 8 days
- Issue authors: 74
- Pull request authors: 45
- Average comments per issue: 1.17
- Average comments per pull request: 2.4
- Merged pull requests: 583
- Bot issues: 4
- Bot pull requests: 187
Top Authors
Issue Authors
- tinosulzer (369)
- rtimms (169)
- martinjrobins (148)
- brosaplanella (125)
- Scottmar93 (102)
- Saransh-cpp (63)
- agriyakhetarpal (61)
- TomTranter (36)
- ejfdickinson (19)
- gyouhoc (18)
- github-actions[bot] (16)
- BradyPlanden (16)
- valentinsulzer (15)
- kratman (14)
- DavidMStraub (12)
Pull Request Authors
- tinosulzer (544)
- kratman (268)
- rtimms (184)
- pre-commit-ci[bot] (183)
- allcontributors[bot] (176)
- agriyakhetarpal (132)
- dependabot[bot] (131)
- martinjrobins (128)
- brosaplanella (109)
- Saransh-cpp (87)
- MarcBerliner (64)
- prady0t (63)
- Scottmar93 (62)
- github-actions[bot] (61)
- aabills (57)
Top Labels
Issue Labels
Pull Request Labels
Packages
- Total packages: 4
-
Total downloads:
- pypi 29,923 last-month
-
Total dependent packages: 4
(may contain duplicates) -
Total dependent repositories: 13
(may contain duplicates) - Total versions: 124
- Total maintainers: 1
pypi.org: pybamm
Python Battery Mathematical Modelling
- Homepage: https://pybamm.org
- Documentation: https://docs.pybamm.org
- License: 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.8.0
published 7 months ago
Rankings
Maintainers (1)
proxy.golang.org: github.com/pybamm-team/PyBaMM
- Documentation: https://pkg.go.dev/github.com/pybamm-team/PyBaMM#section-documentation
- License: bsd-3-clause
-
Latest release: v25.8.0+incompatible
published 7 months ago
Rankings
proxy.golang.org: github.com/pybamm-team/pybamm
- Documentation: https://pkg.go.dev/github.com/pybamm-team/pybamm#section-documentation
- License: bsd-3-clause
-
Latest release: v25.8.0+incompatible
published 7 months ago
Rankings
conda-forge.org: pybamm
- Homepage: https://pybamm.org/
- License: BSD-3-Clause
-
Latest release: 0.2.0
published almost 6 years ago
Rankings
Dependencies
- actions/checkout v3 composite
- actions/setup-python v4 composite
- actions/checkout v3 composite
- actions/download-artifact v2 composite
- actions/setup-python v4 composite
- actions/upload-artifact v2 composite
- 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
- actions/checkout v3 composite
- actions/download-artifact v3 composite
- actions/setup-python v4 composite
- actions/upload-artifact v3 composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- codecov/codecov-action v2.1.0 composite
- fkirc/skip-duplicate-actions master composite
- FantasticFiasco/action-update-license-year v2 composite
- actions/checkout v3 composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- peter-evans/create-pull-request v3 composite
- repo-sync/pull-request v2 composite
- mvasigh/dispatch-action main composite
- actions/checkout v3 composite
- actions/setup-python v4 composite
- peter-evans/create-pull-request v3 composite
- Dockerfile * docker
- quay.io/pypa/manylinux2014_x86_64 2020-11-11-bc8ce45 build
- 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
- casadi *
- sundials *
- actions/cache v3 composite
- actions/checkout v4 composite
- lycheeverse/lychee-action v1.8.0 composite
- octokit/request-action v2.x composite
- dwieeb/needs-reply v2 composite
- JasonEtco/create-an-issue v2 composite
- actions/checkout v3 composite
- actions/checkout v4 composite
- actions/setup-python v4 composite
- codecov/codecov-action v3.1.4 composite
- fkirc/skip-duplicate-actions master composite
- continuumio/miniconda3 latest build