Electrode State of Health Calculations

class ionworkspipeline.calculations.ElectrodeSOH(options=None)

Calculate electrode stoichiometry windows from capacity using the electrode SOH algorithm [1].

When you measure a full-cell OCV curve, you observe:

\[V_{cell}(z) = U_p(\theta_p) - U_n(\theta_n)\]

But the cell voltage alone doesn’t tell you the individual electrode stoichiometries \(\theta_p\) and \(\theta_n\). The ESOH algorithm solves this inverse problem by finding the stoichiometry windows that best explain the full-cell OCV data.

The algorithm finds four key parameters that define the “stoichiometry windows”:

• \(\theta_{n,0}\): Negative electrode stoichiometry at 0% SOC

• \(\theta_{n,100}\): Negative electrode stoichiometry at 100% SOC

• \(\theta_{p,0}\): Positive electrode stoichiometry at 0% SOC

• \(\theta_{p,100}\): Positive electrode stoichiometry at 100% SOC

The algorithm satisfies three constraints:

1. Lower voltage limit: At 0% SOC, cell voltage equals the lower cutoff

2. Upper voltage limit: At 100% SOC, cell voltage equals the upper cutoff

3. Lithium conservation: Cyclable lithium is conserved between electrodes

Parameters

optionsdict, optional

Calculation options:

• known value: str, default=”cyclable lithium capacity” What capacity measure is known: “cyclable lithium capacity” (most common when both half-cells characterized) or “cell capacity” (when you have full-cell data but limited half-cell information).

Notes

The algorithm requires knowledge of the individual electrode OCP curves \(U_p(\theta)\) and \(U_n(\theta)\), typically from half-cell measurements.

Interpreting ESOH Results:

• Wide stoichiometry range: The electrode is well-utilized

• Narrow stoichiometry range: The electrode has excess capacity not being used

Degradation Signatures:

As a cell ages, the stoichiometry windows shift:

• Loss of lithium inventory (LLI): Both electrodes shift to lower stoichiometry at 100% SOC

• Loss of active material (LAM) in negative: Negative window narrows, positive utilization increases

• Loss of active material in positive: Positive window narrows, negative utilization increases

By tracking stoichiometry windows over aging, you can distinguish between LLI and LAM degradation modes.

References

[1]

Mohtat, P., Lee, S., Siegel, J. B., & Stefanopoulou, A. G. (2019). Towards better estimability of electrode-specific state of health: Decoding the cell expansion. Journal of Power Sources, 427, 101-111.

Examples

>>> calc = iwp.calculations.ElectrodeSOH(
...     options={"known value": "cell capacity"}
... )
>>> params = iwp.ParameterValues({
...     "Nominal cell capacity [A.h]": 1.5,
...     "Negative electrode OCP [V]": ocp_neg,
...     "Positive electrode OCP [V]": ocp_pos,
...     "Negative electrode active material volume fraction": 0.75,
...     "Positive electrode active material volume fraction": 0.665,
...     "Negative electrode thickness [m]": 85.2e-6,
...     "Positive electrode thickness [m]": 75.6e-6,
...     "Maximum concentration in negative electrode [mol.m-3]": 33133,
...     "Maximum concentration in positive electrode [mol.m-3]": 63104,
...     "Electrode width [m]": 0.207,
...     "Electrode height [m]": 0.137,
...     "Number of electrodes connected in parallel to make a cell": 1,
...     "Open-circuit voltage at 0% SOC [V]": 2.8,
...     "Open-circuit voltage at 100% SOC [V]": 4.2,
...     "Ambient temperature [K]": 298.15,
...     "Reference temperature [K]": 298.15,
...     "Positive electrode OCP entropic change [V.K-1]": 0,
...     "Negative electrode OCP entropic change [V.K-1]": 0,
... })
>>> result = calc.run(params)
>>> "Negative electrode stoichiometry at 0% SOC" in result
True

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute electrode SOH algorithm to determine stoichiometry windows.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters including OCP curves, dimensions, and capacity.

Returns

iwp.ParameterValues

Stoichiometry values at 0% and 100% SOC for both electrodes.

class ionworkspipeline.calculations.ElectrodeSOHHalfCell(electrode, options=None)

Calculate stoichiometry limits for a half-cell from voltage window.

For half-cell configurations, this simplified ESOH algorithm determines the stoichiometry limits from the voltage window by solving for the stoichiometries where the electrode OCP equals the voltage cutoffs.

Parameters

electrodestr

The electrode to calculate stoichiometry limits for: “positive” or “negative”.

optionsdict, optional

Calculation options:

• simulation_kwargs: dict, default=None Keyword arguments to pass to the simulation (iwp.Simulation).

Examples

Requires OCP, voltage limits, and concentration (many inputs). Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.ElectrodeSOHHalfCell("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.

class ionworkspipeline.calculations.OpenCircuitLimits

Set OCV limits equal to voltage cutoffs for SOC calculations.

Copies voltage cutoff parameters to OCV limit parameters, establishing the relationship between SOC and voltage windows.

Examples

>>> calc = iwp.calculations.OpenCircuitLimits()
>>> params = iwp.ParameterValues({
...     "Lower voltage cut-off [V]": 2.5,
...     "Upper voltage cut-off [V]": 4.2,
... })
>>> result = calc.run(params)
>>> result["Open-circuit voltage at 0% SOC [V]"]
2.5

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Copy voltage cutoffs to OCV limit parameters.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters with voltage cutoffs.

Returns

iwp.ParameterValues

OCV limit parameters matching voltage cutoffs.

class ionworkspipeline.calculations.MSMRElectrodeSOHHalfCell(electrode)

Calculate stoichiometry limits for a half-cell using MSMR lithiation function.

When using MSMR (Multi-Species Multi-Reaction) OCP models, the stoichiometry can be calculated directly from the voltage using the MSMR lithiation function. The MSMR model provides an analytical inverse, avoiding the numerical root-finding needed with interpolated OCP curves.

Parameters

electrodestr

The electrode to calculate stoichiometry limits for: “positive” or “negative”.

Examples

Requires MSMR parameters and voltage limits. Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.MSMRElectrodeSOHHalfCell("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.

class ionworkspipeline.calculations.StoichiometryLimitsFromCapacity(options=None)

Calculate stoichiometry limits from total capacity and excess capacities.

Determines the minimum and maximum stoichiometries for each electrode in a full-cell based on the electrode total capacity, lower and upper excess capacities.

The stoichiometry limits are related to capacity components:

\[\theta_{max} = \frac{Q_{total} - Q_{upper,excess}}{Q_{total}}\]

\[\theta_{min} = \frac{Q_{lower,excess}}{Q_{total}}\]

Parameters

optionsdict, optional

Calculation options:

• direction: str, default=None Direction for the calculation: “charge” or “discharge”. If specified, the lower and upper excess capacities are calculated based on direction.

• particle phases: tuple of str, default=(“1”, “1”) Specifies the number of phases for each electrode as a tuple (negative, positive). Each element can be “1” (single phase) or “2” (composite with Primary and Secondary phases).

Examples

Requires electrode capacities and excess capacities. Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.StoichiometryLimitsFromCapacity()
>>> # 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.

class ionworkspipeline.calculations.StoichiometryAtMinimumSOC(electrode)

Calculate the stoichiometry at the minimum SOC based on the stoichiometry at the maximum SOC, the electrode capacities, and the useable capacity.

Parameters

electrodestr

The electrode to calculate the initial concentration for, either “positive” or “negative”.

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.StoichiometryAtMinimumSOC("negative")
>>> params = iwp.ParameterValues({
...     "Negative electrode stoichiometry at maximum SOC": 0.95,
...     "Negative electrode capacity [A.h]": 3.0,
...     "Useable capacity [A.h]": 2.7,
... })
>>> result = calc.run(params)
>>> f"{result['Negative electrode stoichiometry at minimum SOC']:.2f}"
'0.05'

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.