Skip to main content

Python Battery Mathematical Modelling.

Project description

PyBaMM_logo

Build readthedocs codecov Open In Colab DOI release black code style

All Contributors

PyBaMM

PyBaMM (Python Battery Mathematical Modelling) solves physics-based electrochemical DAE models by using state-of-the-art automatic differentiation and numerical solvers. The Doyle-Fuller-Newman model can be solved in under 0.1 seconds, while the reduced-order Single Particle Model and Single Particle Model with electrolyte can be solved in just a few milliseconds. Additional physics can easily be included such as thermal effects, fast particle diffusion, 3D effects, and more. All models are implemented in a flexible manner, and a wide range of models and parameter sets (NCA, NMC, LiCoO2, ...) are available. There is also functionality to simulate any set of experimental instructions, such as CCCV or GITT, or specify drive cycles.

๐Ÿ’ป 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 CCCV:

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.CasadiSolver())
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 uses CalVer, which means that we make new releases every month with the version number YY.MM. 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 (12 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

pypi downloads

pip install pybamm

Using conda

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

conda_forge downloads

conda install -c conda-forge pybamm

Optional solvers

Following GNU/Linux and macOS solvers are optionally available:

๐Ÿ“– 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 see the contact page.

๐Ÿ“ƒ License

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

โœจ Contributors

Thanks goes to these wonderful people (emoji key):

Valentin Sulzer
Valentin Sulzer

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿšง ๐Ÿ‘€ โš ๏ธ โœ… ๐Ÿ“
Robert Timms
Robert Timms

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿšง ๐Ÿ‘€ โš ๏ธ โœ…
Scott Marquis
Scott Marquis

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿšง ๐Ÿ‘€ โš ๏ธ โœ…
Martin Robinson
Martin Robinson

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿ‘€ โš ๏ธ โœ…
Ferran Brosa Planella
Ferran Brosa Planella

๐Ÿ‘€ ๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿšง โš ๏ธ โœ… ๐Ÿ“
Tom Tranter
Tom Tranter

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿ‘€ โš ๏ธ โœ…
Thibault Lestang
Thibault Lestang

๐Ÿ› ๐Ÿ’ป ๐Ÿ“– ๐Ÿ’ก ๐Ÿค” ๐Ÿ‘€ โš ๏ธ ๐Ÿš‡
Diego
Diego

๐Ÿ› ๐Ÿ‘€ ๐Ÿ’ป ๐Ÿš‡
felipe-salinas
felipe-salinas

๐Ÿ’ป โš ๏ธ
suhaklee
suhaklee

๐Ÿ’ป โš ๏ธ
viviantran27
viviantran27

๐Ÿ’ป โš ๏ธ
gyouhoc
gyouhoc

๐Ÿ› ๐Ÿ’ป โš ๏ธ
Yannick Kuhn
Yannick Kuhn

๐Ÿ’ป โš ๏ธ
Jacqueline Edge
Jacqueline Edge

๐Ÿค” ๐Ÿ“‹ ๐Ÿ”
Fergus Cooper
Fergus Cooper

๐Ÿ’ป โš ๏ธ
jonchapman1
jonchapman1

๐Ÿค” ๐Ÿ”
Colin Please
Colin Please

๐Ÿค” ๐Ÿ”
cwmonroe
cwmonroe

๐Ÿค” ๐Ÿ”
Greg
Greg

๐Ÿค” ๐Ÿ”
Faraday Institution
Faraday Institution

๐Ÿ’ต
Alexander Bessman
Alexander Bessman

๐Ÿ› ๐Ÿ’ก
dalbamont
dalbamont

๐Ÿ’ป
Anand Mohan Yadav
Anand Mohan Yadav

๐Ÿ“–
WEILONG AI
WEILONG AI

๐Ÿ’ป ๐Ÿ’ก โš ๏ธ
lonnbornj
lonnbornj

๐Ÿ’ป โš ๏ธ ๐Ÿ’ก
Priyanshu Agarwal
Priyanshu Agarwal

โš ๏ธ ๐Ÿ’ป ๐Ÿ› ๐Ÿ‘€ ๐Ÿšง โœ…
DrSOKane
DrSOKane

๐Ÿ’ป ๐Ÿ’ก ๐Ÿ“– โš ๏ธ โœ…
Saransh Chopra
Saransh Chopra

๐Ÿ’ป โš ๏ธ ๐Ÿ“– โœ… ๐Ÿ‘€ ๐Ÿšง
David Straub
David Straub

๐Ÿ› ๐Ÿ’ป
maurosgroi
maurosgroi

๐Ÿค”
Amarjit Singh Gaba
Amarjit Singh Gaba

๐Ÿ’ป
KennethNwanoro
KennethNwanoro

๐Ÿ’ป โš ๏ธ
Ali Hussain Umar Bhatti
Ali Hussain Umar Bhatti

๐Ÿ’ป โš ๏ธ
Leshinka Molel
Leshinka Molel

๐Ÿ’ป ๐Ÿค”
tobykirk
tobykirk

๐Ÿค” ๐Ÿ’ป โš ๏ธ โœ…
Chuck Liu
Chuck Liu

๐Ÿ› ๐Ÿ’ป
partben
partben

๐Ÿ“–
Gavin Wiggins
Gavin Wiggins

๐Ÿ› ๐Ÿ’ป
Dion Wilde
Dion Wilde

๐Ÿ› ๐Ÿ’ป
Elias Hohl
Elias Hohl

๐Ÿ’ป
KAschad
KAschad

๐Ÿ›
Vaibhav-Chopra-GT
Vaibhav-Chopra-GT

๐Ÿ’ป
bardsleypt
bardsleypt

๐Ÿ› ๐Ÿ’ป
ndrewwang
ndrewwang

๐Ÿ› ๐Ÿ’ป
MichaPhilipp
MichaPhilipp

๐Ÿ›
Alec Bills
Alec Bills

๐Ÿ’ป
Agriya Khetarpal
Agriya Khetarpal

๐Ÿš‡ ๐Ÿ’ป
Alex Wadell
Alex Wadell

๐Ÿ’ป โš ๏ธ ๐Ÿ“–
iatzak
iatzak

๐Ÿ“–

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pybamm-22.12.tar.gz (990.8 kB view hashes)

Uploaded Source

Built Distributions

pybamm-22.12-cp39-cp39-win_amd64.whl (2.4 MB view hashes)

Uploaded CPython 3.9 Windows x86-64

pybamm-22.12-cp39-cp39-manylinux2010_x86_64.whl (14.2 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ x86-64

pybamm-22.12-cp39-cp39-manylinux2010_i686.whl (11.4 MB view hashes)

Uploaded CPython 3.9 manylinux: glibc 2.12+ i686

pybamm-22.12-cp39-cp39-macosx_10_9_x86_64.whl (4.9 MB view hashes)

Uploaded CPython 3.9 macOS 10.9+ x86-64

pybamm-22.12-cp38-cp38-win_amd64.whl (2.4 MB view hashes)

Uploaded CPython 3.8 Windows x86-64

pybamm-22.12-cp38-cp38-manylinux2010_x86_64.whl (14.2 MB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ x86-64

pybamm-22.12-cp38-cp38-manylinux2010_i686.whl (11.4 MB view hashes)

Uploaded CPython 3.8 manylinux: glibc 2.12+ i686

pybamm-22.12-cp38-cp38-macosx_10_9_x86_64.whl (4.9 MB view hashes)

Uploaded CPython 3.8 macOS 10.9+ x86-64

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page