pulsesuite.libpulsesuite.spliner¶

Spline interpolation routines for arrays.

This module provides routines for interpolation of arrays using cubic splines and polynomial interpolation methods. Supports both real and complex arrays, 1D and 2D rescaling, and multi-dimensional interpolation.

Author: Rahul R. Sah

Attributes¶

JIT_AVAILABLE

Functions¶

`iminloc`(arr)	Find the index of the minimum value in an array.
`rescale_2D_dp`(x0, y0, z0, x1, y1, z1)	Rescale a 2D real array from one grid to another.
`rescale_2D_dpc`(x0, y0, z0, x1, y1, z1)	Rescale a 2D complex array from one grid to another.
`rescale_1D_dpc`(x0, z0, x1, z1)	Rescale a 1D complex array from one grid to another.
`rescale_1D_cyl_dpc`(x0, z0, x1, z1)	Rescale a 1D complex array from one grid to another with cylindrical boundary condition.
`rescale_1D_dp`(x0, y0, x1, y1)	Rescale a 1D real array from one grid to another.
`GetValAt_3D`(e, x0a, x1a, x2a, x0, x1, x2[, N])	Interpolate a 3D array at an arbitrary point.
`GetValAt_2D`(e, x0a, x1a, x0, x1[, N])	Interpolate a 2D array at an arbitrary point.
`GetValAt_1D`(e, x0, x1)	Interpolate a 1D real array at an arbitrary point.
`GetValAt_1D_dpc`(e, x0, x1)	Interpolate a 1D complex array at an arbitrary point.
`polint1`(xa, ya, x[, dy])	Interpolate a 1D array at an arbitrary point using polynomial interpolation.
`polint2`(x1a, x2a, ya, x1, x2[, dy])	Interpolate a 2D array at an arbitrary point using polynomial interpolation.
`polint3`(x1a, x2a, x3a, ya, x1, x2, x3[, dy])	Interpolate a 3D array at an arbitrary point using polynomial interpolation.
`bcucof`(y, y1, y2, y12, d1, d2, c)	Compute bicubic interpolation coefficients.
`bcuint`(y, y1, y2, y12, x1l, x1u, x2l, x2u, x1, x2)	Bicubic interpolation.
`spline2_dpc`(x, z, z2)	Compute the cubic spline interpolant for complex arrays (second derivative version).
`seval2_dpc`(x0, x, z, z2)	Evaluate the cubic spline for complex arrays (second derivative version).
`spline2_dp`(x, y, y2)	Compute the cubic spline interpolant for real arrays (second derivative version).
`locate`(xx, x)	Find the index i such that xx[i] <= x < xx[i+1].
`spline_dp`(x, y, b, c, d)	Compute the cubic spline interpolant for real arrays.
`seval_dp`(u, x, y, b, c, d)	Evaluate the cubic spline for real arrays.
`spline_dpc`(x, y, b, c, d)	Compute the cubic spline interpolant for complex arrays.
`seval_dpc`(u, x, y, b, c, d)	Evaluate the cubic spline for complex arrays.
`seval2_dp`(x0, x, y, y2)	Evaluate the cubic spline for real arrays (second derivative version).
`spline`(x, *args)	Unified interface for spline functions.
`seval`(pos, x, *args)	Unified interface for spline evaluation functions.
`rescale_1D`(x0[, y0, z0, x1, y1, z1])	Unified interface for 1D rescaling functions.
`rescale_2D`(x0, y0, z0, x1, y1, z1)	Unified interface for 2D rescaling functions.

Module Contents¶

pulsesuite.libpulsesuite.spliner.JIT_AVAILABLE = True¶

pulsesuite.libpulsesuite.spliner.iminloc(arr)¶

Find the index of the minimum value in an array.

Parameters:: arr (ndarray) – 1D array of real values
Returns:: Index (1-based in Fortran, 0-based in Python) of minimum value. Note: Returns 0-based index to match Python convention.
Return type:: int

pulsesuite.libpulsesuite.spliner.rescale_2D_dp(x0, y0, z0, x1, y1, z1)¶

Rescale a 2D real array from one grid to another.

Rescales the 2D array z0 defined on grid (x0, y0) to a new grid (x1, y1), storing the result in z1. Uses cubic spline interpolation.

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
y0 (ndarray) – Original Y-coordinates, 1D array
z0 (ndarray) – Original 2D array, shape (len(x0), len(y0))
x1 (ndarray) – New X-coordinates, 1D array
y1 (ndarray) – New Y-coordinates, 1D array
z1 (ndarray) – Output 2D array, shape (len(x1), len(y1)), will be modified in-place

Notes

The function first interpolates along the x-direction for each y0 value, then interpolates along the y-direction for each x1 value.

pulsesuite.libpulsesuite.spliner.rescale_2D_dpc(x0, y0, z0, x1, y1, z1)¶

Rescale a 2D complex array from one grid to another.

Rescales the 2D complex array z0 defined on grid (x0, y0) to a new grid (x1, y1), storing the result in z1. Uses cubic spline interpolation.

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
y0 (ndarray) – Original Y-coordinates, 1D array
z0 (ndarray) – Original 2D complex array, shape (len(x0), len(y0))
x1 (ndarray) – New X-coordinates, 1D array
y1 (ndarray) – New Y-coordinates, 1D array
z1 (ndarray) – Output 2D complex array, shape (len(x1), len(y1)), will be modified in-place

Notes

The function first interpolates along the x-direction for each y0 value, then interpolates along the y-direction for each x1 value.

pulsesuite.libpulsesuite.spliner.rescale_1D_dpc(x0, z0, x1, z1)¶

Rescale a 1D complex array from one grid to another.

Rescales the 1D complex array z0 defined on grid x0 to a new grid x1, storing the result in z1. Uses cubic spline interpolation.

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
z0 (ndarray) – Original 1D complex array
x1 (ndarray) – New X-coordinates, 1D array
z1 (ndarray) – Output 1D complex array, will be modified in-place

Notes

Values outside the range [min(x0), max(x0)] are set to 0.

pulsesuite.libpulsesuite.spliner.rescale_1D_cyl_dpc(x0, z0, x1, z1)¶

Rescale a 1D complex array from one grid to another with cylindrical boundary condition.

Rescales the 1D complex array z0 defined on grid x0 to a new grid x1, storing the result in z1. Uses cubic spline interpolation. The first point z1[0] is set to z0[0] (cylindrical boundary condition).

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
z0 (ndarray) – Original 1D complex array
x1 (ndarray) – New X-coordinates, 1D array
z1 (ndarray) – Output 1D complex array, will be modified in-place

Notes

Values outside the range [min(x0), max(x0)] are set to 0. The first point z1[0] is always set to z0[0].

pulsesuite.libpulsesuite.spliner.rescale_1D_dp(x0, y0, x1, y1)¶

Rescale a 1D real array from one grid to another.

Rescales the 1D real array y0 defined on grid x0 to a new grid x1, storing the result in y1. Uses cubic spline interpolation.

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
y0 (ndarray) – Original 1D real array
x1 (ndarray) – New X-coordinates, 1D array
y1 (ndarray) – Output 1D real array, will be modified in-place

Notes

Values outside the range [min(x0), max(x0)] are set to 0.

pulsesuite.libpulsesuite.spliner.GetValAt_3D(e, x0a, x1a, x2a, x0, x1, x2, N=None)¶

Interpolate a 3D array at an arbitrary point.

Uses polynomial interpolation to interpolate the 3D array e at the point (x0, x1, x2). Returns 0 if the point is outside the array bounds.

Parameters:

e (ndarray) – 3D array to interpolate
x0a (ndarray) – X-coordinates for first dimension, 1D array
x1a (ndarray) – X-coordinates for second dimension, 1D array
x2a (ndarray) – X-coordinates for third dimension, 1D array
x0 (float) – Position in first dimension
x1 (float) – Position in second dimension
x2 (float) – Position in third dimension
N (int, optional) – Order of interpolation (default: 2)

Returns:

Interpolated value at (x0, x1, x2), or 0 if outside bounds

Return type:

float

pulsesuite.libpulsesuite.spliner.GetValAt_2D(e, x0a, x1a, x0, x1, N=None)¶

Interpolate a 2D array at an arbitrary point.

Uses polynomial interpolation to interpolate the 2D array e at the point (x0, x1). Returns 0 if the point is outside the array bounds.

Parameters:

e (ndarray) – 2D array to interpolate
x0a (ndarray) – X-coordinates for first dimension, 1D array
x1a (ndarray) – X-coordinates for second dimension, 1D array
x0 (float) – Position in first dimension
x1 (float) – Position in second dimension
N (int, optional) – Order of interpolation (default: 2)

Returns:

Interpolated value at (x0, x1), or 0 if outside bounds

Return type:

float

pulsesuite.libpulsesuite.spliner.GetValAt_1D(e, x0, x1)¶

Interpolate a 1D real array at an arbitrary point.

Uses cubic spline interpolation to interpolate the 1D array e at the point x1. Returns 0 if the point is outside the array bounds.

Parameters:

e (ndarray) – 1D array to interpolate
x0 (ndarray) – X-coordinates for the array, 1D array
x1 (float) – Position to interpolate

Returns:

Interpolated value at x1, or 0 if outside bounds

Return type:

float

pulsesuite.libpulsesuite.spliner.GetValAt_1D_dpc(e, x0, x1)¶

Interpolate a 1D complex array at an arbitrary point.

Uses cubic spline interpolation to interpolate the 1D complex array e at the point x1. Returns 0 if the point is outside the array bounds.

Parameters:

e (ndarray) – 1D complex array to interpolate
x0 (ndarray) – X-coordinates for the array, 1D array
x1 (float) – Position to interpolate

Returns:

Interpolated complex value at x1, or 0 if outside bounds

Return type:

complex

pulsesuite.libpulsesuite.spliner.polint1(xa, ya, x, dy=None)¶

Interpolate a 1D array at an arbitrary point using polynomial interpolation.

Uses Neville’s algorithm for polynomial interpolation. The polynomial order is determined by the array size (N-1).

Parameters:

xa (ndarray) – X-coordinates, 1D array
ya (ndarray) – Y-values at x coordinates, 1D array
x (float) – Position to interpolate
dy (list or None, optional) – If provided as a list, will store error estimate in dy[0]

Returns:

Interpolated value at x

Return type:

float

pulsesuite.libpulsesuite.spliner.polint2(x1a, x2a, ya, x1, x2, dy=None)¶

Interpolate a 2D array at an arbitrary point using polynomial interpolation.

Uses polynomial interpolation by first interpolating along the second dimension, then along the first dimension.

Parameters:

x1a (ndarray) – X-coordinates for first dimension, 1D array
x2a (ndarray) – X-coordinates for second dimension, 1D array
ya (ndarray) – 2D array of values
x1 (float) – Position in first dimension
x2 (float) – Position in second dimension
dy (float, optional) – Output parameter for error estimate (if provided)

Returns:

Interpolated value at (x1, x2)

Return type:

float

pulsesuite.libpulsesuite.spliner.polint3(x1a, x2a, x3a, ya, x1, x2, x3, dy=None)¶

Interpolate a 3D array at an arbitrary point using polynomial interpolation.

Uses polynomial interpolation by first interpolating along the third and second dimensions, then along the first dimension.

Parameters:

x1a (ndarray) – X-coordinates for first dimension, 1D array
x2a (ndarray) – X-coordinates for second dimension, 1D array
x3a (ndarray) – X-coordinates for third dimension, 1D array
ya (ndarray) – 3D array of values
x1 (float) – Position in first dimension
x2 (float) – Position in second dimension
x3 (float) – Position in third dimension
dy (float, optional) – Output parameter for error estimate (if provided)

Returns:

Interpolated value at (x1, x2, x3)

Return type:

float

pulsesuite.libpulsesuite.spliner.bcucof(y, y1, y2, y12, d1, d2, c)¶

Compute bicubic interpolation coefficients.

Computes the coefficients for bicubic interpolation given function values, first derivatives, and cross derivatives at the four corners of a rectangle.

Parameters:

y (ndarray) – Function values at four corners, shape (4,)
y1 (ndarray) – First derivatives in x-direction at four corners, shape (4,)
y2 (ndarray) – First derivatives in y-direction at four corners, shape (4,)
y12 (ndarray) – Cross derivatives (d^2/dxdy) at four corners, shape (4,)
d1 (float) – Width of rectangle in x-direction
d2 (float) – Width of rectangle in y-direction
c (ndarray) – Output array for bicubic coefficients, shape (4, 4), modified in-place

Notes

The coefficients are stored in c such that the interpolated value is: sum over i,j of c[i,j] * t^i * u^j where t and u are normalized coordinates in [0,1].

pulsesuite.libpulsesuite.spliner.bcuint(y, y1, y2, y12, x1l, x1u, x2l, x2u, x1, x2)¶

Bicubic interpolation.

Performs bicubic interpolation at the point (x1, x2) within a rectangle defined by [x1l, x1u] x [x2l, x2u]. Returns the interpolated value.

Parameters:

y (ndarray) – Function values at four corners, shape (4,)
y1 (ndarray) – First derivatives in x-direction at four corners, shape (4,)
y2 (ndarray) – First derivatives in y-direction at four corners, shape (4,)
y12 (ndarray) – Cross derivatives (d^2/dxdy) at four corners, shape (4,)
x1l (float) – Lower bound of x1 coordinate
x1u (float) – Upper bound of x1 coordinate
x2l (float) – Lower bound of x2 coordinate
x2u (float) – Upper bound of x2 coordinate
x1 (float) – X1 coordinate to interpolate
x2 (float) – X2 coordinate to interpolate

Returns:

(ansy, ansy1, ansy2) where: - ansy: Interpolated value at (x1, x2) - ansy1: Partial derivative d/dx1 - ansy2: Partial derivative d/dx2

Return type:

tuple

pulsesuite.libpulsesuite.spliner.spline2_dpc(x, z, z2)¶

Compute the cubic spline interpolant for complex arrays (second derivative version).

Computes the second derivatives z2 for cubic spline interpolation of the complex function z(x). This version uses natural boundary conditions (zero second derivatives at endpoints).

Parameters:

x (ndarray) – X-coordinates, 1D array, must be in ascending order
z (ndarray) – Complex function values at x coordinates, 1D array
z2 (ndarray) – Output array for second derivatives, shape (len(x)), complex, modified in-place

Notes

Uses natural spline boundary conditions: z2[0] = z2[N-1] = 0. The spline can be evaluated using seval2_dpc.

pulsesuite.libpulsesuite.spliner.seval2_dpc(x0, x, z, z2)¶

Evaluate the cubic spline for complex arrays (second derivative version).

Evaluates the cubic spline at point x0 using the pre-computed second derivatives z2 from spline2_dpc.

Parameters:

x0 (float) – Position to interpolate
x (ndarray) – X-coordinates used to compute spline, 1D array
z (ndarray) – Complex function values at x coordinates, 1D array
z2 (ndarray) – Second derivatives from spline2_dpc, 1D complex array

Returns:

Interpolated complex value at x0

Return type:

complex

pulsesuite.libpulsesuite.spliner.spline2_dp(x, y, y2)¶

Compute the cubic spline interpolant for real arrays (second derivative version).

Computes the second derivatives y2 for cubic spline interpolation of the function y(x). This version uses natural boundary conditions (zero second derivatives at endpoints).

Parameters:

x (ndarray) – X-coordinates, 1D array, must be in ascending order
y (ndarray) – Function values at x coordinates, 1D array
y2 (ndarray) – Output array for second derivatives, shape (len(x)), modified in-place

Notes

Uses natural spline boundary conditions: y2[0] = y2[N-1] = 0. The spline can be evaluated using seval2_dp.

pulsesuite.libpulsesuite.spliner.locate(xx, x)¶

Find the index i such that xx[i] <= x < xx[i+1].

Uses binary search for efficiency. Returns the index of the lower bound.

Parameters:

xx (ndarray) – Sorted 1D array (ascending order)
x (float) – Value to locate

Returns:

Index i such that xx[i] <= x < xx[i+1], or len(xx)-1 if x >= xx[-1]

Return type:

int

pulsesuite.libpulsesuite.spliner.spline_dp(x, y, b, c, d)¶

Compute the cubic spline interpolant for real arrays.

Computes the coefficients b, c, d for cubic spline interpolation of the function y(x). The spline can then be evaluated using seval_dp.

Parameters:

x (ndarray) – X-coordinates, 1D array, must be in ascending order
y (ndarray) – Y-values at x coordinates, 1D array
b (ndarray) – Output array for spline coefficients (linear term)
c (ndarray) – Output array for spline coefficients (quadratic term)
d (ndarray) – Output array for spline coefficients (cubic term)

Notes

The arrays b, c, d are modified in-place. The spline evaluation uses: y(x) = y[i] + dx*(b[i] + dx*(c[i] + dx*d[i])) where dx = x - x[i] and i is the index such that x[i] <= x < x[i+1].

pulsesuite.libpulsesuite.spliner.seval_dp(u, x, y, b, c, d)¶

Evaluate the cubic spline for real arrays.

Evaluates the cubic spline at point u using the pre-computed spline coefficients b, c, d from spline_dp.

Parameters:

u (float) – Position to interpolate
x (ndarray) – X-coordinates used to compute spline, 1D array
y (ndarray) – Y-values at x coordinates, 1D array
b (ndarray) – Spline coefficients (linear term) from spline_dp
c (ndarray) – Spline coefficients (quadratic term) from spline_dp
d (ndarray) – Spline coefficients (cubic term) from spline_dp

Returns:

Interpolated value at u

Return type:

float

pulsesuite.libpulsesuite.spliner.spline_dpc(x, y, b, c, d)¶

Compute the cubic spline interpolant for complex arrays.

Computes the coefficients b, c, d for cubic spline interpolation of the complex function y(x). The spline can then be evaluated using seval_dpc.

Parameters:

x (ndarray) – X-coordinates, 1D array, must be in ascending order
y (ndarray) – Complex Y-values at x coordinates, 1D array
b (ndarray) – Output array for complex spline coefficients (linear term)
c (ndarray) – Output array for complex spline coefficients (quadratic term)
d (ndarray) – Output array for complex spline coefficients (cubic term)

Notes

The arrays b, c, d are modified in-place. The spline evaluation uses: y(x) = y[i] + dx*(b[i] + dx*(c[i] + dx*d[i])) where dx = x - x[i] and i is the index such that x[i] <= x < x[i+1].

pulsesuite.libpulsesuite.spliner.seval_dpc(u, x, y, b, c, d)¶

Evaluate the cubic spline for complex arrays.

Evaluates the cubic spline at point u using the pre-computed spline coefficients b, c, d from spline_dpc.

Parameters:

u (float) – Position to interpolate
x (ndarray) – X-coordinates used to compute spline, 1D array
y (ndarray) – Complex Y-values at x coordinates, 1D array
b (ndarray) – Complex spline coefficients (linear term) from spline_dpc
c (ndarray) – Complex spline coefficients (quadratic term) from spline_dpc
d (ndarray) – Complex spline coefficients (cubic term) from spline_dpc

Returns:

Interpolated complex value at u

Return type:

complex

pulsesuite.libpulsesuite.spliner.seval2_dp(x0, x, y, y2)¶

Evaluate the cubic spline for real arrays (second derivative version).

Evaluates the cubic spline at point x0 using the pre-computed second derivatives y2 from spline2_dp.

Parameters:

x0 (float) – Position to interpolate
x (ndarray) – X-coordinates used to compute spline, 1D array
y (ndarray) – Function values at x coordinates, 1D array
y2 (ndarray) – Second derivatives from spline2_dp, 1D array

Returns:

Interpolated value at x0

Return type:

float

pulsesuite.libpulsesuite.spliner.spline(x, *args)¶

Unified interface for spline functions.

Automatically dispatches to the appropriate spline function based on argument count and types: - 3 args: (x, y, y2) or (x, z, z2) -> uses spline2_* (second derivative) - 5 args: (x, y, b, c, d) or (x, z, b, c, d) -> uses spline_* (coefficients) - Complex arrays -> uses *_dpc version - Real arrays -> uses *_dp version

Parameters:

x (ndarray) – X-coordinates, 1D array
*args (variable) – Positional arguments: - For spline2: (y, y2) or (z, z2) - For spline: (y, b, c, d) or (z, b, c, d)
**kwargs (dict) – Keyword arguments (alternative to positional args)

Notes

This interface matches the Fortran interface behavior, allowing the same function name to be used for different spline variants.

Examples

>>> # Using spline2 (second derivative version)
>>> spline(x, y, y2)  # calls spline2_dp
>>> spline(x, z, z2)  # calls spline2_dpc (if z is complex)

>>> # Using regular spline (coefficient version)
>>> spline(x, y, b, c, d)  # calls spline_dp
>>> spline(x, z, b, c, d)  # calls spline_dpc (if z is complex)

pulsesuite.libpulsesuite.spliner.seval(pos, x, *args)¶

Unified interface for spline evaluation functions.

Automatically dispatches to the appropriate seval function based on argument count and types: - 4 args: (pos, x, y, y2) or (pos, x, z, z2) -> uses seval2_* - 6 args: (pos, x, y, b, c, d) or (pos, x, z, b, c, d) -> uses seval_* - Complex arrays -> uses *_dpc version - Real arrays -> uses *_dp version

Parameters:

pos (float) – Position to interpolate
x (ndarray) – X-coordinates used to compute spline, 1D array
*args (variable) – Positional arguments: - For seval2: (y, y2) or (z, z2) - For seval: (y, b, c, d) or (z, b, c, d)

Returns:

Interpolated value

Return type:

float or complex

Notes

This interface matches the Fortran interface behavior, allowing the same function name to be used for different seval variants.

Examples

>>> # Using seval2 (second derivative version)
>>> seval(x0, x, y, y2)  # calls seval2_dp
>>> seval(x0, x, z, z2)  # calls seval2_dpc (if z is complex)

>>> # Using regular seval (coefficient version)
>>> seval(u, x, y, b, c, d)  # calls seval_dp
>>> seval(u, x, z, b, c, d)  # calls seval_dpc (if z is complex)

pulsesuite.libpulsesuite.spliner.rescale_1D(x0, y0=None, z0=None, x1=None, y1=None, z1=None)¶

Unified interface for 1D rescaling functions.

Automatically dispatches to the appropriate rescale_1D function based on argument types: - If z0 is provided: uses rescale_1D_dpc (complex version) - Otherwise: uses rescale_1D_dp (real version)

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
y0 (ndarray, optional) – Original 1D real array (for rescale_1D_dp)
z0 (ndarray, optional) – Original 1D complex array (for rescale_1D_dpc)
x1 (ndarray) – New X-coordinates, 1D array
y1 (ndarray, optional) – Output 1D real array (for rescale_1D_dp), modified in-place
z1 (ndarray, optional) – Output 1D complex array (for rescale_1D_dpc), modified in-place

Notes

This interface matches the Fortran interface behavior, allowing the same function name to be used for different rescale_1D variants.

pulsesuite.libpulsesuite.spliner.rescale_2D(x0, y0, z0, x1, y1, z1)¶

Unified interface for 2D rescaling functions.

Automatically dispatches to the appropriate rescale_2D function based on argument types: - If z0 is complex: uses rescale_2D_dpc (complex version) - Otherwise: uses rescale_2D_dp (real version)

Parameters:

x0 (ndarray) – Original X-coordinates, 1D array
y0 (ndarray) – Original Y-coordinates, 1D array
z0 (ndarray) – Original 2D array (real or complex)
x1 (ndarray) – New X-coordinates, 1D array
y1 (ndarray) – New Y-coordinates, 1D array
z1 (ndarray) – Output 2D array (real or complex), modified in-place

Notes

This interface matches the Fortran interface behavior, allowing the same function name to be used for different rescale_2D variants.