Skip to content

Fast and flexible physics-based battery models in Python

License

Notifications You must be signed in to change notification settings

singularzhen/PyBaMM

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PyBaMM_logo

Powered by NumFOCUS Scheduled readthedocs codecov Open In Colab DOI release code style

All Contributors

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, 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 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

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

πŸ“– πŸ› πŸ’»
Ankit Kumar
Ankit Kumar

πŸ’»
Aniket Singh Rawat
Aniket Singh Rawat

πŸ’» πŸ“–
Jerom Palimattom Tom
Jerom Palimattom Tom

πŸ“– πŸ’» ⚠️
Brady Planden
Brady Planden

πŸ’‘
jsbrittain
jsbrittain

πŸ’» ⚠️
Arjun
Arjun

πŸš‡ πŸ’» πŸ“– πŸ‘€
CHEN ZHAO
CHEN ZHAO

πŸ›
darryl-ad
darryl-ad

πŸ’» πŸ› πŸ€”
julian-evers
julian-evers

πŸ’»
Jason Siegel
Jason Siegel

πŸ’» πŸ€”
Tom Maull
Tom Maull

πŸ’» ⚠️
ejfdickinson
ejfdickinson

πŸ€” πŸ›
bobonice
bobonice

πŸ› πŸ’»
Eric G. Kratz
Eric G. Kratz

πŸ“– πŸš‡ πŸ› πŸ’» ⚠️
AndrΓ©s Ignacio Torres
AndrΓ©s Ignacio Torres

πŸš‡
Agnik Bakshi
Agnik Bakshi

πŸ“–
RuiheLi
RuiheLi

πŸ’» ⚠️
chmabaur
chmabaur

πŸ› πŸ’»
Abhishek Chaudhari
Abhishek Chaudhari

πŸ“– πŸ’»
Shubham Bhardwaj
Shubham Bhardwaj

πŸš‡
Jonathan Lauber
Jonathan Lauber

πŸš‡
Pradyot Ranjan
Pradyot Ranjan

πŸš‡ πŸ’» ⚠️
XuboGU
XuboGU

πŸ’» πŸ›
Ankit Meda
Ankit Meda

πŸ’»
Alessio Bugetti
Alessio Bugetti

πŸš‡ πŸ’» πŸ“– ⚠️
kawaMANMI
kawaMANMI

πŸ› πŸ’»
AKHIL SHARMA
AKHIL SHARMA

πŸ“–
Harshvir Sandhu
Harshvir Sandhu

πŸ’»

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

About

Fast and flexible physics-based battery models in Python

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Python 97.4%
  • C++ 2.1%
  • Other 0.5%