Return value based on interpolating set of data points
tablelookup(x1d, x2d, x3d, fd, x1, x2, x3, interpolation
= linearsmooth, extrapolation = linearnearest)
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 tabledriven modeling directly
in your custom block, without the need of connecting an external Lookup
Table block to your model.
The tablelookup
function supports onedimensional,
twodimensional, and threedimensional lookup tables. The full syntax
is:
tablelookup(x1d, x2d, x3d, fd, x1, x2, x3, interpolation
= linearsmooth, extrapolation = linearnearest)
x1d  Data set of input values along the first direction, specified as a onedimensional 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 onedimensional array. The values must be strictly monotonic, either increasing or decreasing. This argument is used only for the twodimensional and threedimensional table lookup. 
x3d  Data set of input values along the third direction, specified as a onedimensional array. The values must be strictly monotonic, either increasing or decreasing. This argument is used only for the threedimensional table lookup. 
fd  Data set of output values for the table lookup. This is a required
argument. For onedimensional table lookup, For
twodimensional table lookup, For
threedimensional table lookup, 
x1  The input value along the first direction. Its units must be
commensurate with the units of x1d . This is a required
argument. 
x2  The input value along the second direction. Its units must
be commensurate with the units of x2d . This argument
is used only for the twodimensional and threedimensional table lookup.

x3  The input value along the third direction. Its units must be
commensurate with the units of x3d . This argument
is used only for the threedimensional table lookup. 
interpolation = linearsmooth  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 = linearnearest  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 onedimensional
table lookup, uses a linear function. For twodimensional and threedimensional
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 firstorder
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
firstorder 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 ,
and x3 ...  The tablelookup function... 

Match the values in the input data sets, x1d , x2d ,
and x3d  Outputs the corresponding table value, fd 
Do not match the values in the input data sets, but are within range  Interpolates 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 range  Extrapolates the output value, using the method specified as
the extrapolation argument value 
The following rules apply to data sets x1d
, x2d
, x3d
,
and fd
:
For onedimensional table lookup, x1d
and fd
must
be onedimensional arrays of the same size.
For twodimensional table lookup, x1d
and x2d
must
be onedimensional 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 1bym
array,
and x2d
is a 1byn
array, then fd
must
be an m
byn
matrix.
For threedimensional table lookup, x1d
, x2d
,
and x3d
must be onedimensional arrays, and fd
must
be a threedimensional array, with the size matching the dimensions
defined by the input data sets. For example, if x1d
is
a 1bym
array, x2d
is a 1byn
array,
and x3d
is a 1byk
array, then fd
must
be an m
byn
byk
array.
The x1d
, x2d
,
and x3d
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.
This example implements a onedimensional 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 variablesize 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
.
This example implements a twodimensional 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 variablesize 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
outofrange u1
and u2
values.
This example implements a onedimensional 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 variablesize 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 dropdowns
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
.
For smooth interpolation, the function uses a modified Akima algorithm. For onedimensional smooth interpolation, the Akima algorithm, described in [1], produces a continuous curve with continuous firstorder 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].
[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. 589602.
[2] Akima, Hiroshi. "A method of bivariate interpolation and smooth surface fitting based on local procedures." Communications of the ACM , 17.1, 1974, pp. 1820.