Open Circuit Potential Interpolants

class ionworkspipeline.calculations.OCPDataInterpolant(electrode: str, data: DataFrame | DataFrame | DataLoader, options: dict[str, Any] | None = None)

Create an OCP interpolant from experimental data.

When you have half-cell OCP measurements, this calculation takes voltage vs. stoichiometry data, creates a smooth interpolant, and outputs a callable function for use in simulations.

Parameters

electrodestr

The electrode: “positive”, “negative”, or “lumped”.

datapd.DataFrame | pl.DataFrame | iwdata.DataLoader

OCP data with columns “Stoichiometry” and “Voltage [V]”.

optionsdict, optional

Calculation options:

  • interpolator: str, default=”linear” Interpolator type: “linear” or “cubic”.

  • tolerance: float, default=1e-6 Tolerance for restricting theta range to avoid interpolation issues.

  • direction: str, default=None OCP direction: “lithiation” or “delithiation”.

  • phase: str, default=None Phase for composite electrodes: “primary” or “secondary”.

Notes

Experimental data should be collected at low C-rates (typically C/20 or slower) to minimize kinetic effects and approximate true equilibrium.

Data Quality Considerations:

  • Kinetic overpotential: OCP shifted from equilibrium - use slower C-rate or average charge/discharge

  • Noise: Interpolant oscillates - smooth the data or use more points

  • Limited range: Extrapolation unreliable - use MSMR blending for extension

Examples

Requires OCP data with “Stoichiometry” and “Voltage [V]” columns. Short example:

>>> import ionworkspipeline as iwp
>>> import pandas as pd
>>> data = pd.DataFrame({
...     "Stoichiometry": [0.1, 0.5, 0.9],
...     "Voltage [V]": [3.5, 3.9, 4.2],
... })
>>> calc = iwp.calculations.OCPDataInterpolant(electrode="positive", data=data)
>>> result = calc.run(iwp.ParameterValues({}))
>>> "Positive electrode OCP [V]" in result
True

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.EntropicChangeDataInterpolant(electrode: str, data: DataFrame, options: dict[str, Any] | None = None)

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.

datapandas.DataFrame

The data to use for the interpolant. Must have columns “Stoichiometry” and “Entropic change [V.K-1]”.

optionsdict, optional

A dictionary of options to pass to the calculation.

  • interpolator: str, optional

    The interpolator to use for the interpolant. Can be “linear” or “cubic”. Default is “linear”.

  • tolerance: float

    The tolerance to use when restricting the data to avoid interpolation issues. Default is 1e-6.

  • phase: str, optional

    The phase of the electrode, either “primary” or “secondary”. Default is None, which means no phase is assumed.

  • scale factor: float, optional

    The scale factor to apply to the entropic change. Default is 1.

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.OCPMSMRInterpolant(electrode: str, voltage_limits: tuple[float, float], options: dict[str, Any] | None = None)

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.

optionsdict, optional

A dictionary of options to pass to the calculation.

  • interpolator: str, optional

    The interpolator to use for the interpolant. Can be “linear” or “cubic”. Default is “linear”.

  • tolerance: float

    The tolerance to use when restricting the data to avoid interpolation issues. Default is 1e-6.

  • direction: str

    The direction of the OCP, either “lithiation” or “delithiation”. Default is None, which means no directionality is assumed.

  • phase: str, optional

    The phase of the electrode, either “primary” or “secondary”. Default is None, which means no phase is assumed.

  • create_lithiation_function: bool

    Whether to create a lithiation function from the interpolant. Default is True.

Extends: ionworkspipeline.calculations.calculation.Calculation

plot_fit_results() → tuple[Figure, Axes]

Plot the fit results showing data and interpolant.

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.OCPDataInterpolantMSMRExtrapolation(electrode: str, data: DataFrame | DataFrame | DataLoader, voltage_limits: tuple[float, float], options: dict[str, Any] | None = None)

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

datapd.DataFrame | pl.DataFrame | iwdata.DataLoader

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.

optionsdict, optional

A dictionary of options to pass to the calculation.

  • interpolator: str, optional

    The interpolator to use for the interpolant. Can be “linear” or “cubic”. Default is “linear”.

  • tolerance: float

    The tolerance to use when restricting the data to avoid interpolation issues. Default is 1e-6.

  • direction: str

    The direction of the OCP, either “lithiation” or “delithiation”. Default is None, which means no directionality is assumed.

  • phase: str, optional

    The phase of the electrode, either “primary” or “secondary”. Default is None, which means no phase is assumed.

Extends: ionworkspipeline.calculations.calculation.Calculation

plot_fit_results() → tuple[Figure, Axes]

Plot the fit results showing data and interpolant.

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

class ionworkspipeline.calculations.EntropicChangeFromMSMRFunction(electrode: str, voltage_limits: tuple[float, float], options: dict[str, Any] | None = None)

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.

optionsdict, optional

A dictionary of options to pass to the calculation.

  • interpolator: str, optional

    The interpolator to use for the interpolant. Can be “linear” or “cubic”. Default is “linear”.

  • tolerance: float

    The tolerance to use when restricting the data to avoid interpolation issues. Default is 1e-6.

  • phase: str, optional

    The phase of the electrode, either “primary” or “secondary”. Default is None, which means no phase is assumed.

  • scale factor: float, optional

    The scale factor to apply to the entropic change. Default is 1.

Extends: ionworkspipeline.calculations.calculation.Calculation

run(parameter_values: ParameterValues) → ParameterValues

Execute the calculation to derive new parameters from inputs.

Parameters

parameter_valuesiwp.ParameterValues

Input parameters providing the values needed for this calculation.

Returns

iwp.ParameterValues

Newly calculated parameters to add to the pipeline.

ionworkspipeline.calculations.ocp_data_interpolant_from_csv(electrode: str, data_path: str, options: dict[str, Any] | None = None) → OCPDataInterpolant

Create an interpolant for the open-circuit voltage (OCP) from a CSV file.

Creates a OCPDataInterpolant object.

ionworkspipeline.calculations.entropic_change_data_interpolant_from_csv(electrode: str, data_path: str, options: dict[str, Any] | None = None) → EntropicChangeDataInterpolant

Create an interpolant for the entropic change from a CSV file.

Creates a EntropicChangeDataInterpolant object.