Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt

Use this file to discover all available pages before exploring further.

Before running a simulation, you need to specify how lithium is distributed in each electrode. This determines the starting state of charge and affects the entire simulation. The Electrode State of Health (ESOH) algorithm finds the stoichiometry windows that map cell SOC to electrode lithiation states.

Why Initialization Matters

The initial concentration distribution affects:
  • Starting voltage: The cell begins at the OCV corresponding to the initial stoichiometry
  • Available capacity: How much charge can be extracted before hitting voltage limits
  • Simulation accuracy: Incorrect initialization leads to incorrect predictions throughout the simulation

The ESOH Problem

When you measure a full-cell OCV curve, you observe the difference between electrode potentials: Vcell(z)=Up(θp)Un(θn)V_{\text{cell}}(z) = U_p(\theta_p) - U_n(\theta_n) But the cell voltage alone doesn’t tell you the individual electrode stoichiometries. The ESOH algorithm solves this inverse problem by finding the stoichiometry windows that explain the full-cell OCV.

What ESOH Determines

ParameterMeaning
θn,0\theta_{n,0}Negative stoichiometry at 0% SOC
θn,100\theta_{n,100}Negative stoichiometry at 100% SOC
θp,0\theta_{p,0}Positive stoichiometry at 0% SOC
θp,100\theta_{p,100}Positive stoichiometry at 100% SOC
These define how each electrode is utilized across the SOC range—essential for accurate simulation and degradation tracking.

Calculation of Minimum and Maximum Stoichiometries

First, the minimum and maximum stoichiometries in each electrode (based on the voltage range) must be calculated.

Required Parameters

  • Initial concentration in <electrode> electrode [mol.m-3] (cs,t=0+,c_{s,t=0}^{+,-})
  • Voltage at 100% SOC [V] (V100V_{100})
  • Voltage at 0% SOC [V] (V0V_0)

System of Equations

The stoichiometries are found by solving: U+(x100,T)U(y100,T)V100=0U^+(x_{100}, T) - U^-(y_{100}, T) - V_{100} = 0 U+(x0,T)U(y0,T)V0=0U^+(x_0, T) - U^-(y_0, T) - V_0 = 0 where xx and yy are the stoichiometries of the positive and negative electrodes respectively, the subscript indicates the SOC percentage, TT is temperature, and UU is the open-circuit potential function.

Cyclable Lithium Constraint

By default, cyclable lithium inventory (QLiQ_{Li}) is used as the constraint to fully define the system: y100=QLix100QQ+y_{100} = \frac{Q_{Li} - x_{100} \cdot Q^-}{Q^+} y0=y100+QQ+y_0 = y_{100} + \frac{Q}{Q^+} where QQ is given by: Q=Q(x100x0)Q = Q^- \cdot (x_{100} - x_0)

Electrode Capacity Calculation

Each electrode capacity is calculated as: Q+,=A+,cs,0+,T+,εam+,Q^{+,-} = A^{+,-} \cdot c_{s,0}^{+,-} \cdot T^{+,-} \cdot \varepsilon_{am}^{+,-} where AA is electrode area, TT is electrode thickness, and εam\varepsilon_{am} is the active material volume fraction.

Initialization Options

Directly Specify Initial Concentration

The solver uses the value corresponding to Initial concentration in <electrode> electrode [mol.m-3] in the parameters object. To change the value, simply modify this parameter.

Initialization in Ionworks Pipeline

Ionworks Pipeline provides all of the above initialization methods via the parameters interface.
We generally recommend setting the initial concentrations based on an initial voltage observed in the data. The DataLoader object has an initial_voltage attribute, which is typically set to the last voltage in the step before the first step in the data.
This approach is suitable when the step before the first step to be fit is a long rest step. See the example notebooks for more details on using the parameters interface.

References

  1. Mohtat, Peyman, et al. “Towards better estimability of electrode-specific state of health: Decoding the cell expansion.” Journal of Power Sources 427 (2019): 101-111.
  2. Weng, Andrew, et al. “Modeling battery formation: Boosted sei growth, multi-species reactions, and irreversible expansion.” Journal of The Electrochemical Society 170.9 (2023): 090523.