Documentation

tablelookup

Return value based on interpolating set of data points

Syntax

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

Description

Use the tablelookup function in the equations section to compute an output value by interpolating the 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)

x1dData 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.
x2dData 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 and three-dimensional table lookup.
x3dData 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 table lookup.
x4dData 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 three-dimensional table lookup.
fdData 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.

x1The input value along the first direction. Its units must be commensurate with the units of x1d. This is a required argument.
x2The input value along the second direction. Its units must be commensurate with the units of x2d. This argument is used only for the two-dimensional and three-dimensional table lookup.
x3The input value along the third direction. Its units must be commensurate with the units of x3d. This argument is used only for the three-dimensional table lookup.
x4The input value along the fourth direction. Its units must be commensurate with the units of x4d. This argument is used only for the four-dimensional table lookup.
interpolation = linear|smoothOptional 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|nearestOptional 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 and three-dimensional table lookup, uses an extension of linear algorithm for multidimensional interpolation, by performing linear interpolation in first direction, then in second direction, and then in third direction. Use this method to get the best performance.

  • smooth — Uses a modified Akima algorithm, described in Smooth Interpolation Algorithm. 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.

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 x4dOutputs 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

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.

Examples

1D Lookup Table Implementation

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 (Size=variable)
   xd = [1 2 3 4];
   yd = [1 2 3 4];
 end
 equations
   y == tablelookup(xd, yd, u);
 end
end

xd and yd are declared as variable-size parameters. This enables 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.

2D Lookup Table Implementation

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 (Size=variable)
   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

x1d, x2d, and fd are declared as variable-size parameters. 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, as described in Smooth Interpolation Algorithm. The extrapolation uses the nearest value of fd for out-of-range u1 and u2 values.

Using Lookup Table with Units

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 (Size=variable)
   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 variable-size 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.

Smooth Interpolation Algorithm

For smooth interpolation, the function uses a modified Akima algorithm. For one-dimensional smooth interpolation, the Akima algorithm, described in [1], produces a continuous curve with continuous first-order derivatives. It also tries to preserve the slope and avoid undulations where the data suggests a flat region.

The algorithm interprets the data as a flat region whenever there are three or more consecutive colinear points in the table data. It then connects those three or more points with a straight line. The colinear points do not have to be horizontal. To ensure that the region between two data points is flat, insert an additional data point between those two points.

The following graphic shows the difference between the Akima and spline interpolation.

When two flat regions with different slopes meet, it is not possible to avoid an undulation while maintaining smoothness. The original Akima algorithm gives equal weights to the points on both sides, thus evenly dividing the undulation. The modified algorithm, used in this function, gives more weight to the side where the slope is closer to zero. This modification gives priority to the side that is closer to horizontal, which is more intuitive (see next graphic).

For multidimensional interpolation, the Akima method is extended by computing the mixed derivatives at the grid points using a weighted average of the finite differences, as described in [2].

References

[1] Akima, Hiroshi. "A new method of interpolation and smooth curve fitting based on local procedures." Journal of the ACM (JACM) , 17.4, 1970, pp. 589-602.

[2] Akima, Hiroshi. "A method of bivariate interpolation and smooth surface fitting based on local procedures." Communications of the ACM , 17.1, 1974, pp. 18-20.

Introduced in R2012a

Was this topic helpful?