MSMR functions

class ionworkspipeline.calculations.MSMRFunction(electrode, direction=None, phase=None)

Create the MSMR lithiation function for an electrode.

Creates a lithiation function \(\theta(U)\) from MSMR parameters that maps voltage to stoichiometry. This is the inverse of a typical OCP curve.

Parameters

electrodestr

The electrode: “positive” or “negative”.

directionstr, optional

The direction for hysteretic materials: “lithiation” or “delithiation”. Default is None (no directionality).

phasestr, optional

The phase for composite electrodes: “primary” or “secondary”. Default is None (single phase).

Notes

The lithiation/delithiation terminology refers to the electrode, not the cell. For the positive electrode, lithiation occurs during cell discharge.

For composite electrodes (e.g., silicon-graphite blends), each phase has its own set of MSMR species with separate parameters.

Examples

Basic usage:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.MSMRFunction(electrode="positive")

Direction-dependent MSMR for materials with hysteresis:

>>> calc_lith = iwp.calculations.MSMRFunction(
...     electrode="positive", direction="lithiation"
... )
>>> calc_delith = iwp.calculations.MSMRFunction(
...     electrode="positive", direction="delithiation"
... )

Composite electrode:

>>> calc_primary = iwp.calculations.MSMRFunction(
...     electrode="negative", phase="primary"
... )

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.AverageMSMRParameters(electrode, options=None)

Average MSMR parameters over lithiation and delithiation directions.

After fitting MSMR parameters separately to lithiation and delithiation data, this calculation produces a single averaged parameter set for simulation. It averages:

  • \(U_j^0\) values (standard potentials)

  • \(X_j\) values (host site fractions)

  • \(\omega_j\) values (ideality factors)

The resulting parameters represent the “hysteresis-free” OCP that lies between the lithiation and delithiation curves.

Parameters

electrodestr

The electrode: “positive” or “negative”.

optionsdict, optional

Calculation options:

  • species_format: str, default=”Xj” The format of the species: “Xj” (occupancy fraction) or “Qj” (capacity).

  • phase: str, default=None The phase for composite electrodes: “primary” or “secondary”.

Examples

Requires lithiation and delithiation MSMR parameters. Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.AverageMSMRParameters(electrode="positive")
>>> # result = calc.run(params)

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.