About:DFN

Doyle-Fuller-Newman model - unlock deep insights into cell behavior with our most comprehensive electrochemical model

Overview

About:DFN is a physics-based model that represents the battery according to a set of physical equations and a corresponding parameter set. It is an extended implementation of the Doyle-Fuller-Newman model (see Literature References) as defined by the Battery Parameter eXchange (BPX) standard (v0.5).

About:DFN predicts:

  • Current-voltage relation
  • Battery heat dissipation rate
  • Individual electrode overpotentials
  • Lithiation distribution through electrode and within active material particles
  • Electrolyte distribution across electrodes and separator

About:DFN accounts for:

  • State-of-charge (SOC)
  • Temperature
  • Charge-discharge hysteresis
  • Rate capability (according to physics-based overvoltage computation)
  • Cycling history

Key features

  • Compatible with any thermal model
  • Compatible with distributed electronic networks and 3D cell/module/pack models
  • Implements an extended 1D+1D Doyle-Fuller-Newman (DFN) model in a manner compatible with the Battery Parameter eXchange (BPX) standard for battery parameter sets

Key applications

  • High-fidelity system prototyping for cell integration
  • Fast charge protocol design
  • Representation of cell performance in 3D thermal models
  • Degradation analysis*

* with provision of supplementary degradation data

Technical Description

About:DFN implements an extended 1D+1D DFN model that builds on the BPX standard (v0.5), in which the macroscopic current-flow direction in each electrode pair is resolved as a linear 1D domain, and the microscopic active material particle properties are described by assuming spherical particles of a Li insertion material in each electrode. All particles of a given material are assumed to have constant size; particle size and shape distributions are not considered.

The macroscopic 1D DFN model predicts the electrolyte current density and the flux of Li\(^+\)-containing electrolyte by solving concentrated solution transport equations for the electrolyte concentration and electrolyte potential. In electron-conducting regions, current density is predicted using Ohm’s law, solving for electric potential. Morphology of porous structures (electrodes and separator) is described using a porous transport theory in terms of homogenised properties (porosity, tortuosity).

Li insertion rate and the corresponding faradaic current density is coupled according to a specified volumetric surface area to a microscopic 1D model, which solves the spherically symmetric Fick’s law diffusion equation to predict inserted Li concentration as a function of particle radius. The open circuit potential of the active material in each electrode can be expressed as either a monotonic function of lithiation extent or as a hysteresis model with separate lithiation and delithation branches.

Internal heating is computed, including Joule heating (resistive loss) and activation overpotential. Heat of mixing is ignored, to the first approximation. Temperature dependence of various physical quantities is accounted for by the specification of Arrhenius activation energies.

Mathematical Specification

The mathematical specification is an extension of the BPX standard (v0.5), wherein particular alterations of the standard equations are expressed by means of the BPX standard’s provision for user-defined properties.

Equations

Macroscopic dimension

The macroscopic dimension \(x\) is a 1D linear space \(0 \leq x \leq L_\mathrm{tot}\) and comprises successive domains with thicknesses \(L_\mathrm{neg}\), \(L_\mathrm{sep}\) and \(L_\mathrm{pos}\), where:

\[ \begin{equation} {L}_{\text{tot}}={{L}_{\text{neg}}}+{{L}_{\text{sep}}}+{{L}_{\text{pos}}} \end{equation} \]

The macroscopic domains \(q=\mathrm{neg,pos}\) are defined as \(0\le x\le {{L}_{\text{neg}}}\) and \({{L}_{\text{tot}}}-{{L}_{\text{pos}}}\le x\le {{L}_{\text{tot}}}\).

In the macroscopic dimension:

\[ \begin{equation} \nabla \cdot {{\mathbf{i}}_{s}}=-{{i}_{\text{v}}} \end{equation} \]
\[ \begin{equation} \nabla \cdot {{\mathbf{i}}_{l}}={{i}_{\text{v}}} \end{equation} \]
\[ \begin{equation} {\varepsilon }_{q}\frac{\partial {{c}_{l}}}{\partial t}+\nabla \cdot {{\mathbf{N}}_{l}}={{R}_{l}} \end{equation} \]
\[ \begin{equation} {\mathbf{i}}_{s}=-{{\sigma }_{\text{eff},s,q}}\nabla {{\phi }_{s}} \end{equation} \]
\[ \begin{equation} {\mathbf{i}}_{l}=-{{\kappa }_{l,\text{eff}}}\nabla {{\phi }_{l}}+\frac{2RT}{F}\left( 1-{{t}_{+}} \right){{\kappa }_{l\text{,eff}}}\left( 1+\frac{\partial \ln {{\gamma }_{\pm }}}{\partial \ln {{c}_{l}}} \right)\nabla \ln {{c}_{l}} \end{equation} \]
\[ \begin{equation} {\mathbf{N}}_{l}=-{{D}_{l,\text{eff}}}\nabla {{c}_{l}}+\frac{{{t}_{+}}}{F}{{\mathbf{i}}_{l}} \end{equation} \]
\[ \begin{equation} {R}_{l}=\frac{{{i}_{\text{v}}}}{F} \end{equation} \]
\[ \begin{equation} {i}_{\text{v}}=\sum_m{{i}_{\text{v},m}} \end{equation} \]

Here, the sum \(m\) is taken over all materials \(m\) present in electrode \(q\).

\[ \begin{equation} i_{\mathrm{v},m} = {a}_{\text{vol},m}{i}_{\text{far},m} \end{equation} \]
\[ \begin{equation} {i}_{\text{far},m}={{{i}_{0,m}}\left( \exp \left( \left( 1-{{\alpha }_{m}} \right)f\eta_m \right)-\exp \left( -{{\alpha }_{m}}f\eta_m\right) \right)} \end{equation} \]
\[ \begin{equation} f=\frac{F}{RT} \end{equation} \]
\[ \begin{equation}\eta_m ={{\phi }_{s}}-{{\phi }_{l}}-{{U}_{m,{{x}_{\text{Li},m}}={{x}_{\text{Li},m,\text{surf}}}}} \end{equation} \]
\[ \begin{equation} U_m={{U}_{m,0}}+\left( T-{{T}_{0}} \right)\frac{\Delta {{S}_{m,0}}}{F} \end{equation} \]
\[ \begin{equation} {x}_{\text{Li},m}=\frac{{{c}_{s,m}}}{{{c}_{\text{sat},m}}} \end{equation} \]

When the standard Butler-Volmer equation is used, the exchange current density \(i_{0,m}\) takes the following specific form, which agrees with the BPX standard (when \(\alpha_m = 0.5\)). Alternatively, \(i_{0,m}\) may be specified as a functional parameter (Exchange current density).

\[ \begin{equation} {i}_{0,m}={{i}_{0,\text{sat,}m}}{{\left( \frac{{{c}_{l}}}{{{c}_{l,0}}} \right)}^{1-{{\alpha }_{m}}}}x_{\text{Li},m,\text{surf}}^{{{\alpha }_{m}}}{{\left( 1-{{x}_{\text{Li},m,\text{surf}}} \right)}^{1-{{\alpha }_{m}}}} \end{equation} \]

Optionally, a hysteresis model can be used for any material, such that:

\[ \begin{equation}{{U}_{m,\text{0}}}=\left(\frac{1+h_m}{2}\right){{U}_{m,\text{delit}}}+\left(\frac{1-h_m}{2}\right){{U}_{m,\text{lit}}}\end{equation} \]

If the properties \(U_{m,\mathrm{lit/delit}}\) are not specified, it can be assumed that no hysteresis model is applied.

If the hysteresis model is a “zero-state” hysteresis model, the hysteresis state \(h_m\) is a direct function of local faradaic current density, as a smoothed step function:

\[ \begin{equation}h_m=\tanh \left( \frac{{{i}_{\text{far},m}}}{{{i}_{\text{far,crit}}}} \right)\end{equation} \]

If the hysteresis model is a “one-state” hysteresis model, the hysteresis state \(h_m\) is the solution to a relaxation equation according to a decay rate \(\gamma_m\):

\[ \begin{equation} \frac{\partial h_m}{\partial t} = \gamma_m\left(\frac{i_{\mathrm{v},m}}{\phi_{\mathrm{act},m}Fc_{\mathrm{sat},m}}\right)\left(1 - \mathrm{sgn}(i_{\mathrm{far},m})h_m\right) \end{equation} \]

For \(g_l = D_l,\kappa_l\):

\[ \begin{equation} {g}_{l,\text{eff}}=\frac{{{\varepsilon }_{m}}}{{{\tau }_{m}}}{{g}_{l}} \end{equation} \]

The temperature dependence of any property \(g\) can be expressed as an Arrhenius relation:

\[ \begin{equation} g={{g}_{0}}\exp \left( \frac{{{E}_{\text{a},g}}}{R}\left( \frac{1}{{{T}_\mathrm{ref}}}-\frac{1}{T} \right) \right) \end{equation} \]

For electrolyte parameters, a more general dependence on \(c_l\) and \(T\) may be expressed.

Microscopic dimension

The microscopic dimension \(r\) is a 1D spherically symmetric space \(0 \leq r \leq r_{\mathrm{p},m}\), for each material \(m\). In this dimension:

\[ \begin{equation} \frac{\partial {{c}_{s,m}}}{\partial t}+\nabla \cdot {{\mathbf{N}}_{s,m}}=0 \end{equation} \]
\[ \begin{equation} {\mathbf{N}}_{s,m}=-{{D}_{s,m}}\nabla {{c}_{s,m}} \end{equation} \]

Boundary Conditions

Initial conditions

\[ \begin{equation} {c}_{l,t=0}={{c}_{l,0}} \end{equation} \]
\[ \begin{equation} h_m=0 \end{equation} \]

Initial lithiation extents are determined from a defined state-of-charge \(\mathrm{SOC}_0\) (with respect to nominal capacity and referenced to SOC = 100% as the equilibrium state at \(V_\mathrm{cell} = V_\mathrm{EOC}\)) by solving the simultaneous equations defined in (2a-2d) of the BPX standard (v0.5). For a single-phase electrode, these simplify as follows:

\[ \begin{equation} {x}_{\text{Li},\text{pos},t=0}={{x}_{\text{Li},\text{pos},\text{min}}}+\left(1-\text{SO}{{\text{C}}_{0}}\right)\left(\frac{Q_\mathrm{nom}}{Q_{\mathrm{max,pos}}}\right) \end{equation} \]
\[ \begin{equation} {x}_{\text{Li},\text{neg},t=0}={{x}_{\text{Li},\text{neg},\text{max}}}-\left(1-\text{SO}{{\text{C}}_{0}}\right)\left(\frac{Q_\mathrm{nom}}{Q_\mathrm{max,neg}}\right) \end{equation} \]
\[ \begin{equation} Q_{\mathrm{max},m}=\frac{F}{3600}A_\mathrm{el}\left(\phi_m c_{\mathrm{sat},m}L_m \right) \left(x_{\mathrm{Li},m,\mathrm{max}}-x_{\mathrm{Li},m,\mathrm{min}}\right) \end{equation} \]

Macroscopic boundaries

At the current collector boundaries (\(x = 0, L_\mathrm{tot}\)):

\[ \begin{equation} {\mathbf{i}}_{l}\cdot {{\mathbf{n}}_{x}}={{\mathbf{N}}_{l}}\cdot {{\mathbf{n}}_{x}}=0 \end{equation} \]

At the electrode—separator interfaces (\(x = L_\mathrm{neg},L_\mathrm{tot}-L_\mathrm{pos}\))

\[ \begin{equation} {\mathbf{i}}_{s}\cdot {{\mathbf{n}}_{x}}=0 \end{equation} \]
\[ \begin{equation} {\phi}_{s,x=0}=0 \end{equation} \]
\[ \begin{equation} {\mathbf{i}}_{l}\cdot {{\mathbf{n}}_{x}}=-\frac{{{I}_{\text{cell}}}}{{{A}_{\text{el}}}{{N}_{\text{el}}}} \end{equation} \]
\[ \begin{equation} V_\mathrm{cell} = \phi_{s,x=L_\mathrm{tot}} + I_\mathrm{cell}R_\mathrm{addn} \end{equation} \]

Macroscopic­-microscopic coupling

At \(r = r_{\mathrm{p},m}\) in the microscopic dimension:

\[ \begin{equation} {\mathbf{N}}_{s}\cdot {{\mathbf{n}}_{r}}=\frac{{{i}_{\text{far}}}}{F} \end{equation} \]

Loading conditions

The cell loading is specified by determining \(I_\mathrm{cell}\) from exactly one additional constraint for each discrete simulated time, chosen from the following options. Typically, the chosen loading condition will change at certain times during the protocol being simulated.

1 - Specified current:

\[ \begin{equation} {{I}_{\text{cell}}}={{I}_{\text{app}}} \end{equation} \]

2 - Specified voltage:

\[ \begin{equation} {{V}_{\text{cell}}}={{V}_{\text{app}}} \end{equation} \]

3 - Specified power:

\[ \begin{equation} {{V}_{\text{cell}}}{{I}_{\text{cell}}}={{P}_{\text{app}}} \end{equation} \]

Evaluated quantities

The cell heat source can be provided to a thermal model:

\[ \begin{equation} {Q}_{\text{cell}}={{N}_{\text{el}}}{{A}_{\text{el}}}\mathop{\int }_{0}^{{{L}_{\text{tot}}}}\left( {{q}_{\text{v},\text{rev}}}+ {{q}_{\text{v},\text{hys}}}+{{q}_{\text{v},\text{JH}}}+{{q}_{\text{v},\text{act}}} \right)\ dx \end{equation} \]
\[ \begin{equation}{q}_{\text{v},\text{rev,}m}=\frac{{{i}_{\text{v,}m}}}{F}T\Delta {{S}_{m,0}} \end{equation} \]
\[ \begin{equation} {q}_{\text{v},\text{hys,}m}={i}_{\text{v,}m}\left(U_{m,0}-\frac{{U}_{m,\text{delit}}+{U}_{m,\text{lit}}}{2}\right) \end{equation} \]
\[ \begin{equation} {q}_{\text{v},\text{JH}}=-{{\mathbf{i}}_{s}}\cdot \nabla {{\phi }_{s}}-{{\mathbf{i}}_{l}}\cdot \nabla {{\phi }_{l}} \end{equation} \]
\[ \begin{equation} {q}_{\text{v},\text{act}}=\sum_m {{i}_{\text{v},m}}\eta_m \end{equation} \]

User Inputs: Operating Conditions

Quantity Unit Description
\(I_\mathrm{app}\) A Applied current*
\(P_\mathrm{app}\) W Applied power*
\(\mathrm{SOC}_0\) 1 Initial state-of-charge
\(V_\mathrm{app}\) V Applied voltage*

* Exactly one of the three possible applied quantities must be specified at each simulated time. Additional logic (for example, cut-off voltages or currents for different loading steps) can be built into the simulated protocol at the user’s discretion.

Internal Quantities

Supplied Parameterisation

All parameters are provided at the reference temperature except where otherwise indicated.

Quantity Unit Description
\(A_\mathrm{el}\) m\(^2\) Active electrode area, per electrode pair
\(a_{\mathrm{vol},m}\) m\(^{-1}\) Active material volumetric surface area, material \(m\)
\(c_{l,0}\) mol m\(^{-3}\) Initial electrolyte concentration
\(c_{\mathrm{sat},m}\) mol m\(^{-3}\) Maximum (saturated) concentration of inserted Li, material \(m\)
\(D_l\) m\(^2\) s\(^{-1}\) Electrolyte diffusivity
\(D_{s,m}\) m\(^2\) s\(^{-1}\) Diffusivity, inserted Li, material \(m\)
\(E_{\mathrm{a},D_l}\) J mol\(^{-1}\) Activation energy, electrolyte diffusivity
\(E_{\mathrm{a},D_{s,m}}\) J mol\(^{-1}\) Activation energy, diffusivity, inserted Li, material \(m\)
\(E_{\mathrm{a},i_{0,m}}\) J mol\(^{-1}\) Activation energy, exchange current density, material \(m\)
\(E_{\mathrm{a},\kappa_l}\) J mol\(^{-1}\) Activation energy, electrolyte conductivity
\(i_\mathrm{far,crit}\) A m\(^{-2}\) Critical current density for hysteresis transition, Li insertion, electrode \(m\), 0th-order hysteresis model
\(i_{0,m}\) A m\(^{-2}\) Exchange current density, material \(m\).* Only supplied directly when \(i_{0,m}\) does not have the standard Butler-Volmer form.
\(i_{0,\mathrm{sat},m}\) A m\(^{-2}\) Exchange current density at 100% lithiated conditions, material \(m\). Only supplied when \(i_{0,m}\) has the standard Butler-Volmer form.
\(L_q\) m Thickness, domain \(q\)
\(N_\mathrm{el}\) 1 Number of electrode pairs
\(Q_\mathrm{nom}\) Ah Cell nominal capacity
\(R_\mathrm{addn}\) \(\Omega\) Cell additional series resistance
\(r_{\mathrm{p},m}\) m Particle radius, material \(m\)
\(\Delta S_{m,0}\) J K\(^{-1}\) mol\(^{-1}\) Entropic coefficient, material \(m\)
\(T_\mathrm{ref}\) K Reference temperature
\(t_+\) 1 Transference number, Li\(^+\) in electrolyte
\(U_{m,0}\) V Open circuit potential vs Li\(^+\)/Li at reference temperature, material \(m\)
\(U_{m,\mathrm{delit}}\) V Open circuit potential vs Li\(^+\)/Li at reference temperature during delithiation, material \(m\), hysteresis model
\(U_{m,\mathrm{lit}}\) V Open circuit potential vs Li\(^+\)/Li at reference temperature during lithiation, material \(m\), hysteresis model
\(V_\mathrm{EOC}\) V Cell upper (end-of-charge) cut-off voltage
\(V_\mathrm{EOD}\) V Cell lower (end-of-discharge) cut-off voltage
\(x_\mathrm{Li,neg,max}\) 1 Maximum lithiation extent, negative electrode at \(V = V_\mathrm{EOC}\)
\(x_\mathrm{Li,neg,min}\) 1 Minimum lithiation extent, negative electrode at \(V = V_\mathrm{EOD}\)
\(x_\mathrm{Li,pos,max}\) 1 Maximum lithiation extent, positive electrode at \(V = V_\mathrm{EOD}\)
\(x_\mathrm{Li,pos,min}\) 1 Minimum lithiation extent, positive electrode at \(V = V_\mathrm{EOC}\)
\(\alpha_m\) 1 Transfer coefficient, material \(m\)
\(\gamma_m\) 1 Hysteresis decay rate, material \(m\)
\(\varepsilon_q\) 1 Porosity (electrolyte volume fraction), domain \(q\)
\(\kappa_l\) S m\(^{-1}\) Electrolyte conductivity
\(\sigma_{\mathrm{eff},s,m}\) S m\(^{-1}\) Effective electronic conductivity, material \(m\)
\(\tau_q\) 1 Tortuosity, domain \(q\)
\(\phi_{\mathrm{act},m}\) 1 Active material volume fraction, material \(m\)
\(1 + \partial \ln \gamma_\pm / \partial \ln c_l\) 1 Non-ideality coefficient (”thermodynamic factor”)

Internal Variables

Quantity Unit Description
\(c_l\) mol m\(^{-3}\) Electrolyte concentration
\(c_{s,m}\) mol m\(^{-3}\) Inserted Li concentration, material \(m\)
\(f\) V\(^{-1}\) Inverse thermal voltage
\(D_{l,\mathrm{eff}}\) m\(^2\) s\(^{-1}\) Effective electrolyte diffusivity
\(h_m\) 1 Hysteresis state, material \(m\) (+1 = delithiation branch, -1 = lithiation branch)
\(i_{\mathrm{far},m}\) A m\(^{-2}\) Current density, Li insertion, material \(m\) (positive for anodic current density = delithiation)
\(i_{\mathrm{v},m}\) A m\(^{-3}\) Volumetric current density, Li insertion, material \(m\) (positive for anodic current density = delithiation)
\(\mathbf{i}_l\) A m\(^{-2}\) Electrolyte current density
\(\mathbf{i}_s\) A m\(^{-2}\) Electric current density (electron-conducting phases)
\(i_\mathrm{v}\) A m\(^{-3}\) Volumetric current density, Li insertion (total)
\(\mathbf{N}_l\) mol m\(^{-2}\) s\(^{-1}\) Molar flux, electrolyte
\(\mathbf{N}_s\) mol m\(^{-2}\) s\(^{-1}\) Molar flux, inserted Li in particles
\(\mathbf{n}_r\) 1 Unit vector, outward normal direction, microscopic particle dimension
\(\mathbf{n}_x\) 1 Unit vector, outward normal direction, macroscopic dimension
\(Q_\mathrm{cell}\) W Cell heat source
\(Q_{\mathrm{max},m}\) Ah Maximum thermodynamic capacity in defined voltage window, electrode \(m\)
\(q_\mathrm{v,act}\) W m\(^{-3}\) Volumetric heat source, activation
\(q_\mathrm{v,hys}\) W m\(^{-3}\) Volumetric heat source, hysteresis losses
\(q_\mathrm{v,JH}\) W m\(^{-3}\) Volumetric heat source, Joule heating
\(q_\mathrm{v,rev}\) W m\(^{-3}\) Volumetric heat source, reversible heating
\(R_l\) mol m\(^{-3}\) s\(^{-1}\) Volumetric reaction rate, Li insertion
\(r\) m 1D spherical coordinate, microscopic particle dimension
\(t\) s Time
\(U_m\) V Open circuit potential vs Li\(^+\)/Li, material \(m\)
\(x\) m 1D linear coordinate, macroscopic dimension (current flow direction)
\(x_{\mathrm{Li},m}\) 1 Lithiation extent, material \(m\)
\(x_{\mathrm{Li},m,\mathrm{surf}}\) 1 Lithiation extent, active material particle surface, material \(m\)
\(\gamma_m\) 1 Hysteresis decay rate, material \(m\)
\(\eta_m\) V Overpotential, material \(m\)
\(\kappa_{l,\mathrm{eff}}\) S m\(^{-1}\) Effective electrolyte conductivity
\(\phi_l\) V Electrolyte potential
\(\phi_s\) V Electric potential

Variables inherited from thermal model

Quantity Unit Description
\(T\) K Temperature

Universal constants

Quantity Value Description
\(F\) 96485 C mol\(^{-1}\) Faraday constant
\(R\) 8.3145 J K\(^{-1}\) mol\(^{-1}\) Gas constant

Implementation Details

BPX JSON

The BPX JSON implementation consists of raw parameterisation data in a .json file compatible with the BPX v0.5 standard. These data are intended for use with a user-defined implementation of the equations in the Mathematical Specification.

The table below summarises the JSON paths that yield the variables specified above. Certain properties are derived from the BPX variables as indicated by the equations below:

\[ \phi_{\mathrm{act},m} = \frac{a_{\mathrm{vol},m}r_{\mathrm{p},m}}{3} \]
\[ \tau_q=\frac{\varepsilon_q}{\mathcal{B}_q} \]
\[ \Delta S_{m,0}=F\frac{\partial U_m}{\partial T} \]
\[ i_{0,\mathrm{sat},m}=FK_m \]

Notes on BPX JSON interpretation

  • The following table gives paths for the specification of each quantity relative to the path Parameterisation , which is denoted . in relative paths below.

  • For properties defined by material \(m\), the following string substitutions apply:

    Electrode Type {domain} {material}
    Single-phase {material} electrode Negative or Positive
    Two-phase (negative electrode only) Negative electrode/Particle/{name} {name}: Negative
    - {name} can be any descriptive name, e.g. Silicon Additive.
    - Two-phase positive electrodes are not supported.
    - For properties defined by domain \(q\), the string variable {q} is to be substituted by Negative electrode, Positive electrode, or Separator.
    - Electrolyte parameters may be expressed as extended mathematical functions, beyond the scope of function fields in the BPX schema. In this case, a zero value is entered at the specified JSON path in the BPX schema (when required), and a function definition is given in the "User-defined" section. See Extended mathematical functions below.
    Quantity Unit JSON Path
    \(A_\mathrm{el}\) m\(^2\) ./Cell/Electrode area [m2]
    \(a_{\mathrm{vol},m}\) m\(^{-1}\) ./{domain}/Surface area per unit volume [m-1]
    \(c_{l,0}\) mol m\(^{-3}\) ./Electrolyte/Initial concentration [mol.m-3]
    \(c_{\mathrm{sat},m}\) mol m\(^{-3}\) ./{domain}/Maximum concentration [mol.m-3]
    \(D_l\) m\(^2\) s\(^{-1}\) ./Electrolyte/Diffusivity [m2.s-1]
    \(D_{s,m}\) m\(^2\) s\(^{-1}\) ./{domain}/Diffusivity [m2.s-1]
    \(E_{\mathrm{a},D_l}\) J mol\(^{-1}\) ./Electrolyte/Diffusivity activation energy [J.mol-1]
    \(E_{\mathrm{a},D_{s,m}}\) J mol\(^{-1}\) ./{domain}/Diffusivity activation energy [J.mol-1]
    \(E_{\mathrm{a},i_{0,m}}\) J mol\(^{-1}\) ./{domain}/Reaction rate constant activation energy [J.mol-1]
    \(E_{\mathrm{a},\kappa_l}\) J mol\(^{-1}\) ./Electrolyte/Conductivity activation energy [J.mol-1]
    \(i_{\mathrm{far,crit,}m}\) A m\(^{-2}\) Not specified: numerical smoothing parameter that may be set in implementation-specific manner.
    \(K_m\) mol m\(^{-2}\) s\(^{-1}\) ./{domain}/Reaction rate constant [mol.m-2.s-1]
    \(L_q\) m ./{q}/Thickness [m]
    \(N_\mathrm{el}\) 1 ./Cell/Number of electrode pairs connected in parallel to make a cell
    \(Q_\mathrm{nom}\) Ah ./Cell/Nominal cell capacity [A.h]
    \(R_\mathrm{addn}\) \(\Omega\) ./User-defined/Contact resistance [Ohm]
    \(r_{\mathrm{p},m}\) m ./{domain}/Particle radius [m]
    \(T_\mathrm{ref}\) K ./Cell/Reference temperature [K]
    \(t_+\) 1 ./Electrolyte/Cation transference number
    \(U_{m,0}\) V ./{domain}/OCP [V]
    \(U_{m,\mathrm{delit}}\) V ./User-defined/{material} electrode delithiation OCP [V]
    \(U_{m,\mathrm{lit}}\) V ./User-defined/{material} electrode lithiation OCP [V]
    \(\partial U_m / \partial T\) V K\(^{-1}\) ./{domain}/Entropic change coefficient [V.K-1]
    \(V_\mathrm{EOC}\) V ./Cell/Upper voltage cut-off [V]
    \(V_\mathrm{EOD}\) V ./Cell/Lower voltage cut-off [V]
    \(x_{\mathrm{Li},m,\mathrm{max}}\) 1 ./{domain}/Maximum stoichiometry
    \(x_{\mathrm{Li},m,\mathrm{min}}\) 1 ./{domain}/Minimum stoichiometry
    \(\alpha_m\) 1 Not specified. 0.5 by definition.
    \(\gamma_m\) 1 ./User-defined/{material} particle hysteresis decay rate
    \(\varepsilon_q\) 1 ./{q}/Porosity
    \(\kappa_l\) S m\(^{-1}\) ./Electrolyte/Conductivity [S.m-1]
    \(\sigma_{\mathrm{eff},s,q}\) S m\(^{-1}\) ./{q}/Conductivity [S.m-1]
    \(\mathcal{B}_q\) 1 ./{q}/Transport efficiency
    \(1 + \partial \ln \gamma_\pm / \partial \ln c_l\) 1 ./User-defined/Thermodynamic factor

Exchange current density

For any phase \(m\), the presence of a field ./User-defined/{material} electrode exchange-current density pre-multiplier means that the field value encodes a function \(f(x_\mathrm{Li})\) which acts as a multiplier to a constant reference exchange current density, such that

\[ i_{0,m} =f(x_{\mathrm{Li},m})\,i_{0,\mathrm{sat},m} \]

where \(i_{0,\mathrm{sat},m}=FK_m\) and \(K_m\) is located at the standard place in the schema as defined by the table above.

If the pre-multiplier field is absent, the standard Butler-Volmer exchange current density expression (11) is used.

Extended mathematical functions

For supported properties, the presence of a zero-valued field ./User-defined/{parameter name} func_type {function type} indicates that the named parameter {parameter name} is supplied as a set of coefficients for the function with type {function_type}. The coefficients are then supplied as corresponding fields ./User-defined/{parameter name} {coeff}, where function-specific values of {coeff} are given below.

The string {parameter name} is defined as follows, for supported properties:

Quantity Unit JSON Path
\(D_l\) m\(^2\) s\(^{-1}\) Electrolyte diffusivity [m2.s-1]
\(t_+\) 1 Cation transference number
\(\kappa_l\) S m\(^{-1}\) Electrolyte conductivity [S.m-1]
\(1 + \partial \ln \gamma_\pm / \partial \ln c_l\) 1 Thermodynamic factor

Function type crosspoly: crossed polynomial

\[ f(x,y)=\sum_{i=1}^n{a_i}x^{m_i}y^{n_i} \]

The function \(f(x,y)\) is interpreted as a function \(f(c_l,T)\). There are \(n\) sets of 3 coefficient entries:

Quantity JSON {coeff} key
\(a_i\) poly.poly{i}.a
\(m_i\) poly.poly{i}.m
\(n_i\) poly.poly{i}.n

Function type Landesfeind2019_cond: Landesfeind-Gasteiger conductivity

\[ \begin{equation} f(c_l,T)=\frac{a_1a_2}{a_3} \end{equation} \]
\[ \begin{equation} a_1=p_1\left(1+\theta-p_2\right)c_\mathrm{M} \end{equation} \]
\[ \begin{equation} a_2 = 1+ p_3\sqrt{c_\mathrm{M}} + p_4c_\mathrm{M}\left(1+p_5g_T\right) \end{equation} \]
\[ \begin{equation} a_3= 1+ p_6c^4_\mathrm{M}g_T \end{equation} \]
\[ \begin{equation} g_T=\mathrm{exp}\left(\frac{1000}{\theta}\right) \end{equation} \]
\[ \begin{equation} c_\mathrm{M} = \frac{c_l}{1000\;\mathrm{mol\;m^{-3}}} \end{equation} \]
\[ \begin{equation} \theta = \frac{T}{1 \mathrm{\;K}} \end{equation} \]

There are 6 coefficient entries:

Quantity JSON {coeff} key
\(p_i\) p{i}

Function type Landesfeind2019_diff: Landesfeind-Gasteiger diffusivity

\[ \begin{equation} f(c_l,T) = p_1\mathrm{exp}\left(p_2c_\mathrm{M}\right)\mathrm{exp}\left(\frac{p_3}{\theta}\right)\mathrm{exp}\left(\frac{p_4c_\mathrm{M}}{\theta}\right) \end{equation} \]

See definitions of \(c_\mathrm{M}\) and \(\theta\) under Landesfeind2019_cond.

There are 4 coefficient entries:

Quantity JSON {coeff} key
\(p_i\) p{i}

PyBaMM

The PyBaMM implementation requires a Python environment supporting the dependencies listed in the provided requirements.txt.

All parameterisation data are provided in a BPX JSON format as described above. Python code is provided to yield compatible pybamm.ParameterValues and pybamm.lithium_ion.DFN objects that express the parameter set and can be used to define a pybamm.Simulation.

Literature References

  1. Doyle, M.; Fuller, T.F.; Newman, J. Modeling of Galvanostatic Charge and Discharge of the Lithium/Polymer/Insertion Cell. Journal of The Electrochemical Society 1993, 140, 1526-1533, doi:10.1149/1.2221597.
  2. Fuller, T.F.; Doyle, M.; Newman, J. Simulation and Optimization of the Dual Lithium Ion Insertion Cell. Journal of The Electrochemical Society 1994, 141, 1-10, doi:10.1149/1.2054684.
  3. Doyle, M.; Newman, J.; Gozdz, A.S.; Schmutz, C.N.; Tarascon, J.M. Comparison of Modeling Predictions with Experimental Data from Plastic Lithium Ion Cells. Journal of The Electrochemical Society 1996, 143, 1890-1903, doi:10.1149/1.1836921.
  4. Thomas, K.E.; Newman, J.; Darling, R.M. Mathematical Modeling of Lithium Batteries. In Advances in Lithium-Ion Batteries, van Schalkwijk, W.A., Scrosati, B., Eds.; Kluwer Academic/Plenum Publishers: New York, 2002; pp. 345-392.
  5. Landesfeind, J.; Gasteiger, H.A. Temperature and Concentration Dependence of the Ionic Transport Properties of Lithium-Ion Battery Electrolytes. Journal of The Electrochemical Society 2019, 166, A3079-A3097, doi:10.1149/2.0571912jes.
  6. Wycisk, D.; Oldenburger, M.; Stoye, M.G.; Mrkonjic, T.; Latz, A. Modified Plett-model for modeling voltage hysteresis in lithium-ion cells. Journal of Energy Storage 2022, 52C, 105016, doi:10.1016/j.est.2022.105016.

Version History

Version Release Date Comments
1.0 14 Mar 2023 First release
1.1 20 Sep 2023 Added 0th-order hysteresis model
2.0 23 Sep 2024 Added blended electrodes and 1-state hysteresis model
2.0a 27 Feb 2025 Updated BPX version to v0.5.