Cyclable Lithium Calculations

class ionworkspipeline.calculations.CyclableLithium(method='electrode capacities', options=None)

Calculate the amount of cyclable lithium capacity.

During cycling, lithium ions shuttle between the negative and positive electrodes. The cyclable lithium is the total lithium that can be reversibly transferred - it sets the upper limit on cell capacity.

\[Q_{Li} = \theta_n \cdot Q_n + \theta_p \cdot Q_p\]

where:

  • \(Q_{Li}\) is the cyclable lithium capacity [A h]

  • \(\theta_n, \theta_p\) are the lithium stoichiometries in each electrode

  • \(Q_n, Q_p\) are the electrode capacities

Two calculation methods are available:

From electrode stoichiometries (method="electrode capacities"): When you know the stoichiometry state at a reference point (typically 100% SOC). This is the most direct method when you have electrode-level stoichiometry data.

From formation loss (method="formation loss"): During formation, some lithium is consumed forming the SEI layer:

\[Q_{Li} = f \cdot Q_p\]

where \(f\) is the parameter “Formation lithium loss” representing the fraction of initial positive electrode lithium that remains cyclable after formation.

Parameters

methodstr, default=”electrode capacities”

The method to use: “electrode capacities” or “formation loss”.

optionsdict, optional

Options for the calculation:

  • 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).

Notes

Why cyclable lithium matters:

  • Cell capacity: The usable cell capacity cannot exceed the cyclable lithium. Even if both electrodes have high individual capacities, the cell is limited by the lithium available to shuttle between them.

  • Degradation tracking: Loss of cyclable lithium is a primary degradation mechanism. SEI growth consumes lithium, lithium plating traps lithium as metallic deposits, and particle cracking can isolate lithium in inactive regions.

  • Electrode balancing: The ratio of cyclable lithium to electrode capacity determines utilization (negative-limited, positive-limited, or lithium-limited).

The stoichiometries \(\theta_n\) and \(\theta_p\) should be evaluated at the same state of charge (typically 100% SOC or the point of maximum lithiation of the negative electrode).

Warnings

Cyclable lithium is not directly measurable - it must be inferred from:

  • Half-cell characterization of both electrodes

  • Full-cell OCV fitting

  • Electrode stoichiometry estimation (ESOH)

Examples

Calculate cyclable lithium from electrode stoichiometries:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.CyclableLithium(method="electrode capacities")
>>> params = iwp.ParameterValues({
...     "Negative electrode capacity [A.h]": 3.5,
...     "Positive electrode capacity [A.h]": 3.0,
...     "Initial stoichiometry in negative electrode": 0.8,
...     "Initial stoichiometry in positive electrode": 0.3,
... })
>>> result = calc.run(params)
>>> "Cyclable lithium capacity [A.h]" in result
True

Calculate cyclable lithium from formation loss:

>>> calc = iwp.calculations.CyclableLithium(method="formation loss")
>>> params = iwp.ParameterValues({
...     "Positive electrode capacity [A.h]": 3.0,
...     "Formation lithium loss": 0.95,  # 5% lost to SEI
... })
>>> result = calc.run(params)
>>> f"{result['Cyclable lithium capacity [A.h]']:.2f}"
'2.85'

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Calculate cyclable lithium capacity.