Using submodels
One of the main features of PyBaMM is its modular structure that allows for plug and play models. At the core, all models in PyBaMM are built as a collection of submodels, where a submodel determines a specific subset of the physics. For example, the particle submodel would specify how lithium is transported in the particles.
The full list of submodels can be found in the PyBaMM docs. You can check which submodels a given model uses by calling
model.submodels
In this lesson we will focus only on the subset of models to include additional physics, in particular:
- Thermal
- SEI growth
- Lithium plating
- Mechanics
- Active material
Thermal models
We start with the thermal models. These models account for the changes in the temperature caused by the operation of the battery. The thermal models available in PyBaMM are:
- Isothermal: temperature stays constant.
- Lumped: the temperature is taken to be homogeneous in the battery, so only the average temperature is computed.
- X-lumped: the temperature is taken to be homogeneous across the thickness of the cell, but can vary in the directions parallel to the current collectors. Need to be used in conjunction with a current collector model.
- X-full: the temperature is allowed to vary across the thickness of the cell.
More information on the thermal models can be found in the documentation.
Thermal models add extra physics on top of the electrochemical models, so we need to choose a base electrochemical model to start with. Then, the extra physics can be specified via the model options. For example, if we want to use the DFN model with a lumped thermal model we do
import pybamm model = pybamm.lithium_ion.DFN(options={"thermal": "lumped"})
and then we can solve the model as usual.
Comparing thermal models
Compare the results of the DFN model with isothermal and x-full. Plot the relevant variables, and recall that you can find the list of variables to plot by typing
model.variable_names()
. What differences do you observe in the models?SEI growth
Let's now focus our attention to SEI growth models. These models capture the growth of the solid-electrolyte interphase, which is cause by a side reaction between the electrolyte and lithium. There are multiple ways of simulating SEI growth, and PyBaMM has the following options:
- None: no SEI included.
- Constant: includes an SEI layer which does not grow.
- Reaction limited: assumes reaction is the limiting phenomenon, see Section 5.5.3 of Marquis (2020). It can also be specified to be asymmetric.
- Solvent-diffusion limited: assumes that solvent diffusion is the limiting phenomenon, see Section 5.5.4 of Marquis (2020).
- Electron-migration limited: assumes that migration of electrons is the limiting phenomenon, see Section 5.5.5 of Marquis (2020).
- Interstitial-diffusion limited: assumes that diffusion of lithium-ion intestitials is the limiting phenomenon, see Section 5.4 of Marquis (2020).
- EC reaction limited: assumes the model is limited by both reaction and dissuions, see Yang et al (2017).
See all the available options in the docs. For more information on these models, please see Marquis (2020) and Yang et al (2017).
By default, the change in porosity due to the growth of SEI is not taken into account. To enable it, you need to use the option
"SEI porosity change": "true"
.SEI growth models
Compare the results of the DFN model with various SEI growth submodels of your choice. Plot the relevant variables, and recall that you can find the list of variables to plot by typing
model.variable_names()
. What differences do you observe in the model?Particle mechanics
Finally, we consider the models for particle mechanics. These models account for the deformation and cracking on the particles. The models available in PyBaMM are
- None: no mechanical effects included.
- Swelling only: accounts for the deformation of the particles in the lithiation-delithiation cycle.
- Swelling and cracking: accounts for the swelling and also the crack formation on the particle surface.
The mechanical models can be set differently for each electrode by passing a tuple as the option. For example, the following option
model = pybamm.lithium_ion.DFN( options={"particle mechanics": ("swelling only", "none")} )
will include swelling model for the negative electrode and no mechanical effects for the positive electrode.
Particle mechanics models
Run the DFN model with swelling in the negative electrode and swelling and cracking in the positive electrode. Plot the relevant variables, and recall that you can find the list of variables to plot by typing
model.variable_names()
. What do you observe in the model?Note: you may want to use the "Ai2020" parameter set.