> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Piecewise Interpolants

> Build smooth piecewise interpolants for SOC- and temperature-dependent parameters with ionworks-schema.

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](/guide/calculations/piecewise).

## 1D piecewise interpolant

```python theme={null}
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):

```python theme={null}
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 |

```python theme={null}
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 |

```python theme={null}
import ionworks_schema as iws

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

<Tip>
  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.
</Tip>

<CardGroup cols={2}>
  <Card title="Piecewise Interpolants (theory)" icon="stairs" href="/guide/calculations/piecewise">
    Smooth heaviside math, knot vs slope parameterisation, MSMR blending.
  </Card>

  <Card title="Pipelines overview" icon="diagram-project" href="/pipelines/overview">
    How interpolants chain with direct entries and data fits.
  </Card>
</CardGroup>