Calculations¶

Derived-parameter calculation schemas. Mirrors ionworkspipeline.calculations.

Schemas for calculations.

class ionworks_schema.calculations.AreaToSquareWidthHeight(source=None)¶

Bases: Calculation

Calculate electrode height and width from area assuming square geometry.

Reads "Electrode area [m2]" and produces "Electrode height [m]" and "Electrode width [m]" as sqrt(area). Useful when only total electrode area is known.

Examples¶

>>> calc = iws.calculations.AreaToSquareWidthHeight()
>>> config = iws.Pipeline({"geometry": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ArrheniusDiffusivityFromMSMRData(electrode, data, direction='', phase='', options=None)¶

Bases: Calculation

Calculate the diffusivity from OCP data as

\[D = - \frac{F}{RT_{ref}} D_{ref} x (1-x) \frac{dU}{dx} \exp(E / R (1 / T_{ref} - 1 / T))\]

where $D_{ref}$ is the reference diffusivity, $x$ is the stoichiometry, $U$ is the open-circuit potential, $R$ is the gas constant, $F$ is Faraday’s constant, $T$ is the temperature, $T_{ref}$ is the reference temperature, and $E$ is the activation energy. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters¶

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

dataDataLoader, DataFrame, str, or dict

OCP data with the following columns:

“Stoichiometry” : array
“Voltage [V]” : array

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsMSMRDiffusivityOptions or dict, optional

See MSMRDiffusivityOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: MSMRDiffusivityOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ArrheniusDiffusivityFromMSMRFunction(electrode, voltage_limits, direction='', phase='', options=None)¶

Bases: Calculation

Calculate the diffusivity from an OCP function as

\[D = - \frac{F}{RT_{ref}} D_{ref} x (1-x) \frac{dU}{dx} \exp(E / R (1 / T_{ref} - 1 / T))\]

where $D_{ref}$ is the reference diffusivity, $x$ is the stoichiometry, $U$ is the open-circuit potential, $R$ is the gas constant, $F$ is Faraday’s constant, $T$ is the temperature, $T_{ref}$ is the reference temperature, and $E$ is the activation energy. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters¶

electrodestr: The electrode to calculate the diffusivity for (either “positive” or “negative”).
voltage_limitstuple[float, float]: The voltage limits to use for the OCP data.
directionstr, optional: Specifies lithiation or delithiation for hysteresis models. Default is an empty string.
phasestr, optional: Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.
optionsMSMRDiffusivityOptions or dict, optional: See MSMRDiffusivityOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

voltage_limits: tuple[int | float, int | float] | list[int | float]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: MSMRDiffusivityOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ArrheniusLogLinear(data, reference_temperature=None, include_func=False)¶

Bases: Calculation

Fit an Arrhenius (log-linear) temperature dependence to a quantity measured at several temperatures.

Parameters¶

dataDataLoader, DataFrame, str, or dict: Measured values at each temperature.
reference_temperaturefloat, optional: Reference temperature (in K) used to anchor the Arrhenius fit. If None, a default is chosen from the data.
include_funcbool, optional: If True, also output an interpolant function so the value can be evaluated at any temperature, not just the measured ones. Default False.

Examples¶

>>> calc = iws.calculations.ArrheniusLogLinear(data="path/to/temperature_sweep.csv")
>>> config = iws.Pipeline({"arrhenius": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

reference_temperature: int | float | None¶

include_func: bool¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.AverageMSMRParameters(electrode, options=None)¶

Bases: Calculation

Average the MSMR species parameters across the lithiation and delithiation directions for one electrode.

Useful when you’ve fit the MSMR parameters separately in each direction (to capture hysteresis) but now want a single, direction-independent parameter set for downstream simulations.

Parameters¶

electrodestr: Electrode whose MSMR parameters are being averaged.
optionsAverageMSMRParametersOptions or dict, optional: See AverageMSMRParametersOptions for the available keys.

Examples¶

>>> calc = iws.calculations.AverageMSMRParameters(electrode="positive")
>>> config = iws.Pipeline({"average": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

options: AverageMSMRParametersOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.Calculation(source=None)¶

Bases: BaseSchema

A pipeline step that derives one or more parameters from others without fitting to data.

A calculation reads existing parameters, applies an algebraic or numerical recipe, and writes new parameters back into the parameter set. Typical uses are computing geometric properties (volume, surface area), capacity-related quantities, stoichiometry windows, or concentrations.

Parameters¶

sourcestr, optional: Free-text note describing where the calculation method comes from (paper citation, algorithm description). Optional and only used by some subclasses.

Extends: ionworks_schema.base.BaseSchema

source: str | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.CellMass(model_options=None)¶

Bases: Calculation

Compute the total cell mass in kilograms by summing the masses of the electrodes, separator, and current collectors from their densities, porosities, and thicknesses.

Adds Cell mass [kg] to the parameter set so downstream calculations (e.g. specific heat capacity, gravimetric energy density) can use it.

Parameters¶

model_optionsdict, optional: The pybamm model options — needed only when the cell has composite electrodes so the right phase masses get summed.

Initial credit: PyBOP team

Examples¶

>>> calc = iws.calculations.CellMass()
>>> config = iws.Pipeline({"cell_mass": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_options: dict[str, Any] | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.CyclableLithium(method='electrode capacities', options=None)¶

Bases: Calculation

Calculation of amount of cyclable lithium capacity, either based on previously calculated electrode capacities and initial stoichiometries (“electrode capacities” option), or based on the initial positive electrode capacity and some formation loss (“formation loss” option).

The latter option assumes that before formation the amount of cyclable lithium available is equal to the amount of lithium in the positive electrode (positive electrode starts out fully lithiated, negative electrode starts out fully delithiated), and that a fixed fraction, f, of that lithium is lost during the formation process. Then, the cyclable lithium capacity is given by

\[Q_Li = f * Q_p\]

where f is the parameter “Formation lithium loss” and Q_p is the parameter “Positive electrode capacity [A.h]”.

Parameters¶

methodstr, optional: The method to use to calculate the cyclable lithium capacity. Either “electrode capacities” or “formation loss”. Default is “electrode capacities”.
optionsCyclableLithiumOptions or dict, optional: See CyclableLithiumOptions for the available keys.

Examples¶

>>> calc = iws.calculations.CyclableLithium(method="electrode capacities")
>>> config = iws.Pipeline({"cyclable_li": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

method: str¶

options: CyclableLithiumOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DensityFromVolumeAndMass(source=None)¶

Bases: Calculation

Calculate the density from the mass and volume.

Examples¶

>>> calc = iws.calculations.DensityFromVolumeAndMass()
>>> config = iws.Pipeline({"density": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DiameterToSquareWidthHeight(source=None)¶

Bases: Calculation

Sets the electrode height and width to be the square root of the electrode cross-sectional area, calculated from the diameter (for a coin cell).

Examples¶

>>> calc = iws.calculations.DiameterToSquareWidthHeight()
>>> config = iws.Pipeline({"geometry": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DiffusivityDataInterpolant(electrode, data, direction='', phase='', options=None)¶

Bases: Calculation

A pipeline element that creates an interpolant for the diffusivity from an array of diffusivity data. This interpolant can be used to calculate the diffusivity at any point within the range of the data.

Parameters¶

electrodestr

The electrode to create the interpolant for (either “positive” or “negative”).

dataDataLoader, DataFrame, str, or dict

Diffusivity data with the following columns:

“Stoichiometry”array
The stoichiometry values.

“Diffusivity [m2.s-1]”array
The corresponding diffusivity values.

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsDiffusivityDataInterpolantOptions or dict, optional

See DiffusivityDataInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: DiffusivityDataInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DiffusivityFromMSMRData(electrode, data, direction='', phase='', options=None)¶

Bases: Calculation

Calculate the diffusivity from OCP data as

\[D = - \frac{F}{RT} D_{ref} x (1-x) \frac{dU}{dx}\]

where $D_{ref}$ is the reference diffusivity, $x$ is the stoichiometry, $U$ is the open-circuit potential, $R$ is the gas constant, $F$ is Faraday’s constant, and $T$ is the temperature. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters¶

electrodestr

The electrode to calculate the diffusivity for (either “positive” or “negative”).

dataDataLoader, DataFrame, str, or dict

OCP data with the following columns:

“Stoichiometry” : array
“Voltage [V]” : array

directionstr, optional

Specifies lithiation or delithiation for hysteresis models. Default is an empty string.

phasestr, optional

Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.

optionsMSMRDiffusivityOptions or dict, optional

See MSMRDiffusivityOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: MSMRDiffusivityOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DiffusivityFromMSMRFunction(electrode, voltage_limits, direction='', phase='', options=None)¶

Bases: Calculation

Calculate the diffusivity from an OCP function as

\[D = - \frac{F}{RT} D_{{ref}} x (1-x) \frac{dU}{dx}\]

where $D_{ref}$ is the reference diffusivity, $U$ is the open-circuit potential, $R$ is the gas constant, $F$ is Faraday’s constant, and $T$ is the temperature. This formula is derived from the transport equation in the MSMR model.

This calculation leaves the following parameter to be defined (e.g. by fitting to data):

Negative/Positive particle reference diffusivity [m2.s-1] ($D_{ref}$)

Parameters¶

electrodestr: The electrode to calculate the diffusivity for (either “positive” or “negative”).
voltage_limitstuple[float, float]: The voltage limits to use for the OCP data.
directionstr, optional: Specifies lithiation or delithiation for hysteresis models. Default is an empty string.
phasestr, optional: Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.
optionsMSMRDiffusivityOptions or dict, optional: See MSMRDiffusivityOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

voltage_limits: tuple[int | float, int | float] | list[int | float]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: MSMRDiffusivityOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.DiffusivityFromPulse(electrode, data, direction='', phase='', options=None)¶

Bases: Calculation

A pipeline element that calculates the diffusion coefficient from pulse data by directly using the voltage data from the pulse, without the need for fitting a model. This method uses eqn 26 from Wang et al. [Wang2022] to calculate the diffusion coefficient. Advantages of this method are that it is simple and fast. Disadvantages are that the calculation relies on assumptions that may not be valid in all cases, and the results may be sensitive to noise in the data since we only use 4 data points to calculate the diffusion coefficient.

Parameters¶

electrodestr: The electrode to calculate the diffusivity for (either “positive” or “negative”).
dataDataLoader, DataFrame, str, or dict: The pulse data. Must include columns "Current [A]", "Voltage [V]" and "Step number".
directionstr, optional: Specifies lithiation or delithiation for hysteresis models. Default is an empty string.
phasestr, optional: Specifies the phase (“primary” or “secondary”) for composite electrode models. Default is an empty string.
optionsDiffusivityFromPulseOptions or dict, optional: See DiffusivityFromPulseOptions for the available keys.

Raises¶

ValueError: If no rest step is found after the pulse.

References¶

[Wang2022]

Wang, A. A., et al. “Review of parameterisation and a novel database (LiionDB) for continuum Li-ion battery models.” Progress in Energy 4.3 (2022): 032004.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

direction: Literal['', 'delithiation', 'lithiation']¶

phase: Literal['', 'primary', 'secondary']¶

options: DiffusivityFromPulseOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

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

Bases: Calculation

A pipeline element that calculates variables related to the capacity. Automatically determines the method and unknown.

Solves the algebraic equation: c_max * eps * L * A_cc * (stoich_max - stoich_min) * F / 3600 = capacity,

where capacity can be the electrode capacity, the electrode loading times the area, or the theoretical capacity from the crystal density, fraction of Li per mole of material, and molecular mass of active material. All but one of c_max, eps, L, A_cc, stoich_max, and stoich_min must be provided (stoich_min and stoich_max are only required if use_stoich_window is True). Either capacity, loading, or the crystal density, fraction of Li per mole of material, and molecular mass of active material must be provided.

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

Examples¶

>>> calc = iws.calculations.ElectrodeCapacity(electrode="positive")
>>> config = iws.Pipeline({"capacity": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

use_stoich_window: bool¶

method: str¶

phase: Literal['', 'primary', 'secondary'] | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ElectrodeSOH(options=None)¶

Bases: Calculation

Calculate electrode stoichiometry windows from capacity using electrode SOH algorithm.

Reads "Nominal cell capacity [A.h]" (or "Cyclable lithium capacity [A.h]"), the electrode OCPs, and electrode dimensions/concentrations, and produces the stoichiometries at 0% and 100% SOC for both electrodes. Uses the algorithm from Mohtat et al. (2019) [Mohtat2019].

Parameters¶

optionsElectrodeSOHOptions or dict, optional: See ElectrodeSOHOptions for the available keys.

References¶

[Mohtat2019]

Mohtat, P., Lee, S., Siegel, J. B., & Stefanopoulou, A. G. (2019). Towards better estimability of electrode-specific state of health: Decoding the cell expansion. Journal of Power Sources, 427, 101-111.

Examples¶

>>> calc = iws.calculations.ElectrodeSOH()
>>> config = iws.Pipeline({"esoh": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

options: ElectrodeSOHOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ElectrodeSOHHalfCell(electrode, options=None)¶

Bases: Calculation

Calculate minimum and maximum electrode stoichiometries for a half-cell using the electrode-specific SOH algorithm.

See ElectrodeSOH for more details.

Parameters¶

electrodestr: The electrode to calculate the initial concentration for, either “positive” or “negative”.
optionsElectrodeSOHHalfCellOptions or dict, optional: See ElectrodeSOHHalfCellOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

options: ElectrodeSOHHalfCellOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ElectrodeVolumeFractionFromLoading(electrode, method)¶

Bases: Calculation

Calculate the volume fraction of active material in the electrodes from the loading and maximum concentration or from the coating mass and crystal density.

Parameters¶

electrode[“positive”, “negative”, “both”]: The electrode to calculate the volume fraction for.
method[“loading”, “coating mass”]: The method to use to calculate the volume fraction.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

method: str¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.ElectrodeVolumeFractionFromPorosity(electrode)¶

Bases: Calculation

Calculate the volume fraction of active material in the electrodes from the porosity and the active volume fraction of solid.

Parameters¶

electrodestr: The electrode to calculate the volume fraction for. Must be either “negative” or “positive”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.EntropicChangeDataInterpolant(electrode, data, options=None)¶

Bases: Calculation

Create an interpolant for the open-circuit entropic change from data.

Parameters¶

electrodestr: The electrode to create the interpolant for, either “positive”, “negative”, or “lumped”. If “lumped”, assumes a single electrode and modifies parameter names accordingly.
dataDataLoader, DataFrame, str, or dict: The data to use for the interpolant. Must have columns "Stoichiometry" and "Entropic change [V.K-1]".
optionsEntropicChangeInterpolantOptions or dict, optional: See EntropicChangeInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

options: EntropicChangeInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.EntropicChangeFromMSMRFunction(electrode, voltage_limits, options=None)¶

Bases: Calculation

Create an interpolant for the open-circuit entropic change from MSMR parameters.

Parameters¶

electrodestr: The electrode to create the interpolant for, either “positive” or “negative”.
voltage_limitstuple of float: The voltage limits to use to generate data for the interpolant.
optionsEntropicChangeInterpolantOptions or dict, optional: See EntropicChangeInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

voltage_limits: tuple[int | float, int | float] | list[int | float]¶

options: EntropicChangeInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.HalfCellNominalCapacity(electrode)¶

Bases: Calculation

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

For half-cell models, the cell capacity is determined by the working electrode capacity. Reads "Positive electrode capacity [A.h]" (or the negative-electrode equivalent) and writes the same value to "Nominal cell capacity [A.h]" and "Current function [A]", providing the cell-level parameters required by PyBaMM.

Parameters¶

electrodestr: Working electrode: “negative” or “positive”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialConcentrationFromInitialStoichiometryHalfCell(electrode, options=None)¶

Bases: Calculation

Calculate the initial concentration in the given electrode from the initial stoichiometry and maximum concentration.

Parameters¶

electrodestr: The electrode to calculate the initial concentration for, either “positive” or “negative”.
optionsInitialConcentrationFromInitialStoichiometryHalfCellOptions or dict, optional: See InitialConcentrationFromInitialStoichiometryHalfCellOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

options: InitialConcentrationFromInitialStoichiometryHalfCellOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialSOC(soc)¶

Bases: Calculation

Calculate initial electrode concentrations from target SOC.

Reads the stoichiometry windows ("Negative/Positive electrode stoichiometry at 0%/100% SOC") and maximum concentrations for both electrodes, and produces "Initial stoichiometry in negative/positive electrode" and the corresponding "Initial concentration in negative/positive electrode [mol.m-3]".

Parameters¶

socfloat: Target state of charge (0.0 to 1.0).

Examples¶

>>> calc = iws.calculations.InitialSOC(soc=0.5)
>>> config = iws.Pipeline({"initial_soc": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

soc: int | float | str¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialSOCHalfCell(electrode, soc, options=None)¶

Bases: Calculation

Calculate initial electrode concentration from target SOC for half-cell.

Reads the working electrode’s stoichiometry window and maximum concentration, and produces "Initial stoichiometry in positive/negative electrode" and "Initial concentration in positive/negative electrode [mol.m-3]".

Parameters¶

electrodestr: Working electrode: “negative” or “positive”.
socfloat | int | str: Target SOC. Can be numeric (0.0-1.0) or string (“0%”, “100%”, “minimum”, “maximum”).
optionsInitialSOCHalfCellOptions or dict, optional: See InitialSOCHalfCellOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

soc: int | float | str¶

options: InitialSOCHalfCellOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialSOCfromMaximumStoichiometry(options=None)¶

Bases: Calculation

Calculate the initial concentration in the negative and positive electrodes from the initial SOC and stoichiometry windows in each electrode.

Parameters¶

optionsInitialSOCfromMaximumStoichiometryOptions or dict, optional: See InitialSOCfromMaximumStoichiometryOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

options: InitialSOCfromMaximumStoichiometryOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialStoichiometryFromVoltageHalfCell(electrode, options=None)¶

Bases: Calculation

Calculate the initial stoichiometry in the given electrode from the initial voltage (i.e. find the stoichiometry that gives the correct voltage).

Parameters¶

electrodestr: The electrode to calculate the initial concentration for, either “positive” or “negative”.
optionsInitialStoichiometryFromVoltageHalfCellOptions or dict, optional: See InitialStoichiometryFromVoltageHalfCellOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

options: InitialStoichiometryFromVoltageHalfCellOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialStoichiometryFromVoltageMSMRHalfCell(electrode)¶

Bases: Calculation

Calculate the initial stoichiometry in the given electrode from the initial voltage (i.e. find the stoichiometry that gives the correct voltage) using the MSMR framework.

Parameters¶

electrodestr: The electrode to calculate the initial concentration for, either “positive” or “negative”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.InitialVoltageFromConcentration(electrode)¶

Bases: Calculation

Calculate initial voltage from target concentration using OCP inversion.

Reads "Positive/Negative electrode lithiation" (the OCP function), "Maximum concentration in positive/negative electrode [mol.m-3]", and "Initial concentration in positive/negative electrode [mol.m-3]", and produces "Initial voltage in positive/negative electrode [V]" by numerically inverting the lithiation function.

Parameters¶

electrodestr: Electrode: “negative” or “positive”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.JellyRollThermalDimensions(source=None)¶

Bases: Calculation

Calculate thermal properties of cylindrical jelly roll cell.

Reads "Jelly roll height [m]" and "Jelly roll radius [m]" and produces "Cell volume [m3]" and "Cell cooling surface area [m2]" assuming cylindrical geometry for thermal modeling.

Examples¶

>>> calc = iws.calculations.JellyRollThermalDimensions()
>>> config = iws.Pipeline({"thermal": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.LumpedHeatCapacityAndDensity(source=None)¶

Bases: Calculation

Sets the specific heat capacity and density for each cell component to the lumped (cell-level) values.

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.MSMRElectrodeSOHHalfCell(electrode)¶

Bases: Calculation

Calculate minimum and maximum electrode stoichiometries for a half-cell by evaluating the extent of lithiation at the minimum and maximum OCV.

See ElectrodeSOH for more details.

Parameters¶

electrodestr: The electrode to calculate the minimum and maximum stoichiometries for.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

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

Bases: Calculation

A pipeline element that calculates variables related to the capacity from the MSMR full-cell balance.

Parameters¶

dataDataLoader, DataFrame, str, or dict: The data to use to calculate the useable capacity, see FittingObjective.
parameter_formatstr, optional: The format of the parameters to fit. One parameter is always the lower excess capacity, and this option determines the other parameter, which can be either the total capacity or the upper excess capacity. Default is “total capacity”. (Q_tot = Q_lowex + Q_use + Q_uppex)

Extends: ionworks_schema.calculations.calculations.Calculation

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

method: str¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.MSMRFunction(electrode, direction=None, phase=None)¶

Bases: Calculation

Specifies the MSMR function for the open-circuit potential for the given electrode.

Parameters¶

electrodestr: The name of the electrode.
directionstr, optional: The direction of the MSMR function.
phasestr, optional: The phase of the MSMR function.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

direction: Literal['', 'delithiation', 'lithiation'] | None¶

phase: Literal['', 'primary', 'secondary'] | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.OCPDataInterpolant(electrode, data, options=None)¶

Bases: Calculation

Create an interpolant for the open-circuit voltage (OCP) from data.

Parameters¶

electrodestr: The electrode to create the interpolant for, either “positive”, “negative”, or “lumped”. If “lumped”, assumes a single electrode and modifies parameter names accordingly.
dataDataLoader, DataFrame, str, or dict: The data to use for the interpolant. Must have columns “Stoichiometry” and “Voltage [V]”.
optionsOCPDataInterpolantOptions or dict, optional: See OCPDataInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

options: OCPDataInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.OCPDataInterpolantMSMRExtrapolation(electrode, data, voltage_limits, options=None)¶

Bases: Calculation

Create an interpolant for the open-circuit voltage (OCP) from data and use MSMR parameters to extrapolate outside the data range and to convert capacity to stoichiometry.

The blending uses smooth weight functions to transition between OCP data in the observed stoichiometry range and MSMR extrapolation outside it. Mathematical formulation:

V(x) = w(x)·V_ocp(x) + (1-w(x))·V_msmr_corrected(x)

where w(x) is a smooth bump function based on the error function, and V_msmr_corrected includes a linear offset to ensure C⁰ continuity at the OCP boundaries.

Parameters¶

electrodestr: The electrode to create the interpolant for, either “positive” or “negative”.
dataDataLoader, DataFrame, str, or dict: The data to use for the interpolant. Must have columns “Capacity [A.h]” and “Voltage [V]”.
voltage_limitstuple of float: The voltage limits to use to generate MSMR data for extrapolation.
optionsOCPDataInterpolantOptions or dict, optional: See OCPDataInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

data: Annotated[str | DataFrame | DataFrame | DataLoader | TimeSeriesSpec | DataPayloadSpec | MetadataSpec | dict[str, Any], BeforeValidator(func=_route_measurement_input, json_schema_input_type=PydanticUndefined)]¶

voltage_limits: tuple[int | float, int | float] | list[int | float]¶

options: OCPDataInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.OCPMSMRInterpolant(electrode, voltage_limits, options=None)¶

Bases: Calculation

Create an interpolant for the open-circuit voltage (OCP) from MSMR parameters.

Parameters¶

electrodestr: The electrode to create the interpolant for, either “positive” or “negative”.
voltage_limitstuple of float: The voltage limits to use to generate data for the interpolant.
optionsOCPMSMRInterpolantOptions or dict, optional: See OCPMSMRInterpolantOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

voltage_limits: tuple[int | float, int | float] | list[int | float]¶

options: OCPMSMRInterpolantOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.OpenCircuitLimits(source=None)¶

Bases: Calculation

Set OCV limits equal to voltage cutoffs for SOC calculations.

Reads "Lower voltage cut-off [V]" and "Upper voltage cut-off [V]" and produces "Open-circuit voltage at 0% SOC [V]" and "Open-circuit voltage at 100% SOC [V]", establishing the relationship between SOC and voltage windows.

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.PorosityFromElectrodeVolumeFraction(electrode)¶

Bases: Calculation

Calculate the porosity from the active material volume fraction.

Parameters¶

electrodestr: The electrode to calculate the porosity for. Must be either “negative” or “positive”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.PouchCellThermalDimensions(source=None)¶

Bases: Calculation

Calculate thermal properties of rectangular pouch cell.

Reads "Pouch height [m]", "Pouch width [m]", and "Pouch thickness [m]", and produces "Cell volume [m3]" and "Cell cooling surface area [m2]" assuming rectangular prism geometry for thermal modeling.

Examples¶

>>> calc = iws.calculations.PouchCellThermalDimensions()
>>> config = iws.Pipeline({"thermal": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.SlopesToKnots(base_parameter_name, breakpoint_values, breakpoint_parameter_name)¶

Bases: Calculation

Converts slopes and initial value to knot values for piecewise linear interpolation.

This calculation takes as input: - An initial value at the first breakpoint - Slopes for each segment between consecutive breakpoints

And outputs: - The value at each breakpoint (knot values)

The conversion follows: y_{i+1} = y_i + slope_i * (x_{i+1} - x_i)

Reads the initial value at the first breakpoint and the slopes between consecutive breakpoints (e.g. "Particle diffusion time at SOC 0 [s]", "Particle diffusion time slope from SOC 0 to 0.5 [s]"), and produces the knot value at every breakpoint (e.g. "Particle diffusion time at SOC 0.5 [s]", "Particle diffusion time at SOC 1 [s]").

Parameters¶

base_parameter_namestr: The name of the parameter (e.g., “Particle diffusion time [s]”)
breakpoint_valueslist[float]: List of breakpoint values (e.g., [0.0, 0.5, 1.0])
breakpoint_parameter_namestr: Name of the breakpoint parameter (e.g., “SOC”, “Temperature [K]”)

Extends: ionworks_schema.calculations.calculations.Calculation

base_parameter_name: str¶

breakpoint_values: list[int | float]¶

breakpoint_parameter_name: str¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.SlopesToKnots2D(base_parameter_name, breakpoint1_values, breakpoint1_parameter_name, breakpoint2_values, breakpoint2_parameter_name)¶

Bases: Calculation

Converts slopes and initial value to knot values for 2D piecewise linear interpolation.

This calculation takes as input: - An initial value at (bp1_0, bp2_0) - Slopes along dimension 1 for the first row (at bp2_0) - Slopes along dimension 2 for all subsequent rows

And outputs: - The value at each 2D grid point (knot values)

The conversion follows the same strategy as PiecewiseInterpolation2D slopes mode: 1. Start with initial value at (bp1_0, bp2_0) 2. Use bp1-slopes to fill first row 3. Use bp2-slopes to fill remaining rows

Reads the initial value at (bp1_0, bp2_0), the bp1-slopes along the first row (e.g. "Diffusivity SOC-slope from SOC 0 to 1 at Temperature [K] 273.15 [m2.s-1]"), and the bp2-slopes for each bp1 grid point (e.g. "Diffusivity Temperature [K]-slope from Temperature [K] 273.15 to 323.15 at SOC 0 [m2.s-1]"), and produces the knot value at every 2D grid point.

Parameters¶

base_parameter_namestr: The name of the parameter (e.g., “Diffusivity [m2.s-1]”)
breakpoint1_valueslist[float]: List of first dimension breakpoint values (e.g., [0.0, 0.5, 1.0])
breakpoint1_parameter_namestr: Name of the first breakpoint parameter (e.g., “SOC”)
breakpoint2_valueslist[float]: List of second dimension breakpoint values (e.g., [273.15, 298.15])
breakpoint2_parameter_namestr: Name of the second breakpoint parameter (e.g., “Temperature [K]”)

Extends: ionworks_schema.calculations.calculations.Calculation

base_parameter_name: str¶

breakpoint1_values: list[int | float]¶

breakpoint1_parameter_name: str¶

breakpoint2_values: list[int | float]¶

breakpoint2_parameter_name: str¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.SpecificHeatCapacity(source=None)¶

Bases: Calculation

Calculate the specific heat capacity from the lumped heat capacity and cell mass.

Examples¶

>>> calc = iws.calculations.SpecificHeatCapacity()
>>> config = iws.Pipeline({"cp": calc}).to_config()

Extends: ionworks_schema.calculations.calculations.Calculation

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.StoichiometryAtMinimumSOC(electrode)¶

Bases: Calculation

Calculate the stoichiometry at the minimum SOC based on the stoichiometry at the maximum SOC, the electrode capacities, and the useable capacity.

Parameters¶

electrodestr: The electrode to calculate the initial concentration for, either “positive” or “negative”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.StoichiometryLimitsFromCapacity(options=None)¶

Bases: Calculation

Calculate the minimum and maximum stoichiometries for each electrode in a full-cell based on the electrode total capacity, lower and upper excess capacities.

Parameters¶

optionsStoichiometryLimitsFromCapacityOptions or dict, optional: See StoichiometryLimitsFromCapacityOptions for the available keys.

Extends: ionworks_schema.calculations.calculations.Calculation

options: StoichiometryLimitsFromCapacityOptions | None¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.

class ionworks_schema.calculations.SurfaceAreaToVolumeRatio(electrode)¶

Bases: Calculation

Calculate the surface area to volume ratio for the electrodes from the active material volume fraction and particle radius, assuming spherical particles.

Parameters¶

electrodestr: The electrode to calculate the surface area to volume ratio for, either “positive”, “negative” or “both”.

Extends: ionworks_schema.calculations.calculations.Calculation

electrode: Literal['positive', 'negative', 'lumped']¶

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True, 'validate_by_alias': True, 'validate_by_name': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None¶

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Args:: self: The BaseModel instance. context: The context.