Capacity Calculations

class ionworkspipeline.calculations.ElectrodeCapacity(electrode, use_stoich_window=False, method='auto', phase=None)

Calculate electrode capacity and related parameters from the capacity equation.

The capacity of an electrode is determined by:

\[Q = c_{max} \cdot \varepsilon_{AM} \cdot L \cdot A \cdot n_{elec}\cdot (\theta_{max} - \theta_{min}) \cdot \frac{F}{3600}\]

where:

• \(Q\) is the electrode capacity [A h]

• \(c_{max}\) is the maximum lithium concentration [mol/m^3]

• \(\varepsilon_{AM}\) is the active material volume fraction

• \(L\) is the electrode thickness [m]

• \(A\) is the electrode area [m^2]

• \(n_{elec}\) is the number of electrodes connected in parallel to make a cell (defaults to 1 if not provided)

• \(\theta_{max} - \theta_{min}\) is the usable stoichiometry range

• \(F\) is Faraday’s constant (96485 C/mol)

• The 3600 converts from A s to A h

The capacity equation relates seven parameters (six if n_elec is not provided, since it defaults to 1). If you know all but one, this calculation automatically determines which parameter is missing and solves for it.

The capacity can also be specified via:

• Electrode loading [A.h.cm-2]: Capacity per unit area

• Theoretical capacity: From crystal density, fraction of Li per mole of material, and molecular mass of active material

Parameters

electrodestr

Electrode to calculate capacity for: “positive” or “negative”.

use_stoich_windowbool, default=False

Whether to use stoichiometry limits in the calculation. Set True if capacity is based on a voltage window (e.g., 0-100% SOC from RPT). Set False if capacity represents the full material limit (e.g., from OCP fitting).

methodstr, default=”auto”

Calculation method. Use “auto” to automatically determine based on inputs.

phasestr | None, default=None

Phase for multi-phase materials: “primary” or “secondary”.

Notes

Where these parameters typically come from:

• \(c_{max}\): Material specification or literature

• \(\varepsilon_{AM}\): Electrode formulation or fitting

• \(L\): Direct measurement or electrode specification

• \(A\): Cell design or measurement

• \(n_{elec}\): Cell design or measurement

• \(\theta_{max}, \theta_{min}\): OCP fitting or electrode SOH calculation

When using use_stoich_window=True, the calculation uses the actual stoichiometry range accessible during cycling. This gives a more realistic capacity that accounts for the voltage limits preventing full lithiation/delithiation.

Warnings

The capacity equation gives the theoretical capacity based on material properties. The practical capacity is often lower due to:

• Incomplete lithiation/delithiation (stoichiometry limits don’t reach 0 or 1)

• Inactive material regions

• Kinetic limitations at high rates

Examples

Calculate maximum concentration when capacity is known (common when you have capacity from cell characterization but don’t have detailed material data):

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.ElectrodeCapacity("positive", use_stoich_window=False)
>>> params = iwp.ParameterValues({
...     "Positive electrode capacity [A.h]": 3.0,
...     "Positive electrode active material volume fraction": 0.65,
...     "Positive electrode thickness [m]": 80e-6,
...     "Electrode area [m2]": 0.1,
... })
>>> result = calc.run(params)
>>> float(result["Maximum concentration in positive electrode [mol.m-3]"]) > 0
True

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Solve capacity equation for the missing parameter.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters. Must provide all capacity equation variables except one.

Returns

iwp.ParameterValues

The calculated missing parameter and optionally the electrode capacity.

class ionworkspipeline.calculations.MSMRFullCellCapacities(data, method='total capacity')

Calculate capacity parameters from the MSMR full-cell balance.

In a full cell, the usable capacity is limited by the electrode with lower capacity in the operating voltage window. The total electrode capacity can be split into three components:

\[Q_{tot} = Q_{low,ex} + Q_{use} + Q_{up,ex}\]

where:

• \(Q_{low,ex}\) is the lower excess capacity - lithium that stays in the electrodes below the operating window

• \(Q_{use}\) is the useable capacity - lithium actually cycled in the voltage window

• \(Q_{up,ex}\) is the upper excess capacity - lithium remaining above the operating window

This calculation extracts the useable capacity from data and computes the missing capacity parameters (either total capacity or upper excess capacity depending on the method).

Parameters

datastr or dict

The data to use to calculate the useable capacity, see FittingObjective.

methodstr, default=”total capacity”

The format of the parameters. One parameter is always the lower excess capacity, and this option determines the other parameter, which can be either “total capacity” or “upper excess capacity”.

Notes

The electrode balancing determines:

• N/P ratio: The ratio of negative to positive electrode capacity

• Cyclable lithium: The total lithium that participates in cycling

• Excess capacity: Capacity in each electrode that isn’t accessed during normal cycling

Examples

Requires capacity data and electrode excess capacities. Short example:

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.MSMRFullCellCapacities(
...     data=pd.DataFrame({"Capacity [A.h]": [0, 1, 2]}),
...     method="total capacity",
... )
>>> calc.source
'Calculation of capacity parameters from the MSMR full-cell balance'

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values)

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.HalfCellNominalCapacity(electrode: str)

Set nominal cell capacity and current function equal to electrode capacity.

For half-cell models and measurements, the nominal cell capacity equals the electrode capacity. This calculation copies the electrode capacity to the cell-level parameters required by PyBaMM.

Parameters

electrodestr

Working electrode: “negative” or “positive”.

Notes

When fitting half-cell data, use this calculation to ensure the current function is properly scaled to the electrode capacity.

Examples

>>> import ionworkspipeline as iwp
>>> calc = iwp.calculations.HalfCellNominalCapacity("positive")
>>> params = iwp.ParameterValues({"Positive electrode capacity [A.h]": 3.0})
>>> result = calc.run(params)
>>> result["Nominal cell capacity [A.h]"]
3.0
>>> result["Current function [A]"]
3.0

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Copy electrode capacity to cell-level capacity parameters.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters containing electrode capacity.

Returns

iwp.ParameterValues

Cell-level capacity parameters for PyBaMM half-cell models.