Skip to main content
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

SchemaPurpose
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.

Geometry & Capacity (theory)

The capacity equation, mass balance, and N/P-ratio theory.

Pipelines overview

How calculations chain with direct entries and data fits.