bmlite.P2D.domains#

Contains classes to construct the battery for P2D simulations. Each class reads in keyword arguments that define parameters relevant to its specific domain. For example, the area and temperature are Battery level parameters because they are the same everywhere, but the discretizations Nx and Nr may be different for the anode, separator, and cathode domains.

Classes#

Battery

A class for battery-level attributes.

Electrode

A class for the electrode-specific attributes and methods.

Electrolyte

A class for the electrolyte attributes and methods.

Separator

A class for the separator attributes and methods.

Module Contents#

class bmlite.P2D.domains.Battery(**kwargs)[source]#

A class for battery-level attributes.

Parameters:

**kwargs (dict, required) –

Keyword arguments to set the battery-level attributes. The required keys and descriptions are given below:

Key

Description [units] (type)

cap

nominal battery capacity [A*h] (float)

temp

temperature [K] (float)

area

area normal to current collectors [m2] (float)

update()[source]#

Updates any secondary/dependent parameters. At present, this method does not do anything for the Battery class.

class bmlite.P2D.domains.Electrode(name, **kwargs)[source]#

A class for the electrode-specific attributes and methods.

This class is used to build both the anode and cathode for P2D simulations.

Parameters:

  • name (str) – Name of the electrode, must be either ‘anode’ or ‘cathode’.

  • **kwargs (dict, required) –

    Keyword arguments to set the electrode attributes. The required keys and descriptions are given below:

    Key

    Description [units] (type)

    Nx

    number of x discretizations [-] (int)

    Nr

    number of r discretizations [-] (int)

    thick

    electrode thickness [m] (float)

    R_s

    represenatative particle radius [m] (float)

    eps_el

    electrolyte volume fraction [-] (float)

    eps_CBD

    carbon binder domain volume fraction [-] (float)

    eps_void

    void volume fraction [-] (float)

    p_sol

    solid Bruggeman factor, eps_s**p_sol [-] (float)

    p_liq

    liquid Bruggeman factor, eps_el**p_liq [-] (float)

    alpha_a

    Butler-Volmer anodic symmetry factor [-] (float)

    alpha_c

    Butler-Volmer cathodic symmetry factor [-] (float)

    Li_max

    max solid-phase Li concentration [kmol/m3] (float)

    x_0

    initial solid Li intercalation fraction [-] (float)

    i0_deg

    i0 degradation factor [-] (float)

    Ds_deg

    Ds degradation factor [-] (float)

    material

    class name from bmlite.materials [-] (str)

    csvfile

    path to CSV file with OCV data (optional) (str)

    submodels

    submodels classes to include (dict[dict])

get_Ds(x, T, fluxdir)[source]#

Calculate the lithium diffusivity in the solid phase given the local intercalation fraction x and temperature T.

Parameters:

  • x (float | 1D array) – Lithium intercalation fraction [-].

  • T (float) – Battery temperature [K].

  • fluxdir (float | 1D array) – Lithiation direction: +1 for lithiation, -1 for delithiation, 0 for rest. Used for direction-dependent parameters. Ensure the zero case is handled explicitly or via a default (lithiating or delithiating).

Returns:

Ds (float | 1D array) – Lithium diffusivity in the solid phase [m2/s].

get_Eeq(x)[source]#

Calculate the equilibrium potential given the surface intercalation fraction x at the particle surface.

Parameters:

x (float | 1D array) – Lithium intercalation fraction at r = R_s [-].

Returns:

Eeq (float | 1D array) – Equilibrium potential [V].

get_Mhyst(x)[source]#

Calculate the hysteresis magnitude given the surface intercalation fraction x at the particle surface.

Parameters:

x (float | 1D array) – Lithium intercalation fraction at r = R_s [-].

Returns:

M_hyst (float | 1D array) – Hysteresis magnitude [V].

get_i0(x, C_Li, T, fluxdir)[source]#

Calculate the exchange current density given the surface intercalation fraction x at the particle surface, the local lithium ion concentration C_Li, and temperature T. The input types for x and C_Li should both be the same (i.e., both float or both 1D arrays).

Parameters:

  • x (float | 1D array) – Lithium intercalation fraction at r = R_s [-].

  • C_Li (float | 1D array) – Lithium ion concentration in the local electrolyte [kmol/m3].

  • T (float) – Battery temperature [K].

  • fluxdir (float | 1D array) – Lithiation direction: +1 for lithiation, -1 for delithiation, 0 for rest. Used for direction-dependent parameters. Ensure the zero case is handled explicitly or via a default (lithiating or delithiating).

Returns:

i0 (float | 1D array) – Exchange current density [A/m2].

make_mesh(xshift=0.0, pshift=0)[source]#

Determines/sets the x locations for all of the “minus” interfaces xm, “plus” interfaces xp, and control volume centers x based on the electrode thickness and Nx discretization. At present, only a uniform mesh is supported.

Also determines/sets the r locations for all of the “minus” interfaces rm, “plus” interfaces rp, and control volume centers r based on the representative particle radius and Nr discretization. At present, only a uniform mesh is supported.

Parameters:

  • xshift (float, optional)

  • pshift (int, optional)

See also

batmods.mesh.x_ptr, batmods.mesh.xr_ptr, batmods.mesh.uniform_mesh

update()[source]#

Updates any secondary/dependent parameters. For the Electrode class, this initializes the material class, and sets the following:

  • Void-phase volume fraction [-]:

    eps_void = 1 - eps_s - eps_el

  • Activate material volume fraction [-]:

    eps_AM = eps_s - eps_CBD

  • Solid-phase conductivity [S/m]:

    sigma_s = 10 * eps_s

  • Specific particle surface area [m2/m3]:

    A_s = 3 * eps_AM / R_s

class bmlite.P2D.domains.Electrolyte(**kwargs)[source]#

A class for the electrolyte attributes and methods.

Parameters:

**kwargs (dict, required) –

Keyword arguments to set the electrolyte attributes. The required keys and descriptions are given below:

Key

Description [units] (type)

li_0

initial Li+ concentration [kmol/m3] (float)

D_deg

D degradation factor [-] (float)

t0_deg

t0 degradation factor [-] (float)

kappa_deg

kappa degradation factor [-] (float)

gamma_deg

gamma degradation factor [-] (float)

material

class name from bmlite.materials [-] (str)

get_D(C_Li, T)[source]#

Calculate the lithium ion diffusivity in the electrolyte solution at concentration C_Li and temperature T.

Parameters:

  • C_Li (float | 1D array) – Lithium ion concentration in the electrolyte [kmol/m3].

  • T (float) – Battery temperature [K].

Returns:

D (float | 1D array) – Lithium ion diffusivity in the electrolyte [m2/s].

get_gamma(C_Li, T)[source]#

Calculate the electrolyte thermodynamic factor at concentration C_Li and temperature T.

Parameters:

  • C_Li (float | 1D array) – Lithium ion concentration in the electrolyte [kmol/m3].

  • T (float) – Battery temperature [K].

Returns:

gamma (float | 1D array) – Thermodynamic factor [-].

get_kappa(C_Li, T)[source]#

Calculate the electrolyte conductivity at concentration C_Li and temperature T.

Parameters:

  • C_Li (float | 1D array) – Lithium ion concentration in the electrolyte [kmol/m3].

  • T (float) – Battery temperature [K].

Returns:

kappa (float | 1D array) – Electrolyte conductivity [S/m].

get_t0(C_Li, T)[source]#

Calculate the lithium ion transference number at concentration C_Li and temperature T.

Parameters:

  • C_Li (float | 1D array) – Lithium ion concentration in the electrolyte [kmol/m3].

  • T (float) – Battery temperature [K].

Returns:

t0 (float | 1D array) – Lithium ion transference number [-].

update()[source]#

Updates any secondary/dependent parameters. For the Electrolyte class, this only initializes the material class.

class bmlite.P2D.domains.Separator(**kwargs)[source]#

A class for the separator attributes and methods.

This class is used to build both the separator for P2D simulations.

Parameters:

**kwargs (dict, required) –

Keyword arguments to set the separator attributes. The required keys and descriptions are given below:

Key

Description [units] (type)

Nx

number of x discretizations [-] (int)

thick

electrode thickness [m] (float)

eps_el

electrolyte volume fraction [-] (float)

p_liq

liquid Bruggeman factor, eps_el**p_liq [-] (float)

make_mesh(xshift=0.0, pshift=0)[source]#

Determines/sets the x locations for all of the “minus” interfaces xm, “plus” interfaces xp, and control volume centers x based on the electrode thickness and Nx discretization. At present, only a uniform mesh is supported.

Parameters:

  • xshift (float, optional)

  • pshift (int, optional)

See also

batmods.mesh.x_ptr, batmods.mesh.xr_ptr, batmods.mesh.uniform_mesh

update()[source]#

Updates any secondary/dependent parameters. For the Separator class, this sets the following:

  • Solid-phase volume fraction [-]:

    eps_s = 1 - eps_el