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
`iw.pipeline.calculations.ElectrodeCapacity(electrode=..., use_stoich_window=...)`	Solves the capacity equation for whichever quantity (`c_max`, `eps`, `L`, `A`, capacity, …) you didn’t supply
`iw.pipeline.calculations.CellMass()`	Sums electrode, separator, and current-collector masses from densities and thicknesses
`iw.pipeline.calculations.CyclableLithium()`	Total shuttling lithium from electrode capacities and initial stoichiometries
`iw.pipeline.calculations.ElectrodeSOH()`	Stoichiometry windows at 0% and 100% SOC from cell capacity and the electrode OCPs
`iw.pipeline.calculations.StoichiometryLimitsFromCapacity(electrode=...)`	Minimum/maximum stoichiometries from electrode capacity and excess-capacity values
`iw.pipeline.calculations.ElectrodeGeometryFromLoading(electrode=...)`	Electrode thickness, active material volume fraction and porosity from coating mass loading and press density
`iw.pipeline.calculations.ElectrodeBalanceFromFirstCycleEfficiency()`	All four stoichiometry limits and the initial concentrations at 100% SOC from the cell design and its first cycle efficiency

Capacity from electrode geometry

import ionworks as iw

known = iw.pipeline.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 = iw.pipeline.calculations.ElectrodeCapacity(electrode="positive")

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

client = iw.api.Client()
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 as iw

mass = iw.pipeline.calculations.CellMass()

pipeline = iw.pipeline.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 as iw

pipeline = iw.pipeline.Pipeline({
    "known": known,
    "Q_pos": iw.pipeline.calculations.ElectrodeCapacity(electrode="positive"),
    "Q_neg": iw.pipeline.calculations.ElectrodeCapacity(electrode="negative"),
    "esoh": iw.pipeline.calculations.ElectrodeSOH(),
    "q_li": iw.pipeline.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:

import ionworks as iw

iw.pipeline.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.

Electrode balance from a cell design

When you know how a cell is built but have no fitted electrode capacities, derive the electrode geometry from the coating and balance the electrodes from the first cycle efficiency:

import ionworks as iw

design = iw.pipeline.direct_entries.DirectEntry(
    parameters={
        "Positive electrode coating mass per unit area [g.cm-2]": 0.026,
        "Positive electrode press density [g.cm-3]": 3.5,
        "Positive electrode active material mass fraction": 0.96,
        "Positive electrode crystal density [g.cm-3]": 4.75,
        "Positive electrode active volume fraction of solid": 0.9,
        # … the same five for the negative electrode
        "First cycle efficiency": 0.9,
        # … electrode OCPs, maximum concentrations, electrode dimensions and OCV limits
    },
)

pipeline = iw.pipeline.Pipeline({
    "design": design,
    "geometry_pos": iw.pipeline.calculations.ElectrodeGeometryFromLoading(electrode="positive"),
    "geometry_neg": iw.pipeline.calculations.ElectrodeGeometryFromLoading(electrode="negative"),
    "balance": iw.pipeline.calculations.ElectrodeBalanceFromFirstCycleEfficiency(),
})

ElectrodeGeometryFromLoading turns each electrode’s coating mass per unit area and press density into its thickness, active material volume fraction and porosity. ElectrodeBalanceFromFirstCycleEfficiency then sets the four stoichiometry limits for the lithium left after the first cycle, and the initial concentrations at 100% SOC. Together they replace the ElectrodeCapacity and StoichiometryLimitsFromCapacity chain above. The formation loss is taken against the positive electrode’s capacity: the cyclable lithium is the first cycle efficiency times that capacity, so it follows the cathode loading in a design study. For a composite negative electrode such as graphite/SiOx, add "particle phases": ("2", "1") (and the model’s "open-circuit potential" option if a phase has hysteresis); each phase then gets its own stoichiometry limits and initial concentration. Both check their inputs when the pipeline runs. A first cycle efficiency outside (0, 1], or a loading that gives a volume fraction or porosity outside (0, 1) is reported as an error naming the values to check.