Piecewise Interpolants

Piecewise interpolants produce smooth, differentiable functions of one or two breakpoint variables — useful for SOC-dependent diffusivities, temperature-dependent transport, and OCP curves. For the math (smooth heaviside, knots vs slopes, blending), see the Piecewise Interpolants Guide.

1D piecewise interpolant

import ionworks_schema as iws

D_neg = iws.direct_entries.PiecewiseInterpolation1D(
    base_parameter_name="Negative particle diffusivity [m2.s-1]",
    breakpoint_values=[0.0, 0.3, 0.7, 1.0],
    breakpoint_parameter_name="SOC",
    smoothing=1e-4,
)

values = iws.direct_entries.DirectEntry(
    parameters={
        "Negative particle diffusivity at SOC 0 [m2.s-1]": 3.9e-14,
        "Negative particle diffusivity at SOC 0.3 [m2.s-1]": 5.2e-14,
        "Negative particle diffusivity at SOC 0.7 [m2.s-1]": 4.8e-14,
        "Negative particle diffusivity at SOC 1 [m2.s-1]": 3.5e-14,
    },
)

pipeline = iws.Pipeline({"D_neg values": values, "D_neg": D_neg})

The interpolant reads one parameter per breakpoint (the names follow "<base> at <breakpoint_parameter_name> <value> [units]") and produces a smooth function of the breakpoint variable.

2D piecewise interpolant

For parameters varying with two variables (e.g. SOC and temperature):

import ionworks_schema as iws

D_neg = iws.direct_entries.PiecewiseInterpolation2D(
    base_parameter_name="Negative particle diffusivity [m2.s-1]",
    breakpoint1_values=[0.0, 0.5, 1.0],
    breakpoint1_parameter_name="SOC",
    breakpoint2_values=[273.15, 298.15, 323.15],
    breakpoint2_parameter_name="Temperature [K]",
    smoothing1=1e-4,
    smoothing2=0.1,
)

Use different smoothing parameters when the two axes have very different scales (SOC ∈ [0, 1] vs Temperature ∈ [273, 323] K).

OCP interpolants

Schema	What it builds
`iws.calculations.OCPDataInterpolant(electrode=...)`	Smooth interpolant from half-cell OCP measurements
`iws.calculations.OCPMSMRInterpolant(electrode=...)`	Evaluates the MSMR model over a voltage range to create an interpolant
`iws.calculations.OCPDataInterpolantMSMRExtrapolation(electrode=...)`	Blends measured data inside the data range with MSMR extrapolation outside

import ionworks_schema as iws

ocp_pos = iws.calculations.OCPDataInterpolantMSMRExtrapolation(electrode="positive")

pipeline = iws.Pipeline({"ocp_pos": ocp_pos})

The blended interpolant is the recommended option whenever a simulation might access stoichiometries outside the measured data range — MSMR provides thermodynamically consistent extrapolation at the extremes.

Choosing an interpolator

All 1-D interpolant calculations — OCP interpolants (OCPDataInterpolant, OCPMSMRInterpolant, OCPDataInterpolantMSMRExtrapolation), diffusivity interpolants (DiffusivityDataInterpolant, DiffusivityFromMSMRData, DiffusivityFromMSMRFunction, ArrheniusDiffusivityFromMSMRData, ArrheniusDiffusivityFromMSMRFunction), and entropic-change interpolants (EntropicChangeDataInterpolant, EntropicChangeFromMSMRFunction) — accept an "interpolator" option that controls how values between data points are evaluated.

Value	Behaviour	When to use
`"linear"` (default)	Straight segments between knots	Coarse data, or when you want to avoid overfitting
`"cubic"`	Cubic-spline interpolation	Smooth physical relationships sampled densely
`"pchip"`	Monotone cubic (PCHIP) interpolation	Monotonic data (e.g. OCP curves) — prevents the overshoots that plain cubic splines can introduce

import ionworks_schema as iws

ocp_pos = iws.calculations.OCPDataInterpolantMSMRExtrapolation(
    electrode="positive",
    options={"interpolator": "pchip"},
)

For OCP curves and other monotonic data, "pchip" typically produces the most physically realistic interpolant: it stays monotonic between knots and avoids the spurious oscillations a cubic spline can introduce near steep features.