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.

When configuring a battery model, you may encounter several types of voltage and stoichiometry limits. This guide clarifies what each set of limits means, how they are used in simulation and parameter fitting, and why they all exist.

Voltage Limits

Voltage limits define the operating range of the cell. These values are critical for safety, model realism, and aligning with experimental protocols.

Cut-off Voltages

  • Lower voltage cut-off / Upper voltage cut-off
These are the actual voltage limits of the cell, typically set by the manufacturer or safety requirements. They define the voltage range within which the cell is cycled and are used as hard simulation limits.

OCV at SOC Endpoints

  • Open-circuit voltage at 0% / 100% SOC
These correspond to the stoichiometric endpoints of the electrodes. They define the open-circuit voltage at full lithiation or delithiation and are used to determine the stoichiometry range during parameterization. They should always lie within the upper and lower voltage cut-off values.
These two sets of voltage values often appear similar and typically take the same value, but serve different purposes:
  • Cut-off voltages are operational bounds
  • OCV endpoints are parameterization references for stoichiometry

Stoichiometry Limits

Stoichiometry describes the relative lithium content in each electrode and is central to determining electrode balancing and usable lithium.

Stoichiometry at 0%/100% SOC

  • Negative/positive electrode stoichiometry at 0%/100% SOC
These define the electrode stoichiometries corresponding to 0% and 100% state of charge based on the full-cell OCV curve. They are used to compute:
  • Initial lithium concentrations
  • Electrode balancing
These are the main stoichiometry bounds used in simulations.

Stoichiometry at Min/Max SOC

  • Negative/positive electrode stoichiometry at minimum/maximum SOC
These reflect the range of stoichiometry values observed in the data used for fitting. They are not used in simulation, only during parameter estimation.
These parameters provide better numerical convergence during fitting and help guide the optimization algorithm.

Lower/Upper Excess Capacity

  • Negative/positive electrode lower/upper excess capacity
These are alternative fitting parameters that reflect unused lithiation capacity outside the typical operating range. Like min/max stoichiometry, they are internal to the fitting process and not exposed during model evaluation.

How These Fit Together

1

Start with OCV Data

Obtain OCV data from the full cell
2

Determine Min/Max Stoichiometry

Use OCV data to determine min/max stoichiometry for each electrode
3

Derive 0%/100% Stoichiometry

Calculate the stoichiometry limits corresponding to OCV at 0%/100% SOC
4

Calculate Initial Conditions

Use stoichiometry limits to compute initial concentrations and cyclable lithium
5

Define Operating Range

Set cut-off voltages to define where the cell will actually be cycled

Stoichiometry Sign Convention

Key Design Principle: Stoichiometry always increases as voltage decreases for a given electrode.
ElectrodeSOCStoichiometryReason
Negative0%LowerDelithiated during discharge
Negative100%HigherLithiated during charge
Positive0%HigherLithiated during discharge
Positive100%LowerDelithiated during charge
This consistent convention helps maintain orientation across models.

Summary Table

Parameter TypeUsed InPurpose
Cut-off voltagesSimulationOperational safety bounds
OCV at 0%/100% SOCParameterizationStoichiometry range reference
Stoichiometry at 0%/100% SOCSimulationInitial concentrations, electrode balance
Stoichiometry at min/max SOCFitting onlyNumerical convergence, optimization guidance
Excess capacityFitting onlyUnused lithiation capacity
While having multiple definitions may seem excessive, each serves a specific role in maintaining model fidelity, improving fitting stability, and aligning with experimental protocols.