ILNumerics Ultimate VS

Interpolation.splinens Method (InArray<fcomplex>, InCell, InArray<fcomplex>)

ILNumerics Ultimate VS Documentation
ILNumerics - Technical Application Development
N-dimensional spline interpolation of scattered data from gridded points.

[ILNumerics Interpolation Toolbox]

Namespace:  ILNumerics.Toolboxes
Assembly:  ILNumerics.Toolboxes.Interpolation (in ILNumerics.Toolboxes.Interpolation.dll) Version: 5.5.0.0 (5.5.7503.3146)
Syntax

public static RetArray<fcomplex> splinens(
	InArray<fcomplex> V,
	InCell X,
	InArray<fcomplex> Xn
)

Parameters

V
Type: ILNumerics.InArray<fcomplex>
Known values as n-dimensional array, at least 4 samples in each dimension.
X
Type: ILNumerics.InCell
Grid position vectors for the values in V (non-/uniform), matching the lengths of corresponding dims in V. Cell array of length N.
Xn
Type: ILNumerics.InArray<fcomplex>
Interpolation grid vectors (non-/uniform), matrix of size [n x m].

Return Value

Type: RetArray<fcomplex>
Spline interpolated values at scattered positions as determined by Xn. Size [1 x m].
Exceptions

ExceptionCondition
ArgumentExceptionif V has less than 4 elements in any dimension or any range in X does not match the corresponding dimension length in V.
ArgumentNullException if on entry any of V or X are null.
Remarks

splinens(InArray<fcomplex> , InCell, InCell) performs efficient piecewise cubic interpolation with continous 2nd derivatives on an n-dimensional regular grid of sampled values V. X is expected as a cell vector with [V.S.NumberOfDimensions] arrays as cell elements. Each element is a numeric array (preferred: Array<T> corresponding to element type T of V) with strictly monotonically increasing range specifications for the corresponding dimensions in V. The spacing between elements must not be uniform.

The spline interpolation function created by splinen(InArray<fcomplex> , InCell, InCell) will always match the given data values V at the specified sample positions X.

New values to be interpolated are specified by the columns in Xn.

Any range for V not provided in X (i.e. the corresponding cell element X_i is null or empty) is automatically replaced by an upwards counting vector: counter(0,1,size(l,1)), where l=V.S[i]. If the parameter X is null on entry, the same scheme applies to all dimensions of V.

Note, that in difference to splinen(InArray<fcomplex> , InCell, InCell) both, X and Xn are obligatory parameters! Xn is not allowed to be null on entry.

X is allowed to hold not only vectors but n-dimensional arrays as the result of the meshgrid(InArray<fcomplex> , InArray<fcomplex> , InArray<fcomplex> , OutArray<fcomplex> , OutArray<fcomplex> ) function. In this case, only the first 'vector' along each corresponding dimension is considered from the input arrays. If, let's say, a matrix is given for the first cell element in X the first column is extracted and its values are assumed for the ranges of the first dimension in V. Note that all n-dimensional functions expect the common order of dimensions: 1st dimension goes along the columns, 2nd dimension goes along the rows. This (intentionally) differs from the somehow mixed-up way meshgrid(InArray<fcomplex> , InArray<fcomplex> , InArray<fcomplex> , OutArray<fcomplex> , OutArray<fcomplex> ) shows.

Any values from Xn laying outside of the range of X will cause the corresponding result elements to be marked as 'NaN' values. Use the overload [!:splinens(InArray<fcomplex>, InCell, InArray<fcomplex>, fcomplex?)] to control this value or to compute extrapolated values at those positions.

Algorithm: [!:splinens(InArray<fcomplex>, InCell, InArray<fcomplex>, fcomplex?)] performs one-dimensional interpolation of the spline coefficients along all n dimensions. The resulting coefficients hypercube is then used to perform a fast and parallelized variant of local cubic evaluation of the surrounding hypercubes for each query point. Good performance is achieved via efficient parallelization in the underlying SplineInterpolatorFComplex object. However, the interpolation of the coefficients in n dimensions require a significant amount of memory: roughly 4 times the original dimension length is required for each dimension. Therefore, on larger data one might consider to use interpns(InArray<fcomplex> , InCell, InCell, InterpolationMethod) with cubic instead.

Support for NaN values: spline interpolation performs interpolation by taking all values of V into account. What enables best smoothness properties on the other hand implies that any NaN value in V populate to all elements of the output. Therefore, one must ensure that no NaN values exist in V. Use cubic polynomial interpolation in [!:Interpolation.interpns(InArray<fcomplex>, InCell, InArray<fcomplex>, InterpolationMethod)] for an alternative on data with NaN values.

This n-dimensional spline interpolation is called from [!:interpns(InArray<fcomplex>, InCell, InArray<fcomplex>, fcomplex?, InterpolationMethod)].

A note on convenience: if the coordinates for new query points exist as individual vectors anyway, consider using the overload splinens(InArray<fcomplex>, InCell, InCell, Nullable<fcomplex>).

References: C. de Boor, A Practical Guide to Splines (Applied Mathematical Sciences), Springer, 2001"

[ILNumerics Interpolation Toolbox]

See Also

Reference

[!:interpns(InArray<fcomplex>, InCell, InArray<fcomplex>, fcomplex?, InterpolationMethod)]
InterpolationInternal.interpn(InArray<fcomplex>, Nullable<fcomplex>, InCell, InCell, InterpolationMethod)
[!:spline(InArray<fcomplex>, fcomplex?, InArray<fcomplex>, InArray<fcomplex>, InArray<fcomplex>, InArray<fcomplex>)]
[!:splinepath(InArray<fcomplex>, InArray<fcomplex>, InArray<fcomplex>, InArray<fcomplex>, int)]