Running PyBaMM
Before starting this course, you should be comfortable with the basics of Python and have PyBaMM installed in your machine. If you need a refresher about Python you can check the Intro to Python course. The instructions on how to install PyBaMM are available in the PyBaMM docs.
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
- a framework for writing and solving systems of differential equations,
- a library of battery models and parameters, and
- 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.
First steps with PyBaMM
The very first thing we need to do is to import PyBaMM
import pybamm
This will make all the PyBaMM functionality available in the current script/notebook. As a very first example, we will run the Doyle-Fuller-Newman (DFN) model with all the basic settings. The DFN is one of the many models implemented in PyBaMM, so we can create it by typing
model = pybamm.lithium_ion.DFN()
The next step is to create a
pybamm.Simulation
to process the model and make it ready to be solved:simulation = pybamm.Simulation(model)
The simulation can be solved by calling the
solve
method in the simulation object. The method takes an argument which should be the time interval to solve for in seconds (here we do 1 hour, as the default setup is a 1C discharge):simulation.solve([0, 3600])
Now that the simulation has been solved, we can simply call the
plot
method to generate an interactive plot of the key variables:simulation.plot()
Comparing multiple models
We have seen how to run a simulation of the DFN model, but PyBaMM includes many other standard electrochemical models and makes comparing their outputs very easy. Let’s now compare the DFN model with the Single Particle Model (SPM) and the Single Particle Model with electrolyte (SPMe). We can leverage the functionality of Python lists to do so. We start by creating a list of all the models we wish to solve
models = [ pybamm.lithium_ion.SPM(), pybamm.lithium_ion.SPMe(), pybamm.lithium_ion.DFN(), ]
so we can now loop over the list, creating and solving the simulations as we go. The solved simulations are stored in the list
simulations
simulations = [] for model in models: simulation = pybamm.Simulation(model) simulation.solve([0, 3600]) simulations.append(simulation)
We can now plot the results. Because we want to plot all the simulations in the same plot we cannot use the same syntax as before, instead we can use the
pybamm.dynamic_plot
method, which takes the list of simulations as an input:pybamm.dynamic_plot(simulations)
Basic plotting
So far we have been using the default plotting settings, but we can choose which variables to plot by passing the keyword argument
output_variables
which should be a list of the plotting variables.output_variables = ["Voltage [V]", "Current [A]"] simulation.plot(output_variables=output_variables)
the argument should be a list of strings with the names of the variables to plot. We can also plot multiple variables on the same plot by nesting lists.
output_variables = [ "Voltage [V]", ["Electrode current density [A.m-2]", "Electrolyte current density [A.m-2]"] ] simulation.plot(output_variables=output_variables)
To find which variables can be plotted for a given model, we can call the
variable_names
methodmodel.variable_names()
There are a lot of variables, so we can also search the list of variables for a particular string (e.g. “electrolyte”)
model.variables.search("electrolyte")
Changing the parameters
When running our simulations we have been using the default parameter values, which might not match the battery we want to simulate. PyBaMM has a number of in-built parameter sets (check the list here) that we can use. For example, to use the Chen et al (2020) parameter set we can do
parameter_values = pybamm.ParameterValues("Chen2020")
and then, when defining the simulation, we pass the parameter values as a keyword argument
simulation = pybamm.Simulation(model, parameter_values=parameter_values)
and solve and plot as usual.
Running experiments
The default settings are to do a 1C discharge, but we normally want to simulate other conditions. To do so, we can pass an experiment to the simulation, for example
simulation = pybamm.Simulation(model, experiment="Discharge at 3C until 3.3 V")
Printing citations
We aim to recognize all contributions by automatically generating citations to the relevant papers on which different parts of the code are built.
These will change depending on what models and solvers you use. Adding the command
pybamm.print_citations()
to the end of a script or notebook will print all citations that were used by that piece of code. This will print BibTeX information to the terminal; passing a filename to
print_citations
will print the BibTeX information to the specified file instead.