Tip

An interactive online version of this notebook is available, which can be accessed via

---

Alternatively, you may download this notebook and run it offline.

Attention

You are viewing this notebook on the latest version of the documentation, where these notebooks may not be compatible with the stable release of PyBaMM since they can contain features that are not yet released. We recommend viewing these notebooks from the stable version of the documentation. To install the latest version of PyBaMM that is compatible with the latest notebooks, build PyBaMM from source.

Tutorial 1 - How to run a model

Welcome to PyBaMM! In this notebook, we will run your first PyBaMM model in just a few simple lines.

To run through this jupyter notebook simply shift-enter to run the cells. If you are unfamiliar with Jupyter notebooks we recommend checking out this cheat sheet.

The first we need to do is to import PyBaMM, so we can use its capabilities. Note that the very first line is only needed in Google Colab.

%pip install "pybamm[plot,cite]" -q    # install PyBaMM if it is not installed
import pybamm

[notice] A new release of pip is available: 23.3.1 -> 23.3.2
[notice] To update, run: pip install --upgrade pip
Note: you may need to restart the kernel to use updated packages.

An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.

First, we load the model that we wish to run from PyBaMM’s model library. For this notebook, we choose the Doyle-Fuller-Newman (DFN) model:

model = pybamm.lithium_ion.DFN()

We now use this model to create a PyBaMM Simulation, which is used to process and solve the model:

sim = pybamm.Simulation(model)

We can then call solve on our simulation object to solve the model, passing the window of time to solve for in seconds (here 1 hour):

sim.solve([0, 3600])

<pybamm.solvers.solution.Solution at 0x7fbf9d8accd0>

Once the simulation is solved, we can call plot to generate a dynamic plot of the key variables:

sim.plot()

<pybamm.plotting.quick_plot.QuickPlot at 0x7fbf9d6f9f50>

In this tutorial, we have solved a model with the inbuilt default settings. However, PyBaMM is designed to be highly customisable. Over the course of the getting started tutorials, we will see how various settings can be changed so that the model is appropriate for your situation. In Tutorial 2 we cover how to simulate and compare different models.

References

If you write a paper that uses PyBaMM, we would be grateful if you could cite the papers relevant to your code. These will change depending on what models and solvers you use. To find out which papers you should cite, you can run:

pybamm.print_citations()

[1] Joel A. E. Andersson, Joris Gillis, Greg Horn, James B. Rawlings, and Moritz Diehl. CasADi – A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1):1–36, 2019. doi:10.1007/s12532-018-0139-4.
[2] Marc Doyle, Thomas F. Fuller, and John Newman. Modeling of galvanostatic charge and discharge of the lithium/polymer/insertion cell. Journal of the Electrochemical society, 140(6):1526–1533, 1993. doi:10.1149/1.2221597.
[3] Charles R. Harris, K. Jarrod Millman, Stéfan J. van der Walt, Ralf Gommers, Pauli Virtanen, David Cournapeau, Eric Wieser, Julian Taylor, Sebastian Berg, Nathaniel J. Smith, and others. Array programming with NumPy. Nature, 585(7825):357–362, 2020. doi:10.1038/s41586-020-2649-2.
[4] Scott G. Marquis, Valentin Sulzer, Robert Timms, Colin P. Please, and S. Jon Chapman. An asymptotic derivation of a single particle model with electrolyte. Journal of The Electrochemical Society, 166(15):A3693–A3706, 2019. doi:10.1149/2.0341915jes.
[5] Valentin Sulzer, Scott G. Marquis, Robert Timms, Martin Robinson, and S. Jon Chapman. Python Battery Mathematical Modelling (PyBaMM). Journal of Open Research Software, 9(1):14, 2021. doi:10.5334/jors.309.

Alternatively, you can print the citations in BibTeX format by running

pybamm.print_citations(output_format="bibtex")

In both cases, you can pass the extra argument filename to store the citations into a file.