Package: pybamm
PyBaMMPyBaMM (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 anopen governance modeland is fiscally sponsored byNumFOCUS. Consider making
atax-deductible donationto help the project
pay for developer time, professional services, travel, workshops, and a variety of other needs.💻 Using PyBaMMThe easiest way to use PyBaMM is to run a 1C constant-current discharge with a model of your choice with all the default settings:importpybammmodel=pybamm.lithium_ion.DFN()# Doyle-Fuller-Newman modelsim=pybamm.Simulation(model)sim.solve([0,3600])# solve for 1 hoursim.plot()or simulate an experiment such as a constant-current discharge followed by a constant-current-constant-voltage charge:importpybammexperiment=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 DFNscriptornotebook).For new users we recommend theGetting Startedguides. 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 throughGoogle Colab.Further details can be found in a number ofdetailed examples, hosted here on
github. In addition, there is afull API documentation,
hosted onRead The Docs.
Additional supporting material can be foundhere.Note that the examples on the defaultdevelopbranch are tested on the latestdevelopcommit. This may sometimes cause errors when running the examples on the pybamm pip package, which is synced to themainbranch. You can switch to themainbranch on github to see the version of the examples that is compatible with the latest pip release.VersioningPyBaMM makes releases every four months and we useCalVer, which means that the version number isYY.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 theCHANGELOG, 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 onGitHub.🚀 Installing PyBaMMPyBaMM 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, seethe documentation.Using pippipinstallpybammUsing condaPyBaMM is available as a conda package through the conda-forge channel.condainstall-cconda-forgepybammOptional solversFollowing GNU/Linux and macOS solvers are optionally available:scikits.odes-based solver, seethe documentation.jax-based solver, seethe documentation.📖 Citing PyBaMMIf you use PyBaMM in your work, please cite our paperSulzer, 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 linepybamm.print_citations()to the end of your script. This will print BibTeX information to the terminal; passing a filename toprint_citationswill print the BibTeX information to the specified file instead. A list of all citations can also be found in thecitations file. In particular, PyBaMM relies heavily onCasADi.
SeeCONTRIBUTING.mdfor information on how to add your own citations when you contribute.🛠️ Contributing to PyBaMMIf you'd like to help us develop PyBaMM by adding new methods, writing documentation, or fixing embarrassing bugs, please have a look at theseguidelinesfirst.📫 Get in touchFor any questions, comments, suggestions or bug reports, please see thecontact page.📃 LicensePyBaMM is fully open source. For more information about its license, seeLICENSE.✨ ContributorsThanks goes to these wonderful people (emoji key):Valentin Sulzer🐛💻📖💡🤔🚧👀⚠️✅📝Robert Timms🐛💻📖💡🤔🚧👀⚠️✅Scott Marquis🐛💻📖💡🤔🚧👀⚠️✅Martin Robinson🐛💻📖💡🤔👀⚠️✅Ferran Brosa Planella👀🐛💻📖💡🤔🚧⚠️✅📝Tom Tranter🐛💻📖💡🤔👀⚠️✅Thibault Lestang🐛💻📖💡🤔👀⚠️🚇Diego🐛👀💻🚇felipe-salinas💻⚠️suhaklee💻⚠️viviantran27💻⚠️gyouhoc🐛💻⚠️Yannick Kuhn💻⚠️Jacqueline Edge🤔📋🔍Fergus Cooper💻⚠️jonchapman1🤔🔍Colin Please🤔🔍cwmonroe🤔🔍Greg🤔🔍Faraday Institution💵Alexander Bessman🐛💡dalbamont💻Anand Mohan Yadav📖WEILONG AI💻💡⚠️lonnbornj💻⚠️💡Priyanshu Agarwal⚠️💻🐛👀🚧✅DrSOKane💻💡📖⚠️✅👀Saransh Chopra💻⚠️📖✅👀🚧David Straub🐛💻maurosgroi🤔Amarjit Singh Gaba💻KennethNwanoro💻⚠️Ali Hussain Umar Bhatti💻⚠️Leshinka Molel💻🤔tobykirk🤔💻⚠️✅Chuck Liu🐛💻partben📖Gavin Wiggins🐛💻Dion Wilde🐛💻Elias Hohl💻KAschad🐛Vaibhav-Chopra-GT💻bardsleypt🐛💻ndrewwang🐛💻MichaPhilipp🐛Alec Bills💻Agriya Khetarpal🚇💻📖👀Alex Wadell💻⚠️📖iatzak📖🐛💻Ankit Kumar💻Aniket Singh Rawat💻📖Jerom Palimattom Tom📖💻⚠️Brady Planden💡jsbrittain💻⚠️Arjun🚇💻📖👀CHEN ZHAO🐛darryl-ad💻🐛🤔julian-evers💻Jason Siegel💻🤔Tom Maull💻⚠️ejfdickinson🤔🐛bobonice🐛💻Eric G. Kratz📖🚇🐛💻⚠️Andrés Ignacio Torres🚇Agnik Bakshi📖RuiheLi💻⚠️chmabaur🐛💻Abhishek Chaudhari📖💻Shubham Bhardwaj🚇Jonathan Lauber🚇Pradyot Ranjan🚇XuboGU💻🐛Ankit Meda💻This project follows theall-contributorsspecification. Contributions of any kind welcome!