Return value based on interpolating set of data points
tablelookup(x1d, x2d, x3d, x4d, fd, x1, x2, x3, x4,
interpolation = linearsmooth, extrapolation = linearnearesterror)
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, threedimensional, and fourdimensional lookup tables. The full syntax
is:
tablelookup(x1d, x2d, x3d, x4d, fd, x1, x2, x3, x4,
interpolation = linearsmooth, extrapolation = linearnearesterror)

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. 

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. 

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. 

Data set of input values along the fourth 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. 

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, For fourdimensional table lookup, 

The input value along the first direction. Its units must be commensurate with
the units of 

The input value along the second direction. Its units must be commensurate with
the units of 

The input value along the third direction. Its units must be commensurate with
the units of 

The input value along the fourth direction. Its units must be commensurate with
the units of 

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 

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 
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.
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 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
, x4d
,
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 1byp
array, then fd
must
be an m
byn
byp
array.
For fourdimensional table lookup, x1d
, x2d
, x3d
,
and x4d
must be onedimensional arrays, and fd
must
be a fourdimensional 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, x3d
is
a 1byp
array, and x4d
is a
1byq
array, then fd
must be
an m
byn
byp
byq
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.
The Foundation library includes builtin 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 UserSpecified Interpolation and Extrapolation Methods example and Using Enumeration in Function Arguments.
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 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 (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 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 builtin 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 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.