Return value based on interpolating set of data points

```
tablelookup(x1d, x2d, yd, x1, x2, interpolation =
linear|cubic|spline, extrapolation = linear|nearest)
```

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
and two-dimensional lookup tables. The full syntax is:

```
tablelookup(x1d, x2d, yd, x1, x2, interpolation =
linear|cubic|spline, extrapolation = linear|nearest)
```

`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 table lookup. |

`yd` | Data set of output values for the table lookup. This is a required
argument. For one-dimensional table lookup, For
two-dimensional 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 two-dimensional table lookup. |

`interpolation = linear|cubic|spline` | 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` | 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 table lookup, uses a bilinear interpolation algorithm, which is an extension of linear interpolation for functions in two variables. The method performs linear interpolation first in-direction and then in`x`

-direction.`y`

`cubic`

— For one-dimensional table lookup, uses the Piecewise Cubic Hermite Interpolation Polinomial (PCHIP). For more information, see the`pchip`

MATLAB^{®}function. For two-dimensional table lookup, uses the bicubic interpolation algorithm described in [1].`spline`

— For one-dimensional table lookup, uses the cubic spline interpolation algorithm described in [1]. For two-dimensional table lookup, uses the bicubic spline interpolation algorithm described in [1].

The `extrapolation`

argument values are:

`linear`

— Extrapolates using the linear method, based on the last two output values at the appropriate end of the range. That is, the function uses the first and second specified output values if the input value is below the specified range, and the two last specified output values if the input value is above the specified range.`nearest`

— Uses the last specified output value at the appropriate end of the range. That is, the function uses the last specified output value for all input values greater than the last specified input argument, and the first specified output value for all input values less than the first specified input argument.

The function returns an output value, in the units specified
for `yd`

, by looking up or estimating table values
based on the input values:

When inputs `x1` and `x2` ... | The `tablelookup` function... |
---|---|

Match the values of indices in the input data sets, `x1d` and `x2d` | Outputs the corresponding table value, `yd` |

Do not match the values of indices 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 of indices 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`

,
and `yd`

:

For one-dimensional table lookup,

`x1d`

and`yd`

must be one-dimensional arrays of the same size.For two-dimensional table lookup,

`x1d`

and`x2d`

must be one-dimensional arrays, and`yd`

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`yd`

must be an`m`

-by-`n`

matrix.The

`x1d`

and`x2d`

values must be strictly monotonic, either increasing or decreasing.For cubic or spline interpolation, each data set must contain at least three values. For linear interpolation, two values are sufficient.

If these rules are violated by... | You get an error... |
---|---|

The block author, in the component Simscape file | At build time, when running `ssc_build` to
convert the component to a custom block |

The block user, when entering values in the block dialog box | At simulation time, when attempting to simulate the model containing the custom block |

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`

.

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

component tlu_2d inputs u1 = 0; u2 = 0; end outputs y = 0; end parameters (Size=variable) x1d = [1 2 3 4]; x2d = [1 2 3]; yd = [1 2 3; 3 4 5; 5 6 7; 7 8 9]; end equations y == tablelookup(x1d, x2d, yd, u1, u2, interpolation=spline, extrapolation=nearest); end end

`x1d`

, `x2d`

, and `yd`

are
declared as variable-size parameters. The `x1d`

and `x2d`

vector
values must be strictly monotonic, either increasing or decreasing.
For spline interpolation, each vector must have at least three values.
The size of the `yd`

matrix must match the dimensions
of the `x1d`

and `x2d`

vectors.

The interpolation uses the bicubic spline algorithm. The extrapolation
uses the nearest value of `yd`

for out-of-range `u1`

and `u2`

values.

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`

.

[1] W.H.Press, B.P.Flannery, S.A.Teulkolsky, W.T.Wetterling, *Numerical
Recipes in C: The Art of Scientific Computing*, Cambridge
University Press, 1992

Was this topic helpful?