CUBIC_SPLINE

Overview

The CUBIC_SPLINE function performs piecewise cubic polynomial interpolation through a set of data points. Unlike fitting a single high-degree polynomial to all data points (which can cause Runge’s phenomenon), cubic spline interpolation fits individual cubic polynomials between each pair of consecutive points while ensuring the overall curve is C² smooth—meaning the function, its first derivative, and second derivative are all continuous across segment boundaries.

This implementation uses the SciPy CubicSpline class from the scipy.interpolate module. The algorithm constructs n cubic polynomials q_i(x) for n+1 data points, where each polynomial connects adjacent knots (x_{i-1}, y_{i-1}) and (x_i, y_i). The continuity requirements at interior knots generate a tridiagonal system of linear equations that is solved efficiently to determine the spline coefficients.

The function supports four boundary condition types that specify behavior at the endpoints:

not-a-knot (default): The first and second polynomial segments share the same cubic; similarly for the last two segments. This is a good choice when no boundary information is available.
natural: The second derivative at both endpoints is zero (q''(x_0) = q''(x_n) = 0), simulating a physical elastic ruler that can pivot freely at its ends.
clamped: The first derivative at both endpoints is zero, fixing the slope at the boundaries.
periodic: For periodic functions where y_0 = y_n, this ensures y'(x_0) = y'(x_n) and y''(x_0) = y''(x_n).

The extrapolate parameter controls whether the spline extends beyond the original data range or returns errors for out-of-bounds queries. For further mathematical background, see the Spline interpolation article on Wikipedia and Carl de Boor’s reference text A Practical Guide to Splines (Springer-Verlag, 1978).

This example function is provided as-is without any representation of accuracy.

Excel Usage

=CUBIC_SPLINE(x, y, x_new, bc_type, extrapolate)

x (list[list], required): The x-coordinates of the data points.
y (list[list], required): The y-coordinates of the data points.
x_new (list[list], required): The x-coordinates at which to evaluate the interpolated values.
bc_type (str, optional, default: “not-a-knot”): Boundary condition type.
extrapolate (bool, optional, default: true): If True, extrapolate out-of-bounds points.

Returns (list[list]): A 2D list of interpolated values, or an error message (str) if invalid.

Examples

Example 1: Demo case 1

Inputs:

x	y	x_new
0	0	0.5
1	1	1.5
2	4	2.5
3	9

Excel formula:

=CUBIC_SPLINE({0;1;2;3}, {0;1;4;9}, {0.5;1.5;2.5})

Expected output:

Result
0.25
2.25
6.25

Example 2: Demo case 2

Inputs:

x	y	x_new	bc_type
0	0	0.5	natural
1	1	1.5
2	0	2.5
3	1	3.5
4	0

Excel formula:

=CUBIC_SPLINE({0;1;2;3;4}, {0;1;0;1;0}, {0.5;1.5;2.5;3.5}, "natural")

Expected output:

Result
0.7679
0.4464
0.4464
0.7679

Example 3: Demo case 3

Inputs:

x	y	x_new	bc_type
1	1	1.5	clamped
2	4	2.5
3	9	3.5
4	16

Excel formula:

=CUBIC_SPLINE({1;2;3;4}, {1;4;9;16}, {1.5;2.5;3.5}, "clamped")

Expected output:

Result
2
6
13.5

Example 4: Demo case 4

Inputs:

x	y	x_new	bc_type	extrapolate
0	0	0.5	not-a-knot	true
1	1	1.5
2	4	2.5

Excel formula:

=CUBIC_SPLINE({0;1;2}, {0;1;4}, {0.5;1.5;2.5}, "not-a-knot", TRUE)

Expected output:

Result
0.25
2.25
6.25

Python Code

import math
from scipy.interpolate import CubicSpline as scipy_CubicSpline

def cubic_spline(x, y, x_new, bc_type='not-a-knot', extrapolate=True):
    """
    Cubic spline data interpolator.

    See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.CubicSpline.html

    This example function is provided as-is without any representation of accuracy.

    Args:
        x (list[list]): The x-coordinates of the data points.
        y (list[list]): The y-coordinates of the data points.
        x_new (list[list]): The x-coordinates at which to evaluate the interpolated values.
        bc_type (str, optional): Boundary condition type. Valid options: not-a-knot, periodic, clamped, natural. Default is 'not-a-knot'.
        extrapolate (bool, optional): If True, extrapolate out-of-bounds points. Default is True.

    Returns:
        list[list]: A 2D list of interpolated values, or an error message (str) if invalid.
    """
    def to2d(val):
        """Convert scalar to 2D list if needed."""
        return [[val]] if not isinstance(val, list) else val

    def flatten(arr):
        """Flatten a 2D list to 1D."""
        result = []
        for sublist in arr:
            if isinstance(sublist, list):
                for item in sublist:
                    result.append(item)
            else:
                result.append(sublist)
        return result

    def validate_numeric_array(arr, name):
        """Validate that array contains only numeric values."""
        for i, row in enumerate(arr):
            if not isinstance(row, list):
                return f"Invalid input: {name} must be a 2D list."
            for j, val in enumerate(row):
                if not isinstance(val, (int, float, bool)):
                    return f"Invalid input: {name}[{i}][{j}] must be numeric."
                if isinstance(val, bool):
                    continue
                num_val = float(val)
                if math.isnan(num_val) or math.isinf(num_val):
                    return f"Invalid input: {name}[{i}][{j}] must be finite."
        return None

    # Validate bc_type
    valid_bc_types = ['not-a-knot', 'periodic', 'clamped', 'natural']
    if not isinstance(bc_type, str):
        return "Invalid input: bc_type must be a string."
    if bc_type not in valid_bc_types:
        return f"Invalid input: bc_type must be one of {valid_bc_types}."

    # Validate extrapolate
    if not isinstance(extrapolate, bool):
        return "Invalid input: extrapolate must be a boolean."

    # Normalize inputs to 2D lists
    x = to2d(x)
    y = to2d(y)
    x_new = to2d(x_new)

    # Validate inputs
    error = validate_numeric_array(x, 'x')
    if error:
        return error
    error = validate_numeric_array(y, 'y')
    if error:
        return error
    error = validate_numeric_array(x_new, 'x_new')
    if error:
        return error

    # Flatten arrays
    try:
        x_flat = flatten(x)
        y_flat = flatten(y)
        x_new_flat = flatten(x_new)
    except Exception as exc:
        return f"Invalid input: unable to flatten arrays: {exc}"

    # Check that x and y have the same length
    if len(x_flat) != len(y_flat):
        return "Invalid input: x and y must have the same number of elements."

    # Check minimum number of points
    if len(x_flat) < 2:
        return "Invalid input: at least 2 data points are required."

    # Check if x is strictly increasing
    for i in range(len(x_flat) - 1):
        if x_flat[i] >= x_flat[i+1]:
             return "Invalid input: x must be strictly increasing."

    # Perform cubic spline interpolation
    try:
        interp = scipy_CubicSpline(x_flat, y_flat, bc_type=bc_type, extrapolate=extrapolate)
        result = interp(x_new_flat)
    except Exception as exc:
        return f"scipy.interpolate.CubicSpline error: {exc}"

    # Convert result to 2D list
    try:
        result_2d = [[float(val)] for val in result]
    except Exception as exc:
        return f"Error converting result to 2D list: {exc}"

    # Validate result values
    for i, row in enumerate(result_2d):
        for j, val in enumerate(row):
            if math.isnan(val) or math.isinf(val):
                if extrapolate is False:
                    continue
                return f"scipy.interpolate.CubicSpline error: result contains non-finite value at index {i}."

    return result_2d

Overview

Excel Usage

Examples

Python Code

Online Calculator