# 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

example

````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,...ni in each dimension. The value of ni 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

collapse all

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

collapse all

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`

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

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 Rn.

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

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

• 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 Rn.

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`

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

`"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

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

collapse all

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`.

## Version History

Introduced in R2024a