fixed.interpn

Interpolation for 1-D, 2-D, 3-D, and N-D gridded data in ndgrid format

Since R2024a

Syntax

Vq = fixed.interpn(X1,X2,...,Xn,V,Xq1,Xq2,...,Xqn)

Vq = fixed.interpn(V,Xq1,Xq2,...,Xqn)

Vq = fixed.interpn(___,method)

Vq = fixed.interpn(___,method,extrapval)

Description

Vq = fixed.interpn(X1,X2,...,Xn,V,Xq1,Xq2,...,Xqn) returns interpolated values of a function of n variables at specific query points using linear interpolation. The results always pass through the original sampling of the function. X1,X2,...,Xn contain the coordinates of the sample points. V contains the corresponding function values at each sample point. Xq1,Xq2,...,Xqn contain the coordinates of the query points.

Vq = fixed.interpn(V,Xq1,Xq2,...,Xqn) assumes a default grid of sample points. The default grid consists of the points, 1,2,3,...n_i in each dimension. The value of n_i is the length of the ith dimension in V. Use this syntax when you want to conserve memory and are not concerned about the absolute distances between points.

Vq = fixed.interpn(___,method) specifies an alternative interpolation method: "linear" or "nearest". The default method is "linear".

Vq = fixed.interpn(___,method,extrapval) specifies extrapval, a scalar value that is assigned to all queries that lie outside the domain of the sample points.

Examples

Implement N-D Fixed-Point Lookup Tables Using Interpolation

This example shows how to implement an N-dimensional fixed-point lookup table using fixed.interpn.

Run the example multiple times to see the approximation over different query points.

Create Lookup Table for Function

Define a function f(x,y) to replace with a lookup table approximation.

clearvars
f = @(x,y) sin(x)+sin(y)-(x.^2+y.^2)/20;

Define breakpoints x and y for the lookup table. Note that m and n do not have to be equal and x and y do not have to be linearly spaced.

m = 16;
n = 16;
x = linspace(-5,5,n);
y = linspace(-5,5,m);
[X,Y] = ndgrid(x,y);

Generate lookup table values V, corresponding to the breakpoints.

V = f(X,Y);

Query Lookup Table

Choose a random query point (xq,yq) in the ranges of x and y.

xq = fixed.example.realUniformRandomArray(x(1),x(end),1);
yq = fixed.example.realUniformRandomArray(y(1),y(end),1);

Cast the inputs to 16-bit fixed-point.

x = fi(x);
y = fi(y);
V = fi(V);
xq = fi(xq);
yq = fi(yq);

The fixed.interpn function computes vq, the lookup table approximation of f(xq,yq).

vq = fixed.interpn(x,y,V,xq,yq)

vq = 
   -2.0808

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 12

Compare Lookup Approximation to Actual Function Value

Compare vq to the actual function evaluation f(xq,yq).

vq_expected = f(double(xq),double(yq))

vq_expected = 
-2.1175

err = double(vq) - vq_expected

err = 
0.0367

Plot f(x,y).

clf
mesh(x,y,V,'EdgeAlpha',0.8,'FaceAlpha',0);
xlabel('x')
ylabel('y')
zlabel('v')
hold on

Plot vq, the lookup table approximation of f(xq,vq), using a red stem plot.

stem3(xq,yq,vq,'Filled','red')
legend('f(x)','vq = Fixed-point lookup-table approximation of f(xq)','location','best')

Input Arguments

X1,X2,...,Xn — Sample grid points

arrays | vectors

Sample grid points, specified as real arrays or vectors. The sample grid points must be strictly monotonically increasing in each dimension.

• If X1,X2,...,Xn are arrays, then they contain the coordinates of a full grid (in ndgrid format). Use the ngrid function to create the X1,X2,...,Xn arrays together. These arrays must be the same size.

• If X1,X2,...,Xn are vectors, then they are treated as grid vectors. The values in these vectors must be strictly monotonically increasing.

The inputs [X1,X2,...,Xn], V, and [Xq1,Xq2,...,Xqn] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interpn.

Example: [X1,X2,X3,X4] = fi(ndgrid(1:30,-10:10,1:5,10:13))

Example: [X1,X2,X3,X4] = half(ndgrid(1:30,-10:10,1:5,10:13))

Data Types: fi | single | double

V — Sample values

array

Sample values, specified as a real or complex array. The size requirements for V depend on the size of the grid of sample points defined by X1,X2,...,Xn. The sample points X1,X2,...,Xn can be arrays or grid vectors, but in both cases they define an n-dimensional grid. V must be an array that at least has the same n dimension sizes, but it also can have extra dimensions beyond n:

• If V also has n dimensions, then the size of V must match the size of the n-dimensional grid defined by X1,X2,...,Xn. In this case, V contains one set of sample values at the sample points. For example, if X1,X2,X3 are 3-by-3-by-3 arrays, then V can also be a 3-by-3-by-3 array.

• If V has more than n dimensions, then the first n dimensions of V must match the size of the n-dimensional grid defined by X1,X2,...,Xn. The extra dimensions in V define extra sets of sample values at the sample points. For example, if X1,X2,X3 are 3-by-3-by-3 arrays, then V can be a 3-by-3-by-3-by-2 array that defines two sets of sample values at the sample points.

If V contains complex numbers, then fixed.interpn interpolates the real and imaginary parts separately.

The inputs [X1,X2,...,Xn], V, and [Xq1,Xq2,...,Xqn] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interpn.

Example: fi(rand(10,5,3,2))

Example: half(rand(10,5,3,2))

Data Types: fi | single | double
Complex Number Support: Yes

Xq1,Xq2,...,Xqn — Query points

scalars | vectors | arrays

Query points, specified as real scalars, vectors, or arrays.

• If Xq1,Xq2,...,Xqn are scalars, then they are the coordinates of a single query point in Rⁿ.

• If Xq1,Xq2,...,Xqn are vectors of different orientations, then Xq1,Xq2,...,Xqn are treated as grid vectors in Rⁿ.

• If Xq1,Xq2,...,Xqn are vectors of the same size and orientation, then Xq1,Xq2,...,Xqn are treated as scattered points in Rⁿ.

• If Xq1,Xq2,...,Xqn are arrays of the same size, then they represent either a full grid of query points (in ndgrid format) or scattered points in Rⁿ.

The inputs [X1,X2,...,Xn], V, and [Xq1,Xq2,...,Xqn] must be the same data type: fi, half, single, or double. When using fi data, you can use the shortened function name interpn.

Example: [X1,X2,X3,X4] = fi(ndgrid(1:10,1:5,7:9,10:11))

Example: [X1,X2,X3,X4] = half(ndgrid(1:10,1:5,7:9,10:11))

Data Types: fi | single | double

method — Interpolation method

"linear" (default) | "nearest"

Interpolation method, specified as one of the options in this table.

Method	Description	Continuity	Comments
"linear"	The interpolated value at a query point is based on linear interpolation of the values at neighboring grid points in each respective dimension. This method is the default interpolation method.	C0	Requires at least two grid points in each dimension Requires more memory than "nearest"
"nearest"	The interpolated value at a query point is the value at the nearest sample grid point.	Discontinuous	Requires two grid points in each dimension Fastest computation with modest memory requirements

extrapval — Function value outside domain of X1,X2,...,Xn

scalar

Function value outside the domain of X1,X2,...,Xn, specified as a real or complex scalar. interpn returns this constant value for all points outside the domain of X1,X2,...,Xn. If the scalar value is nonzero and outside the range of the sample values v, then this value is set to the minimum or maximum value of v, whichever is closer.

The data type of extrapval must be the same as [X1,X2,...,Xn], V, and [Xq1,Xq2,...,Xqn].

The default behavior with fi input data is to return 0 for query points outside the domain. The default behavior with half, single, or double input data is to return NaN for query points outside the domain.

Example: fi(5)

Example: half(5+1i)

Data Types: fi | single | double
Complex Number Support: Yes

Note

The default behavior of the interpn function is to return NaN when a query point is outside the domain. The fixed.interpn function with fi input data is not consistent with this behavior because fi casts NaN to 0.

Output Arguments

Vq — Interpolated values

scalar | vector | array

Interpolated values, returned as a real or complex scalar, vector, or array. The size and shape of Vq depends on the syntax you use and, in some cases, the size and value of the input arguments. The data type of Vq is the same as that of the sample values V.

• If you specify sample points with X1,X2,...,Xn, or use the default grid, and V has the same number of dimensions as the n-dimensional grid of sample points, then Vq contains a single set of interpolated values at the query points defined by Xq1,Xq2,...,Xqn.

  • If Xq1,Xq2,...,Xqn are scalars, then Vq is a scalar.

  • If Xq1,Xq2,...,Xqn are vectors of the same size and orientation, then Vq is a vector with the same size and orientation.

  • If Xq1,Xq2,...,Xqn are grid vectors of mixed orientation, then Vq is an array with the same size as the grid implicitly defined by the grid vectors.

  • If Xq1,Xq2,...,Xqn are arrays of the same size, then Vq is an array with the same size.

• If you specify sample points with X1,X2,...,Xn, or use the default grid, and V has more dimensions than the n-dimensional grid of sample points, then Vq contains multiple sets of interpolated values at the query points defined by Xq1,Xq2,...,Xqn. In this case, the first n dimensions of Vq follow the size rules for a single set of interpolated values above, but Vq also has the same extra dimensions as V with the same sizes.

• With the syntax fixed.interpn(V), Vq is an array with the same number of dimensions as V, where the size of the ith dimension is 2 * (size(V,i)-1)+1.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Version History

Introduced in R2024a