Particle Diffusivity

class ionworkspipeline.calculations.DiffusivityFromPulse(electrode: str, data: dict[str, Any], direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

A pipeline element that calculates the diffusion coefficient from pulse data by directly using the voltage data from the pulse, without the need for fitting a model. This method uses eqn 26 from Wang et al. [1] to calculate the diffusion coefficient. Advantages of this method are that it is simple and fast. Disadvantages are that the calculation relies on assumptions that may not be valid in all cases, and the results may be sensitive to noise in the data since we only use 4 data points to calculate the diffusion coefficient.

Parameters

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

datadict

A dictionary containing the pulse data. Should have columns “Current [A]”, “Voltage [V]” and “Step number”.

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “step number”int

  The step number to use for the calculation. If not provided, the first non-rest step is used.

• “dt_IR”float

  The time to establish the IR drop, in seconds. If not provided, the IR drop is assumed to be established at the start of the pulse (first data point with that step number)

• “dt_pulse”float

  The time at which to calculate the diffusion coefficient, in seconds. If not provided, the diffusion coefficient will be calculated at the end of the pulse.

Raises

ValueError

If no rest step is found after the pulse.

References

[1]

Wang, A. A., et al. “Review of parameterisation and a novel database (LiionDB) for continuum Li-ion battery models.” Progress in Energy 4.3 (2022): 032004.

Examples

Requires pulse data (current, voltage, step number). Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.DiffusivityFromPulse(
...     electrode="positive",
...     data=pd.DataFrame({"Current [A]": [], "Voltage [V]": [], "Step number": []}),
... )
>>> calc.source
'Calculate diffusivity directly from pulse data'

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.DiffusivityDataInterpolant(electrode: str, data: DataFrame | DataFrame | DataLoader, direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

A pipeline element that creates an interpolant for the diffusivity from an array of diffusivity data. This interpolant can be used to calculate the diffusivity at any point within the range of the data.

Parameters

electrodestr

The electrode to create the interpolant for (either “positive” or “negative”).

datapd.DataFrame | pl.DataFrame | iwdata.DataLoader

Diffusivity data with the following columns:

• “Stoichiometry”array

  The stoichiometry values.

• “Diffusivity [m2.s-1]”array

  The corresponding diffusivity values.

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “interpolator”str

  The interpolator to use. Default is “linear”. For more options, see the documentation for pybamm.Interpolant

• “transformation”str

  The transformation to apply to the data before creating the interpolant. Options are “none” (default) or “log” (interpolant is created in log10 space).

• “scale factor”bool

  Whether to multiply the diffusivity by a scale factor. Default is False. If True, this leaves the following parameter to be defined (e.g. by fitting to data):

  • Negative/Positive particle diffusivity scale factor

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.DiffusivityFromMSMRData(electrode: str, data: DataFrame | DataFrame | DataLoader, direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

Calculate the diffusivity from OCP data as

\[D = - \frac{F}{RT} D_{ref} x (1-x) \frac{dU}{dx}\]

where \(D_{ref}\) is the reference diffusivity, \(x\) is the stoichiometry, \(U\) is the open-circuit potential, \(R\) is the gas constant, \(F\) is Faraday’s constant, and \(T\) is the temperature. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

• Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

datapd.DataFrame | pl.DataFrame | iwdata.DataLoader

OCP data with the following columns:

• “Stoichiometry” : array

• “Voltage [V]” : array

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “interpolator”str

  The interpolator to use. Default is “linear”. For more options, see the documentation for pybamm.Interpolant

• “x tolerance”float

  The tolerance for the stoichiometry values near 0 and 1. Default is 1e-6. Data points where x < tolerance or x > (1 - tolerance) are excluded from the calculation.

• “minimum dUdx”float

  The minimum value for the gradient of the open-circuit potential with respect to the stoichiometry. Default is 1e-6. When the absolute value of dU/dx is below this minimum, the corresponding y_data = x(1-x)dU/dx values are clipped.

Extends: ionworkspipeline.calculations.particle_diffusivity._BaseMSMRDiffusivity

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.ArrheniusDiffusivityFromMSMRData(electrode: str, data: DataFrame | DataFrame | DataLoader, direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

Calculate the diffusivity from OCP data as

\[D = - \frac{F}{RT_{ref}} D_{ref} x (1-x) \frac{dU}{dx} \exp(E / R (1 / T_{ref} - 1 / T))\]

where \(D_{ref}\) is the reference diffusivity, \(x\) is the stoichiometry, \(U\) is the open-circuit potential, \(R\) is the gas constant, \(F\) is Faraday’s constant, \(T\) is the temperature, \(T_{ref}\) is the reference temperature, and \(E\) is the activation energy. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

• Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

datapd.DataFrame | pl.DataFrame | iwdata.DataLoader

OCP data with the following columns:

• “Stoichiometry” : array

• “Voltage [V]” : array

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “interpolator”str

  The interpolator to use. Default is “linear”. For more options, see the documentation for pybamm.Interpolant

• “x tolerance”float

  The tolerance for the stoichiometry values near 0 and 1. Default is 1e-6. Data points where x < tolerance or x > (1 - tolerance) are excluded from the calculation.

• “minimum dUdx”float

  The minimum value for the gradient of the open-circuit potential with respect to the stoichiometry. Default is 1e-6. When the absolute value of dU/dx is below this minimum, the corresponding y_data = x(1-x)dU/dx values are clipped.

Extends: ionworkspipeline.calculations.particle_diffusivity._BaseMSMRDiffusivity

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.DiffusivityFromMSMRFunction(electrode: str, voltage_limits: tuple[float, float], direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

Calculate the diffusivity from an OCP function as

\[D = - \frac{F}{RT} D_{{ref}} x (1-x) \frac{dU}{dx}\]

where \(D_{ref}\) is the reference diffusivity, \(U\) is the open-circuit potential, \(R\) is the gas constant, \(F\) is Faraday’s constant, and \(T\) is the temperature. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

• Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

voltage_limitstuple[float, float]

The voltage limits to use for the OCP data.

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “interpolator”str

  The interpolator to use. Default is “linear”. For more options, see the documentation for pybamm.Interpolant

• “x tolerance”float

  The tolerance for the stoichiometry values near 0 and 1. Default is 1e-6. Data points where x < tolerance or x > (1 - tolerance) are excluded from the calculation.

• “minimum dUdx”float

  The minimum value for the gradient of the open-circuit potential with respect to the stoichiometry. Default is 1e-6. When the absolute value of dU/dx is below this minimum, the corresponding y_data = x(1-x)dU/dx values are clipped.

Extends: ionworkspipeline.calculations.particle_diffusivity._BaseMSMRDiffusivity

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.ArrheniusDiffusivityFromMSMRFunction(electrode: str, voltage_limits: tuple[float, float], direction: str = '', phase: str = '', options: dict[str, Any] | None = None)

Calculate the diffusivity from an OCP function as

\[D = - \frac{F}{RT_{ref}} D_{ref} x (1-x) \frac{dU}{dx} \exp(E / R (1 / T_{ref} - 1 / T))\]

where \(D_{ref}\) is the reference diffusivity, \(x\) is the stoichiometry, \(U\) is the open-circuit potential, \(R\) is the gas constant, \(F\) is Faraday’s constant, \(T\) is the temperature, \(T_{ref}\) is the reference temperature, and \(E\) is the activation energy. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

• Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

voltage_limitstuple[float, float]

The voltage limits to use for the OCP data.

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsdict, optional

Options for the calculation. The available options are:

• “interpolator”str

  The interpolator to use. Default is “linear”. For more options, see the documentation for pybamm.Interpolant

• “x tolerance”float

  The tolerance for the stoichiometry values near 0 and 1. Default is 1e-6. Data points where x < tolerance or x > (1 - tolerance) are excluded from the calculation.

• “minimum dUdx”float

  The minimum value for the gradient of the open-circuit potential with respect to the stoichiometry. Default is 1e-6. When the absolute value of dU/dx is below this minimum, the corresponding y_data = x(1-x)dU/dx values are clipped.

Extends: ionworkspipeline.calculations.particle_diffusivity._BaseMSMRDiffusivity

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.