tablelookup
Return value based on interpolating set of data points
Syntax
tablelookup(x1d, x2d, x3d, x4d, fd, x1, x2, x3, x4,
interpolation = linearsmooth, extrapolation = linearnearesterror)
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 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, threedimensional, and fourdimensional 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 and fourdimensional 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 fourdimensional 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 query input value along the first direction, specified as a scalar or as a
onedimensional array. Its units must be commensurate with the units of

 The query input value along the second direction, specified as a scalar or as a
onedimensional array of the same size as 
 The query input value along the third direction, specified as a scalar or as a
onedimensional array of the same size as 
 The query input value along the fourth direction, specified as a scalar or as a
onedimensional array of the same size as 

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. For more information, seemakima
. 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 
If the query input values x1
, x2
,
x3
, and x4
are:
Scalar, then the function returns a scalar.
Onedimensional arrays, then the function returns a onedimensional array of the same size.
Error Checking
The following rules apply to data sets x1d
, x2d
, x3d
, x4d
,
and fd
:
For onedimensional table lookup,
x1d
andfd
must be onedimensional arrays of the same size.For twodimensional table lookup,
x1d
andx2d
must be onedimensional arrays, andfd
must be a matrix, with the size matching the dimensions defined by the input data sets. For example, ifx1d
is a 1bym
array, andx2d
is a 1byn
array, thenfd
must be anm
byn
matrix.For threedimensional table lookup,
x1d
,x2d
, andx3d
must be onedimensional arrays, andfd
must be a threedimensional array, with the size matching the dimensions defined by the input data sets. For example, ifx1d
is a 1bym
array,x2d
is a 1byn
array, andx3d
is a 1byp
array, thenfd
must be anm
byn
byp
array.For fourdimensional table lookup,
x1d
,x2d
,x3d
, andx4d
must be onedimensional arrays, andfd
must be a fourdimensional array, with the size matching the dimensions defined by the input data sets. For example, ifx1d
is a 1bym
array,x2d
is a 1byn
array,x3d
is a 1byp
array, andx4d
is a 1byq
array, thenfd
must be anm
byn
byp
byq
array.The
x1d
,x2d
,x3d
, andx4d
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 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.
Examples
1D Lookup Table Implementation
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
.
2D Lookup Table Implementation
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, makima
. The
extrapolation uses the nearest value of fd
for outofrange
u1
and u2
values.
UserSpecified Interpolation and Extrapolation Methods
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.
Using Lookup Table with Units
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
.