bmlite.materials

The materials package contains kinetic and transport properties for common battery materials, including both electrode active materials and electrolytes.

Classes

Gen2Electrolyte	Gen 2 Electrolyte transport and material properties.
GraphiteFast	Computationally fast Graphite kinetic and transport properties.
GraphiteSiOx	Computationally fast GraphiteSiOx kinetic and transport properties.
GraphiteSiOxSlow	Computationally slow GraphiteSiOx kinetic and transport properties.
GraphiteSlow	Computationally slow Graphite kinetic and transport properties.
GraphiteSlowExtrap	Computationally slow Graphite kinetic and transport properties.
LFPInterp	LFP kinetic and transport properties, interpolated from data.
NMC532Fast	Computationally fast NMC532 kinetic and transport properties.
NMC532Slow	Computationally slow NMC532 kinetic and transport properties.
NMC532SlowExtrap	Computationally slow NMC532 kinetic and transport properties.
NMC811	Computationally fast NMC811 kinetic and transport properties.
NMC811Slow	Computationally slow NMC811 kinetic and transport properties.

Package Contents

class bmlite.materials.Gen2Electrolyte

Gen 2 Electrolyte transport and material properties.

References

TODO: cite publication with Gen2 properties.

get_D(C_Li, T)

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)

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)

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)

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 [-].

class bmlite.materials.GraphiteFast(alpha_a, alpha_c, Li_max)

Computationally fast Graphite kinetic and transport properties.

Differs from GraphiteSlow because the equilibrium potential is not piecewise here, making it less accurate, but faster to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Ds(x, T, fluxdir)

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)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

get_Mhyst(x)

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)

Calculate the exchange current density given the 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].

class bmlite.materials.GraphiteSiOx(alpha_a, alpha_c, Li_max)

Computationally fast GraphiteSiOx kinetic and transport properties.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Ds(x, T, fluxdir)

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

From Table V in “Development of Experimental Techniques for Parameterization “of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167 The functional form is the same as Graphite but is scaled so the average over x matches the paper above at 30C

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)

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

From Eq 9 in “Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

get_Mhyst(x)

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)

Calculate the exchange current density given the 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).

From Table VI in “Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167 The functional form is the same as Graphite but is scaled so the average over x matches the paper above at 30C

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].

class bmlite.materials.GraphiteSiOxSlow(alpha_a, alpha_c, Li_max, csvfile=None)

Computationally slow GraphiteSiOx kinetic and transport properties.

Differs from GraphiteSiOx because the equilibrium potential is piecewise here, making it more accurate, but slower to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

• csv_file (str | None) – Path to open circuit potential data containing 2 columns: x and V. If None, reads an internal data/graphite_SiOx_ocv.csv.

check_ocv_data(csvfile)

Check that the open circuit potential data has the right format

Parameters:

csvfile (str) – Path to open circuit potential data containing 2 columns: x and V.

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

class bmlite.materials.GraphiteSlow(alpha_a, alpha_c, Li_max)

Computationally slow Graphite kinetic and transport properties.

Differs from GraphiteFast because the equilibrium potential is piecewise here, making it more accurate, but slower to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

class bmlite.materials.GraphiteSlowExtrap(alpha_a, alpha_c, Li_max)

Computationally slow Graphite kinetic and transport properties.

Differs from GraphiteSlow because the piecewise equilibrium potential is extrapolated to be valid on the full [0, 1] range.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

class bmlite.materials.LFPInterp(alpha_a, alpha_c, Li_max)

LFP kinetic and transport properties, interpolated from data.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Ds(x, T, fluxdir)

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)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

get_Mhyst(x)

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)

Calculate the exchange current density given the 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].

class bmlite.materials.NMC532Fast(alpha_a, alpha_c, Li_max)

Computationally fast NMC532 kinetic and transport properties.

Differs from NMC532Slow because the equilibrium potential is not piecewise here, making it less accurate, but faster to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Ds(x, T, fluxdir)

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)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

get_Mhyst(x)

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)

Calculate the exchange current density given the 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].

class bmlite.materials.NMC532Slow(alpha_a, alpha_c, Li_max)

Computationally slow NMC532 kinetic and transport properties.

Differs from NMC532Fast because the equilibrium potential is piecewise here, making it more accurate, but slower to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

class bmlite.materials.NMC532SlowExtrap(alpha_a, alpha_c, Li_max)

Computationally slow NMC532 kinetic and transport properties.

Differs from NMC532Slow because the piecewise equilibrium potential is extrapolated to be valid on the full [0, 1] range.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

class bmlite.materials.NMC811(alpha_a, alpha_c, Li_max)

Computationally fast NMC811 kinetic and transport properties.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

get_Ds(x, T, fluxdir)

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

From Table V in “Development of Experimental Techniques for Parameterization “of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167 The functional form is the same as NMC532 but is scaled so the average over x matches the paper above at 30C.

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)

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

From Eq 8 in “Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].

get_Mhyst(x)

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)

Calculate the exchange current density given the 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).

From Table VI in “Development of Experimental Techniques for Parameterization of Multi-scale Lithium-ion Battery Models”, Chen et al., J. of the Electrochemical Society, 2020 Vol. 167 The functional form is the same as NMC532 but is scaled so the average over x matches the paper above at 30C.

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].

class bmlite.materials.NMC811Slow(alpha_a, alpha_c, Li_max, csvfile=None)

Computationally slow NMC811 kinetic and transport properties.

Differs from NMC811 because the equilibrium potential is piecewise here, making it more accurate, but slower to evaluate.

Parameters:

• alpha_a (float) – Anodic symmetry factor in Butler-Volmer expression [-].

• alpha_c (float) – Cathodic symmetry factor in Butler-Volmer expression [-].

• Li_max (float) – Maximum lithium concentration in solid phase [kmol/m3].

• csv_file (str | None) – Path to open circuit potential data containing 2 columns: x and V. If None, reads an internal data/nmc811_ocv.csv.

check_ocv_data(csvfile)

Check that the open circuit potential data has the right format

Parameters:

csvfile (str) – Path to open circuit potential data containing 2 columns: x and V.

get_Eeq(x)

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

Parameters:

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

Returns:

Eeq (float) – Equilibrium potential [V].