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

# Parameter Interpolants

> Define model parameters as lookup tables using CSV data with linear, cubic, or pchip interpolation

## What is an Interpolant?

An **interpolant** is a parameter defined as a lookup table rather than a single
value or mathematical expression. Interpolants are ideal for representing
experimental data or complex relationships that don't have simple mathematical
formulas.

When you define a parameter as an interpolant, you provide discrete data points,
and Ionworks Studio automatically interpolates between them during simulations.

## When to Use Interpolants

Interpolants are particularly useful for:

* **Open-circuit potential (OCP) curves**: Voltage as a function of
  stoichiometry from experimental measurements
* **Diffusivity data**: Diffusion coefficients that vary non-linearly with
  concentration or temperature
* **Temperature-dependent properties**: Physical properties measured at discrete
  temperature points
* **Complex multi-variable relationships**: Parameters that depend on multiple
  inputs (e.g., conductivity as a function of both concentration and temperature)

<Tip>
  Use interpolants when you have experimental data that's difficult to express
  as a mathematical function, or when a lookup table provides better accuracy
  than a fitted equation.
</Tip>

## Creating an Interpolant

### Step 1: Identify Compatible Parameters

Not all parameters can be converted to interpolants. Only parameters that accept
function inputs can become interpolants.

To check if a parameter can be an interpolant:

1. Navigate to the **Model Editor** when creating or cloning a model
2. Look for the parameter you want to modify
3. Click the **change circle icon** (⟳) next to the parameter value
4. If "Interpolant" appears in the menu, the parameter supports interpolants

<Note>
  Parameters that only accept scalar values (like geometric dimensions) cannot
  be converted to interpolants.
</Note>

### Step 2: Convert the Parameter Type

To convert a parameter to an interpolant:

1. Click the **change circle icon** (⟳) next to the parameter value
2. Select **Interpolant** from the dropdown menu
3. The interpolant editor will open

### Step 3: Enter Data

You have two options for entering interpolant data:

#### Option A: Upload a CSV File

The quickest way to define an interpolant is to upload a CSV file:

1. In the interpolant editor, click the **Upload File** button or drag and drop
   a CSV file
2. Format your CSV file with columns for:
   * First column(s): Input variable(s) (e.g., stoichiometry, temperature)
   * Last column: Output value (the parameter value)

**Example CSV for 1D interpolant (e.g., OCP vs. Stoichiometry):**

```csv theme={null}
0.0, 3.5
0.1, 3.6
0.2, 3.65
0.3, 3.7
0.5, 3.8
0.7, 3.85
0.9, 3.95
1.0, 4.1
```

**Example CSV for 2D interpolant (e.g., Diffusivity vs. Stoichiometry and
Temperature):**

```csv theme={null}
0.0, 298, 1.5e-14
0.0, 323, 2.8e-14
0.5, 298, 1.8e-14
0.5, 323, 3.2e-14
1.0, 298, 1.6e-14
1.0, 323, 3.0e-14
```

#### Option B: Manual Entry

For smaller datasets, you can enter data points manually:

1. Click **Insert Row Above** or **Insert Row Below** to add new data points
2. Click on any cell in the table to edit the value
3. Enter your data points
4. Use **Delete Row** to remove unwanted points

<Note>
  For 1D interpolants, you can edit both input (x) and output (y) values. For
  multi-dimensional interpolants, only output (y) values are editable after
  uploading data—input combinations must be defined via CSV.
</Note>

### Step 4: Choose Interpolation Method

Select the interpolation method that best fits your data:

* **Linear**: Straight lines between data points. Best for coarse data or when
  you want to avoid overfitting.
* **Cubic**: Smooth curves using cubic splines. Ideal for smooth physical
  relationships, but can overshoot near sharp features and produce unphysical
  values (for example, negative diffusivities).
* **Pchip**: Piecewise cubic Hermite interpolating polynomial. Produces a smooth
  curve like cubic, but guarantees the interpolant stays between adjacent data
  points—so monotonic data stays monotonic and values never overshoot the
  bracketing samples. Recommended for diffusivity tables and OCP data that
  varies sharply with stoichiometry.

<Tip>
  For most electrochemical properties like OCP curves, **cubic** or **pchip**
  interpolation provides the smoothest, most physically realistic results.
  Prefer **pchip** when the underlying data is (or should be) monotonic, or when
  unconstrained cubic interpolation produces unphysical overshoot.
</Tip>

### Step 5: Preview and Save

* For **1D interpolants**, a plot preview appears on the right side showing how
  your data will be interpolated
* Review the plot to ensure the interpolation looks physically reasonable
* Click **Save** to apply the interpolant to your parameter

## Working with Multi-Dimensional Interpolants

Multi-dimensional interpolants allow you to define parameters that depend on
multiple variables simultaneously (e.g., conductivity as a function of both
concentration and temperature).

### Requirements

* The parameter must accept a function with multiple inputs
* Data must be provided as a CSV file with all input combinations you want to
  define
* The CSV format is: `input1, input2, ..., output`

### Example: Diffusivity(Stoichiometry, Temperature)

If a parameter accepts a function like `D(sto, T)`, you can create a 2D
interpolant:

```csv theme={null}
stoichiometry, temperature, diffusivity
0.0, 298, 1.5e-14
0.0, 323, 2.8e-14
0.2, 298, 1.7e-14
0.2, 323, 3.0e-14
0.5, 298, 1.8e-14
0.5, 323, 3.2e-14
0.8, 298, 1.7e-14
0.8, 323, 3.1e-14
1.0, 298, 1.6e-14
1.0, 323, 3.0e-14
```

During simulation, Ionworks Studio will interpolate between these points to
evaluate the parameter at any (stoichiometry, temperature) combination.

<Warning>
  Multi-dimensional interpolants require careful data preparation. Ensure your
  input space is adequately sampled to avoid extrapolation errors during
  simulation.
</Warning>

## Best Practices

### Data Quality

* **Use sufficient data points**: For 1D interpolants, 10-20 points often
  provide good accuracy
* **Cover the full range**: Ensure your data spans the entire range the
  parameter will encounter during simulation
* **Avoid extrapolation**: Simulations that require parameter values outside
  your data range will extrapolate, which can lead to unphysical results
* **Check for noise**: Smooth or filter noisy experimental data before creating
  an interpolant

### Testing Your Interpolant

After creating an interpolant:

1. **Visual inspection**: For 1D interpolants, check the plot preview to ensure
   the curve looks physically reasonable
2. **Run a test simulation**: Verify that your model with the interpolant
   produces expected results
3. **Compare with original data**: If converting from a function to an
   interpolant, compare simulation results to ensure consistency

### Converting Between Parameter Types

You can always switch a parameter between value, function, and interpolant:

1. Click the **change circle icon** (⟳)
2. Select the new type
3. Ionworks Studio temporarily saves your previous parameter definition, so
   switching back preserves your work within the same editing session

<Tip>
  When iterating on a model, you might start with a simple function, then refine
  to an interpolant as you gather experimental data. Cloning models makes this
  workflow seamless.
</Tip>

## Common Use Cases

### Open-Circuit Potential (OCP)

The most common use of interpolants is for OCP curves:

```csv theme={null}
stoichiometry, voltage
0.01, 0.15
0.10, 0.35
0.20, 0.45
0.50, 0.60
0.80, 0.75
0.90, 0.85
0.99, 0.95
```

Parameter name: `Positive electrode OCP [V]` or `Negative electrode OCP [V]`

### Temperature-Dependent Conductivity

```csv theme={null}
temperature, conductivity
273, 0.5
298, 1.0
323, 1.8
348, 2.9
```

Parameter name: `Electrolyte conductivity [S.m-1]`

### Concentration-Dependent Diffusivity

```csv theme={null}
concentration, diffusivity
1000, 1.2e-14
5000, 1.5e-14
10000, 1.8e-14
15000, 1.6e-14
20000, 1.4e-14
```

Parameter name: `Positive electrode diffusivity [m2.s-1]` or
`Negative electrode diffusivity [m2.s-1]`

## Technical Details

### Interpolation Algorithms

* **Linear**: Uses `scipy.interpolate.interp1d` with `kind='linear'`
* **Cubic**: Uses `scipy.interpolate.interp1d` with `kind='cubic'`
* **Pchip**: Uses `scipy.interpolate.PchipInterpolator` (monotonic cubic
  interpolation)

During simulation, PyBaMM's `Interpolant` class handles the evaluation of
interpolated values.

## Troubleshooting

### "Missing values in the table"

This error occurs when your data contains NaN or missing values. Check your CSV
file for:

* Empty cells
* Non-numeric data
* Formatting issues

### Simulation fails with interpolant

If your simulation fails after adding an interpolant:

1. **Check data range**: Ensure your interpolant covers the full range of
   values encountered during simulation
2. **Try different interpolation method**: Switch from cubic to linear or pchip
3. **Increase data points**: Add more points in regions where the parameter
   changes rapidly
4. **Verify units**: Confirm that your data uses the correct units for both
   inputs and outputs

### Cannot convert parameter to interpolant

If the interpolant option doesn't appear:

* The parameter only accepts scalar values and cannot be an interpolant
* Try using a function parameter instead, or check the parameter library
  documentation for that specific parameter

## Related Topics

* [Models](/build/models): Learn more about model creation and parameter
  configuration
* [Simulations](/simulate/simulations): Understand how interpolants are used during
  simulation