API reference

The public API is re-exported from the top-level pyakima package (see __all__); the implementations live in pyakima.pyakima.

class pyakima.SplineCoeffs(x, y, n_control, a, b, c, d)[source]

NamedTuple storing the coefficients that represent a cubic spline.

NamedTuple is used because numba handles it well and it is statically typed.

Parameters:

  • x (NDArray[np.floating])

  • y (NDArray[np.floating])

  • n_control (int)

  • a (NDArray[np.floating])

  • b (NDArray[np.floating])

  • c (NDArray[np.floating])

  • d (NDArray[np.floating])

x

One-dimensional x coordinates of the spline control points.

Type:

NDArray[np.floating]

y

One-dimensional y coordinates of the spline control points.

Type:

NDArray[np.floating]

n_control

Number of control points.

Type:

int

a

n_control-1 first (constant) terms of the cubic spline pieces.

Type:

NDArray[np.floating]

b

n_control-1 second (linear) terms of the cubic spline pieces.

Type:

NDArray[np.floating]

c

n_control-1 third (quadratic) terms of the cubic spline pieces.

Type:

NDArray[np.floating]

d

n_control-1 fourth (cubic) terms of the cubic spline pieces.

Type:

NDArray[np.floating]

Provide numba-compatible Akima spline interpolation.

Expose the public building blocks of the pyakima.pyakima module: the AkimaSpline object for constructing and evaluating a spline, the SplineCoeffs named tuple that stores a spline’s coefficients, and the njit-compiled helpers that create and evaluate splines from within other numba-compiled code.

class pyakima.AkimaSpline(x, y, ext=3, corner_model='makima', denom_small_cut=nan, linear_vector_calls=0)[source]

Bases: object

Python class to manage Akima and Modified Akima splines.

Parameters:

  • x (NDArray[np.floating]) – One-dimensional array of spline control point x coordinates. Must be at least 5 points, and x must be monotonically increasing.

  • y (NDArray[np.floating]) – One-dimensional y coordinates of the spline control points (shape must match x). Non-finite y are used in computations as-is (like gsl, unlike scipy which raises). Calls near control points with non-finite y will produce nan, but keeps the spline usable if most of the control points are finite.

  • ext (int) –

    Extrapolation handling flag, similar to scipy:

    0: Extrapolate 1: Return zero outside the domain 2: Not implemented 3: Return the boundary value 4: Return nan outside domain

    Default 3

  • corner_model (int | str) –

    Selection for how corners are handled:
    0 or ‘non-rounded’: Wodicka non-rounded corner method (near-exact match to gsl for denom_small_cut == 0.0)

    Non-differentiable/exhibits discontinuous numerical behavior at sharp corners, but not oscillations.

    1 or ‘akima’: Original Akima method (close to scipy method=’akima’).

    Differentiable at sharp corners and less noticeably discontinuous behavior, still some oscillations.

    2 or ‘makima’: Modified Akima/makima method with stabilizing weights for guaranteed differentiability.

    No special corner handling is needed, so discontinuous numerical behavior is eliminated. Close to scipy method=’makima’. Described by C. Moler at https://blogs.mathworks.com/cleve/2019/04/29/makima-piecewise-cubic-interpolation/

    Default is ‘makima’ (modified Akima)

  • denom_small_cut (float) – Threshold below which the denominator in the slope is treated as zero and handled specially. Usually best left at zero, but included for scipy feature parity. The default nan selects a method-specific value.

  • linear_vector_calls (int) –

    Affects only the speed of __call__, not the results.

    0: Search takes advantage of the fact that callers may be partly sorted (forward or reverse). 1: Evaluate vector inputs with independent per-point searches Default 0

Raises:

ValueError – if the specified model parameters are unrecognized, the x/y inputs are invalid, or denom_small_cut is negative or non-finite.

pyakima.cubic_call(xint: float | floating, spline: SplineCoeffs, ext: int) → float[source]
pyakima.cubic_call(xint: NDArray[np.floating], spline: SplineCoeffs, ext: int) → NDArray[np.floating]

Evaluate akima splines with scalar or vector input.

Dispatches separate helper functions for vector and scalar inputs.

Parameters:

  • xint (float | np.floating | NDArray[np.floating]) – scalar or C- or Fortran-contiguous array of any shape containing points at which to evaluate the spline.

  • spline (SplineCoeffs) – NamedTuple containing the computed spline coefficients.

  • ext (int) –

    Extrapolation handling flag, similar to scipy:

    0: Extrapolate 1: Return zero outside the domain 2: Not implemented 3: Return the boundary value 4: Return nan outside domain

Returns:

scalar or array of the same shape as xint containing interpolated y values.

Return type:

float | NDArray[np.floating]

Raises:

TypeError – if the type of xint, spline, or ext is unsupported.

pyakima.cubic_call_scalar(xint, spline, ext)[source]

Call cubic spline with a scalar.

Searches the control points with a binary search, and evaluates at the selected control point.

Parameters:

  • xint (float | np.floating) – scalar point at which to evaluate the spline.

  • spline (SplineCoeffs) – NamedTuple containing the computed spline coefficients.

  • ext (int) –

    Extrapolation handling flag, similar to scipy:

    0: Extrapolate 1: Return zero outside the domain 2: Not implemented 3: Return the boundary value 4: Return nan outside domain

Returns:

interpolated y value.

Return type:

float

Raises:

ValueError – if the extrapolation flag is unrecognized.

pyakima.cubic_call_vector(xint, spline, ext)[source]

Evaluate akima splines with an array input.

Note that there are several possible implementations of this method that could be best in various circumstances. The current implementation can take advantage of the assumption that xint is typically likely to be sorted (either forward or reversed) but does not require it; if the application was _required_ to be sorted a somewhat more efficient implementation would be possible. If xint is very likely not to have any particular order, use cubic_call_vector_linear. cubic_call_vector_linear would also be more vectorizable. Depending on the application, lazy evaluation of spline coefficients could be more efficient, but is not implemented here.

Parameters:

  • xint (NDArray[np.floating]) – C- or Fortran-contiguous array of any shape containing points at which to evaluate the spline.

  • spline (SplineCoeffs) – NamedTuple containing the computed spline coefficients.

  • ext (int) –

    Extrapolation handling flag, similar to scipy:

    0: Extrapolate 1: Return zero outside the domain 2: Not implemented 3: Return the boundary value 4: Return nan outside domain

Returns:

array of the same shape as xint containing interpolated y values.

Return type:

NDArray[np.floating]

pyakima.cubic_call_vector_linear(xint, spline, ext)[source]

Evaluate akima splines with an array input using independent loop iterations.

Produces the same result as cubic_call_vector, but inlines the per-point logic of cubic_call_scalar so each point is evaluated independently. Loop iterations remain uncorrelated (no shared location guess) May be faster when xint is not at least partially sorted or, on some compute architectures (this method is more readily parallelizable/vectorizable).

Parameters:

  • xint (NDArray[np.floating]) – C- or Fortran-contiguous array of any shape containing points at which to evaluate the spline. Non-contiguous layouts are not part of the public contract.

  • spline (SplineCoeffs) – NamedTuple containing the computed spline coefficients.

  • ext (int) –

    Extrapolation handling flag, similar to scipy:

    0: Extrapolate 1: Return zero outside the domain 2: Not implemented 3: Return the boundary value 4: Return nan outside domain

Returns:

array of the same shape as xint containing interpolated y values.

Return type:

NDArray[np.floating]

pyakima.make_akima_coeffs(x, y, corner_model=2, denom_small_cut=0.0)[source]

Compute the coefficients that define Akima and Modified Akima splines.

Parameters:

  • x (NDArray[np.floating]) – One-dimensional array of spline control point x coordinates. Must be at least 5 points, and x must be monotonically increasing.

  • y (NDArray[np.floating]) – One-dimensional y coordinates of the spline control points (shape must match x). Non-finite y are used in computations as-is (like gsl, unlike scipy which raises). Calls near control points with non-finite y will produce nan, but keeps the spline usable if most of the control points are finite.

  • corner_model (int) –

    Selection for how corners are handled:
    0 Wodicka non-rounded corner method (near-exact match to gsl for denom_small_cut == 0.0)

    Non-differentiable/exhibits discontinuous numerical behavior at sharp corners, but not oscillations.

    1 Original Akima method (close to scipy method=’akima’).

    Differentiable at sharp corners and less noticeably discontinuous behavior, still some oscillations.

    2 Modified Akima/makima method with stabilizing weights for guaranteed differentiability.

    No special corner handling is needed, so discontinuous numerical behavior is eliminated. Close to scipy method=’makima’. Described by C. Moler at https://blogs.mathworks.com/cleve/2019/04/29/makima-piecewise-cubic-interpolation/

    Default is 2 (modified Akima/’makima’)

  • denom_small_cut (float) – Threshold below which the denominator in the slope is treated as zero and handled specially. Usually best left at zero, but included for scipy feature parity.

Returns:

NamedTuple containing the computed spline coefficients.

Return type:

SplineCoeffs

Raises:

ValueError – if corner_model is unrecognized if input x and y shapes do not match if x and y are not one-dimensional if x is not monotonically increasing if x does not have at least 5 control points if denom_small_cut is negative or non-finite

Notes

Notes on non-rounded corner akima spline implementation:

it is described in algorithm 13.1 in “Akima and Renner Subsplines” from “Numerical Algorithms with C” by Engeln-Müllges, Gisela & Uhlig, Frank, ISBN 9783642646829 See https://link.springer.com/content/pdf/10.1007/978-3-642-61074-5_13.pdf

Currently, only natural boundary conditions are implemented.

pyakima.spline_single_knot_eval(xint: float | np.floating, spline: SplineCoeffs, i: int) → float[source]
pyakima.spline_single_knot_eval(xint: NDArray[np.floating], spline: SplineCoeffs, i: int) → NDArray[np.floating]

Evaluate the spline from the values at the knot point with index i.

Do not check whether xint is in the x range covered by the specified knot.

Parameters:

  • xint (float | np.floating | NDArray[np.floating]) – Scalar or array of any shape, containing x values at which to evaluate the spline.

  • spline (SplineCoeffs) – NamedTuple containing the spline coefficients to evaluate.

  • i (int) – Index of the spline knot to evaluate.

Returns:

Evaluated points of the same shape as xint; preserves input type for array inputs Numba compiler casts scalar types to float at output.

Return type:

float | np.floating | NDArray[np.floating]