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.

BasicDFN2D: simulating in-plane electrolyte flows

PyBaMM’s single-layer pouch cell model and "x-lumped" thermal model use asymptotic reduction to model the effects of uneven current distribution and thermal gradients with minimal computational complexity. These are the most common types of inhomogeneity within a cell.

However, the asymptotic reduction assumed lithium ions cannot move in the in-plane directions, which means other types of inhomogeneity such as negative electrode overhang and manufacturing defects are not captured. To predict these effects, a full two-dimensional model is required. The BasicDFN class can be used for this.

In these example, we use the BasicDFN class to reproduce an effect observed by Liu and Arnold (2020), where placing an artificial blockage in the separator causes localized lithium plating.

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

import pybamm

Note: you may need to restart the kernel to use updated packages.

Load the BasicDFN2D model and add a defect by making the separator porosity a function of z_s. Like all FunctionParameter objects, all arguments (in this case, x_s and z_s) must be listed when defining the function, even if there is no dependence on them.

model = pybamm.lithium_ion.BasicDFN2D()
param = pybamm.ParameterValues("Ecker2015")
Lz = param["Electrode height [m]"]
exp = pybamm.Experiment(
    [
        "Discharge at 1C until 2.7 V",
        "Charge at 0.8C until 4.2 V",
        "Hold at 4.2 V until C/20",
    ]
)


def _sigmoid(arg):
    return (1 + np.tanh(arg)) / 2


def _top_hat(arg, a, b, k=200):
    return _sigmoid(k * (arg - a)) * _sigmoid(k * (b - arg))


def eps_sep(x_s, z_s):
    return 0.508 - 0.458 * (_top_hat(arg=z_s, a=Lz * 0.4, b=Lz * 0.6))


param_defect = param.copy()
param_defect.update({"Separator porosity": eps_sep})

Solve and plot. Notice how the lithium ions in the electrolyte have to move around the blockage, just like a fluid would.

z_2d = pybamm.SpatialVariable(
    "z_2d",
    domain=["negative electrode", "separator", "positive electrode"],
    coord_sys="cartesian",
    direction="tb",
)
var_pts = {"x_n": 5, "x_s": 5, "x_p": 5, "r_n": 20, "r_p": 20, z_2d: 10}
sim_defect = pybamm.Simulation(
    model, parameter_values=param_defect, experiment=exp, var_pts=var_pts
)
sol_defect = sim_defect.solve()
output_variables = [
    "Negative electrode surface potential difference [V]",
    "Negative electrode surface stoichiometry",
    "Negative electrode ocp [V]",
    "Electrolyte flux X-component [mol.m-2.s-1]",
    "Electrolyte flux Z-component [mol.m-2.s-1]",
    "Voltage [V]",
]
plot_defect = sol_defect.plot(output_variables, variable_limits="tight", shading="auto")

There is no lithium plating in this model. However, at the end of the constant current charge, the negative electrode potential difference in the area near the defect goes below 0 and the surface stoichiometry becomes 1, which are the two conditions required for lithium plating to happen.

plot_defect.plot(2.285)

Would this have happened without the blockage? To find out, run the model again with the original param dictionary that doesn’t have altered separator porosity.

sim_pristine = pybamm.Simulation(model, parameter_values=param, experiment=exp)
sol_pristine = sim_pristine.solve()
output_variables = [
    "Negative electrode surface potential difference [V]",
    "Negative electrode surface stoichiometry",
    "Negative electrode ocp [V]",
    "Electrolyte flux X-component [mol.m-2.s-1]",
    "Electrolyte flux Z-component [mol.m-2.s-1]",
    "Voltage [V]",
]
plot_pristine = sol_pristine.plot(
    output_variables, variable_limits="tight", shading="auto"
)

Without the defect, the negative electrode potential difference does not go below zero at any point.

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] Madeleine Ecker, Stefan Käbitz, Izaro Laresgoiti, and Dirk Uwe Sauer. Parameterization of a Physico-Chemical Model of a Lithium-Ion Battery: II. Model Validation. Journal of The Electrochemical Society, 162(9):A1849–A1857, 2015. doi:10.1149/2.0541509jes.
[3] Madeleine Ecker, Thi Kim Dung Tran, Philipp Dechent, Stefan Käbitz, Alexander Warnecke, and Dirk Uwe Sauer. Parameterization of a Physico-Chemical Model of a Lithium-Ion Battery: I. Determination of Parameters. Journal of the Electrochemical Society, 162(9):A1836–A1848, 2015. doi:10.1149/2.0551509jes.
[4] Alastair Hales, Laura Bravo Diaz, Mohamed Waseem Marzook, Yan Zhao, Yatish Patel, and Gregory Offer. The cell cooling coefficient: a standard to define heat rejection from lithium-ion batteries. Journal of The Electrochemical Society, 166(12):A2383, 2019.
[5] 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.
[6] Alan C. Hindmarsh. The PVODE and IDA algorithms. Technical Report, Lawrence Livermore National Lab., CA (US), 2000. doi:10.2172/802599.
[7] Alan C. Hindmarsh, Peter N. Brown, Keith E. Grant, Steven L. Lee, Radu Serban, Dan E. Shumaker, and Carol S. Woodward. SUNDIALS: Suite of nonlinear and differential/algebraic equation solvers. ACM Transactions on Mathematical Software (TOMS), 31(3):363–396, 2005. doi:10.1145/1089014.1089020.
[8] 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.
[9] Simon E. J. O'Kane, Ian D. Campbell, Mohamed W. J. Marzook, Gregory J. Offer, and Monica Marinescu. Physical origin of the differential voltage minimum associated with lithium plating in li-ion batteries. Journal of The Electrochemical Society, 167(9):090540, may 2020. URL: https://doi.org/10.1149/1945-7111/ab90ac, doi:10.1149/1945-7111/ab90ac.
[10] Giles Richardson, Ivan Korotkin, Rahifa Ranom, Michael Castle, and Jamie M. Foster. Generalised single particle models for high-rate operation of graded lithium-ion electrodes: systematic derivation and validation. Electrochimica Acta, 339:135862, 2020. doi:10.1016/j.electacta.2020.135862.
[11] 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.
[12] Yan Zhao, Yatish Patel, Teng Zhang, and Gregory J Offer. Modeling the effects of thermal gradients induced by tab and surface cooling on lithium ion cell performance. Journal of The Electrochemical Society, 165(13):A3169, 2018.