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)

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.

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

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

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):

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):

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

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.

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.
• Pchip: Piecewise cubic Hermite interpolating polynomial. Prevents overshooting and is good for monotonic data.

For most electrochemical properties like OCP curves, cubic or pchip interpolation provides the smoothest, most physically realistic results.

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:

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.

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

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

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.

Common Use Cases

Open-Circuit Potential (OCP)

The most common use of interpolants is for OCP curves:

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

temperature, conductivity
273, 0.5
298, 1.0
323, 1.8
348, 2.9

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

Concentration-Dependent Diffusivity

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: Learn more about model creation and parameter configuration
• Simulations: Understand how interpolants are used during simulation