Geometry & Capacity

Geometry and capacity calculations derive cell-level quantities from electrode dimensions and material properties. For the underlying equations and parameter definitions, see the Geometry & Capacity Guide.

Available calculations

Schema	Purpose
`iws.calculations.ElectrodeCapacity(electrode=..., use_stoich_window=...)`	Solves the capacity equation for whichever quantity (`c_max`, `eps`, `L`, `A`, capacity, …) you didn’t supply
`iws.calculations.CellMass()`	Sums electrode, separator, and current-collector masses from densities and thicknesses
`iws.calculations.CyclableLithium()`	Total shuttling lithium from electrode capacities and initial stoichiometries
`iws.calculations.ElectrodeSOH()`	Stoichiometry windows at 0% and 100% SOC from cell capacity and the electrode OCPs
`iws.calculations.StoichiometryLimitsFromCapacity(electrode=...)`	Minimum/maximum stoichiometries from electrode capacity and excess-capacity values

Capacity from electrode geometry

import ionworks_schema as iws
from ionworks import Ionworks

known = iws.direct_entries.DirectEntry(
    parameters={
        "Positive electrode active material volume fraction": 0.65,
        "Positive electrode thickness [m]": 80e-6,
        "Electrode area [m2]": 0.1,
        "Maximum concentration in positive electrode [mol.m-3]": 51217.0,
        # … stoichiometry limits if use_stoich_window=True
    },
)

q_pos = iws.calculations.ElectrodeCapacity(electrode="positive")

pipeline = iws.Pipeline({"known": known, "Q_pos": q_pos})

client = Ionworks()
submission = client.pipeline.create(pipeline)
client.pipeline.wait_for_completion(submission.id)
result = client.pipeline.result(submission.id)

Supply any five of the six parameters in the capacity equation and ElectrodeCapacity returns the missing one. Set use_stoich_window=True when the capacity corresponds to a voltage window rather than the full material limit.

Mass and energy density

import ionworks_schema as iws

mass = iws.calculations.CellMass()

pipeline = iws.Pipeline({
    "known": known,
    "cell_mass": mass,
})

The result adds "Cell mass [kg]" to the parameter set so downstream calculations (specific heat capacity, gravimetric energy density) can use it.

Stoichiometry windows and cyclable lithium

import ionworks_schema as iws

pipeline = iws.Pipeline({
    "known": known,
    "Q_pos": iws.calculations.ElectrodeCapacity(electrode="positive"),
    "Q_neg": iws.calculations.ElectrodeCapacity(electrode="negative"),
    "esoh": iws.calculations.ElectrodeSOH(),
    "q_li": iws.calculations.CyclableLithium(),
})

ElectrodeSOH reads the cell capacity and electrode OCPs and produces the stoichiometries at 0% and 100% SOC for both electrodes. CyclableLithium then combines those with the electrode capacities to give the total lithium that shuttles during cycling.

Composite electrodes

StoichiometryLimitsFromCapacity needs a usable capacity when either electrode is composite — that is, when its particle phases option contains "2", as it does for a graphite–silicon anode:

iws.calculations.StoichiometryLimitsFromCapacity(
    electrode="negative",
    options={"particle phases": ["2", "1"], "usable capacity": 4.85},
)

Omitting it is rejected when the configuration is validated, before the pipeline is submitted. usable capacity is per direction. A joint-hysteresis fit uses a different usable capacity on charge than on discharge, so run one calculation per direction with that direction’s value rather than sharing a single number between them.