tablelookup

Return value based on interpolating set of data points

Parent Section: equations

Syntax

```tablelookup(x1d, x2d, x3d, x4d, fd, x1, x2, x3, x4, interpolation = linear|smooth, extrapolation = linear|nearest|error)
```

Description

Use the `tablelookup` function in the `equations` section to compute an output value by interpolating the query input value against a set of data points. This functionality is similar to that of the Simulink® and Simscape™ Lookup Table blocks. It allows you to incorporate table-driven modeling directly in your custom block, without the need of connecting an external Lookup Table block to your model.

The `tablelookup` function supports one-dimensional, two-dimensional, three-dimensional, and four-dimensional lookup tables. The full syntax is:

```tablelookup(x1d, x2d, x3d, x4d, fd, x1, x2, x3, x4, interpolation = linear|smooth, extrapolation = linear|nearest|error) ```
 `x1d` Data set of input values along the first direction, specified as a one-dimensional array. The values must be strictly monotonic, either increasing or decreasing. This is a required argument. `x2d` Data set of input values along the second direction, specified as a one-dimensional array. The values must be strictly monotonic, either increasing or decreasing. This argument is used only for the two-dimensional, three-dimensional, and four-dimensional table lookup. `x3d` Data set of input values along the third direction, specified as a one-dimensional array. The values must be strictly monotonic, either increasing or decreasing. This argument is used only for the three-dimensional and four-dimensional table lookup. `x4d` Data set of input values along the fourth direction, specified as a one-dimensional array. The values must be strictly monotonic, either increasing or decreasing. This argument is used only for the four-dimensional table lookup. `fd` Data set of output values for the table lookup. This is a required argument. For one-dimensional table lookup, `fd` must be a one-dimensional array of the same size as `x1d`. For two-dimensional table lookup, `fd` must be a two-dimensional array, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, and `x2d` is a 1-by-`n` array, then `fd` must be an `m`-by-`n` matrix.For three-dimensional table lookup, `fd` must be a three-dimensional array, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, `x2d` is a 1-by-`n` array, and `x3d` is a 1-by-`p` array, then `fd` must be an `m`-by-`n`-by-`p` array.For four-dimensional table lookup, `fd` must be a four-dimensional array, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, `x2d` is a 1-by-`n` array, `x3d` is a 1-by-`p` array, and `x4d` is a 1-by-`q` array, then `fd` must be an `m`-by-`n`-by-`p`-by-`q` array. `x1` The query input value along the first direction, specified as a scalar or as an N-D array. Its units must be commensurate with the units of `x1d`. This is a required argument. `x2` The query input value along the second direction, specified as a scalar or as an N-D array of the same size as `x1`. Its units must be commensurate with the units of `x2d`. This argument is used only for the two-dimensional, three-dimensional, and four-dimensional table lookup. `x3` The query input value along the third direction, specified as a scalar or as an N-D array of the same size as `x1`. Its units must be commensurate with the units of `x3d`. This argument is used only for the three-dimensional and four-dimensional table lookup. `x4` The query input value along the fourth direction, specified as a scalar or as an N-D array of the same size as `x1`. Its units must be commensurate with the units of `x4d`. This argument is used only for the four-dimensional table lookup. `interpolation = linear|smooth` Optional argument that specifies the approximation method for calculating the output value when the input value is inside the range specified in the lookup table. The default is `interpolation = linear`. ```extrapolation = linear|nearest|error``` Optional argument that specifies the approximation method for calculating the output value when the input value is outside the range specified in the lookup table. The default is `extrapolation = linear`.

The `interpolation` argument values are:

• `linear` — For one-dimensional table lookup, uses a linear function. For two-dimensional, three-dimensional, and four-dimensional table lookup, uses an extension of linear algorithm for multidimensional interpolation, by performing linear interpolation in the first direction, then in second direction, then in third direction, and then in fourth direction. Use this method to get the best performance.

• `smooth` — Uses a modified Akima algorithm. For more information, see `makima`. Use this method to produce a continuous curve or surface with continuous first-order derivatives.

The `extrapolation` argument values are:

• `linear`— Extends from the edge of the interpolation region linearly. The slope of the linear extrapolation is equal to the slope of the interpolated curve or surface at the edge of the interpolation region. Use this method to produce a curve or surface with continuous value and continuous first-order derivatives at the boundary between the interpolation region and the extrapolation region.

• `nearest` — Extends from the edge of the interpolation region as a constant. The value of the nearest extrapolation is equal to the value of the interpolated curve or surface at the edge of the interpolation region. Use this method to produce a curve or surface with continuous value at the boundary between the interpolation region and the extrapolation region that does not go above the highest point in the data or below the lowest point in the data.

• `error` — Generates an error when the input value is outside the range specified in the lookup table.

The function returns an output value, in the units specified for `fd`, by looking up or estimating table values based on the input values:

When inputs `x1`, `x2`, `x3`, and `x4`...The `tablelookup` function...
Match the values in the input data sets, `x1d`, `x2d`, `x3d`, and `x4d`Outputs the corresponding table value, `fd`
Do not match the values in the input data sets, but are within rangeInterpolates appropriate table values, using the method specified as the `interpolation` argument value
Do not match the values in the input data sets, and are out of rangeExtrapolates the output value, using the method specified as the `extrapolation` argument value

If the query input values `x1`, `x2`, `x3`, and `x4` are:

• Scalar, then the function returns a scalar.

• N-D arrays, then the function returns an N-D array of the same size.

Error Checking

The following rules apply to data sets `x1d`, `x2d`, `x3d`, `x4d`, and `fd`:

• For one-dimensional table lookup, `x1d` and `fd` must be one-dimensional arrays of the same size.

• For two-dimensional table lookup, `x1d` and `x2d` must be one-dimensional arrays, and `fd` must be a matrix, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, and `x2d` is a 1-by-`n` array, then `fd` must be an `m`-by-`n` matrix.

• For three-dimensional table lookup, `x1d`, `x2d`, and `x3d` must be one-dimensional arrays, and `fd` must be a three-dimensional array, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, `x2d` is a 1-by-`n` array, and `x3d` is a 1-by-`p` array, then `fd` must be an `m`-by-`n`-by-`p` array.

• For four-dimensional table lookup, `x1d`, `x2d`, `x3d`, and `x4d` must be one-dimensional arrays, and `fd` must be a four-dimensional array, with the size matching the dimensions defined by the input data sets. For example, if `x1d` is a 1-by-`m` array, `x2d` is a 1-by-`n` array, `x3d` is a 1-by-`p` array, and `x4d` is a 1-by-`q` array, then `fd` must be an `m`-by-`n`-by-`p`-by-`q` array.

• The `x1d`, `x2d`, `x3d`, and `x4d` values must be strictly monotonic, either increasing or decreasing.

• For smooth interpolation, each data set of input values must contain at least three values. For linear interpolation, two values are sufficient.

Using Enumerations for Interpolation and Extrapolation Options

The Foundation library includes built-in enumerations, `interpolation.m` and `extrapolation.m`:

```classdef interpolation < int32 enumeration linear (1) smooth (2) end methods(Static) function map = displayText() map = containers.Map; map('linear') = 'Linear'; map('smooth') = 'Smooth'; end end end```
```classdef extrapolation < int32 enumeration linear (1) nearest (2) error (3) end methods(Static) function map = displayText() map = containers.Map; map('linear') = 'Linear'; map('nearest') = 'Nearest'; map('error') = 'Error'; end end end```

These enumerations are located in the directory `matlabroot``\toolbox\physmod\simscape\library\m\+simscape\+enum`.

You can use these enumerations to declare component parameters, and then use these parameters as `tablelookup` function arguments. For more information, see the User-Specified Interpolation and Extrapolation Methods example and Using Enumeration in Function Arguments.

Examples

expand all

This example implements a one-dimensional lookup table with linear interpolation and extrapolation.

```component tlu_1d_linear inputs u = 0; end outputs y = 0; end parameters xd = [1 2 3 4]; yd = [1 2 3 4]; end equations y == tablelookup(xd, yd, u); end end```

Parameters `xd` and `yd` allow the block users to provide their own data sets when the component is converted to a custom block. For more information, see Using Lookup Tables in Equations.

The `xd` values must be strictly monotonic, either increasing or decreasing. `yd` must have the same size as `xd`.

This example implements a two-dimensional lookup table with specific interpolation and extrapolation methods.

```component tlu_2d inputs u1 = 0; u2 = 0; end outputs f = 0; end parameters x1d = [1 2 3 4]; x2d = [1 2 3]; fd = [1 2 3; 3 4 5; 5 6 7; 7 8 9]; end equations f == tablelookup(x1d, x2d, fd, u1, u2, interpolation=smooth, extrapolation=nearest); end end```

Parameters `x1d`, `x2d`, and `fd` allow the block users to provide their own data sets when the component is converted to a custom block. The `x1d` and `x2d` vector values must be strictly monotonic, either increasing or decreasing. For smooth interpolation, each vector must have at least three values. The size of the `fd` matrix must match the dimensions of the `x1d` and `x2d` vectors.

The interpolation uses the modified Akima algorithm, `makima`. The extrapolation uses the nearest value of `fd` for out-of-range `u1` and `u2` values.

This example is similar to the previous one, but it gives the block user control over the interpolation and extrapolation methods.

```import simscape.enum.* component tlu_2d_enum inputs u1 = 0; u2 = 0; end outputs f = 0; end parameters x1d = [1 2 3 4]; x2d = [1 2 3]; fd = [1 2 3; 3 4 5; 5 6 7; 7 8 9]; end parameters interp = interpolation.linear; % Interpolation method extrap = extrapolation.linear; % Extrapolation method end equations f == tablelookup(x1d, x2d, fd, u1, u2, interpolation=interp, extrapolation=extrap); end end```

The component imports the built-in enumerations, and then uses them to declare two additional parameters: `interp` (Interpolation method) and `extrap` (Extrapolation method). The `tablelookup` function uses these parameters as arguments, to specify the interpolation and extrapolation methods. For more information, see Using Enumeration in Function Arguments.

The block generated from this component will have the Interpolation method and Extrapolation method parameters, both with the default value of `Linear`. The block user can select any other interpolation and extrapolation options.

This example implements a one-dimensional lookup table with units, to map temperature to pressure, with linear interpolation and extrapolation.

```component TtoP inputs u = {0,'K'}; % temperature end outputs y = {0,'Pa'}; % pressure end parameters xd = {[100 200 300 400] 'K'}; yd = {[1e5 2e5 3e5 4e5] 'Pa'}; end equations y == tablelookup(xd,yd,u); end end```

`xd` and `yd` are declared as parameters with units. This enables the block users to provide their own data sets when the component is converted to a custom block, and also to select commensurate units from the drop-downs in the custom block dialog box. For more information, see Using Lookup Tables in Equations.

The `xd` values must be strictly monotonic, either increasing or decreasing. `yd` must have the same size as `xd`.

Version History

Introduced in R2012a