# n-D Lookup Table

Approximate N-dimensional function

Lookup Tables

## Description

### Supported Block Operations

The n-D Lookup Table block evaluates a sampled representation of a function in N variables

`$y=F\left({x}_{1},{x}_{2},{x}_{3},...,{x}_{N}\right)$`

where the function F can be empirical. The block maps inputs to an output value by looking up or interpolating a table of values you define with block parameters. The block supports flat (constant), linear, and cubic-spline interpolation methods. You can apply these methods to a table of any dimension from 1 through 30.

In the following block, the first input identifies the first dimension (row) breakpoints, the second input identifies the second dimension (column) breakpoints, and so on.

See Port Location After Rotating or Flipping in the Simulink ® documentation for a description of the port order for various block orientations.

### Specification of Breakpoint and Table Data

The following block parameters define the breakpoint and table data.

Block ParameterPurpose
Number of table dimensionsSpecifies the number of dimensions of your lookup table.
BreakpointsSpecifies a breakpoint vector that corresponds to each dimension of your lookup table.
Table dataDefines the associated set of output values.

 Tip   Evenly spaced breakpoints can make the generated code division-free. For more information, see `fixpt_evenspace_cleanup` in the Simulink documentation and Identify questionable fixed-point operations in the Simulink Coder™ documentation.

### How the Block Generates Output

The n-D Lookup Table block generates output by looking up or estimating table values based on the input values:

When block inputs...The n-D Lookup Table block...
Match the values of indices in breakpoint data setsOutputs the table value at the intersection of the row, column, and higher dimension breakpoints
Do not match the values of indices in breakpoint data sets, but are within rangeInterpolates appropriate table values, using the Interpolation method you select
Do not match the values of indices in breakpoint data sets, and are out of rangeExtrapolates the output value, using the Extrapolation method you select

### Other Blocks That Perform Equivalent Operations

You can use the Interpolation Using Prelookup block with the Prelookup block to perform the equivalent operation of one n-D Lookup Table block. This combination of blocks offers greater flexibility that can result in more efficient simulation performance for linear interpolations.

When the lookup operation is an array access that does not require interpolation, use the Direct Lookup Table (n-D) block. For example, if you have an integer value `k` and you want the `k`th element of a table, ```y = table(k)```, interpolation is unnecessary.

## Data Type Support

The n-D Lookup Table block supports all numeric data types that Simulink supports, including fixed-point data types. For more information, see Data Types Supported by Simulink in the Simulink documentation.

For cubic spline interpolation and linear extrapolation modes, the following parameters must use the same floating-point type:

• Table data

• Breakpoints

• Fraction

• Intermediate results

• Output

Inputs for indexing must be real, but table data can be complex.

## Parameters

### Table and Breakpoints Tab

Number of table dimensions

Enter the number of dimensions of the lookup table by specifying an integer from `1` to `30`. This parameter determines:

• The number of independent variables for the table and the number of block inputs

• The number of breakpoint sets to specify

Data specification

From the list, select:

• `Table and breakpoints` — Specify the table data and breakpoints. Selecting this option enables these parameters:

• Table data

• Breakpoints specification

• Breakpoints 1

• Breakpoints 2

• Breakpoints 3

• Edit table and breakpoints

• `Lookup table object` — Use an existing lookup table (`Simulink.LookupTable`) object. Selecting this option enables the Name field and Edit table and breakpoints button.

Name

Enter the name of the lookup table (`Simulink.LookupTable`) object.

Table data

Enter the table of output values.

During simulation, the matrix size must match the dimensions defined by the Number of table dimensions parameter. However, during block diagram editing, you can enter an empty matrix (specified as `[]`) or an undefined workspace variable. This technique lets you postpone specifying a correctly dimensioned matrix for the table data and continue editing the block diagram. For information about how to construct multidimensional arrays in MATLAB®, see Multidimensional Arrays in the MATLAB online documentation.

Breakpoints specification

Specify whether to enter data as explicit breakpoints or as parameters that generate evenly spaced breakpoints.

• To explicitly specify breakpoint data, set this parameter to `Explicit values` and enter breakpoint data in the text box next to the Breakpoints parameters.

• To specify parameters that generate evenly spaced breakpoints, set this parameter to `Even spacing` and enter values for the First point and Spacing parameters for each dimension of breakpoint data. The block calculates the number of points to generate from the table data.

First point

Specify the first point in your evenly spaced breakpoint data. This parameter is available when Breakpoints specification is set to `Even spacing`.

Spacing

Specify the spacing between points in your evenly-spaced breakpoint data. This parameter is available when Breakpoints specification is set to `Even spacing`.

Breakpoints

Specify the breakpoint data explicitly or as evenly-spaced breakpoints, based on the value of the Breakpoints specification parameter.

• If you set Breakpoints specification to Even spacing, enter the parameters First point and Spacing in each Breakpoints row to generate evenly-spaced breakpoints in the respective dimension. Your table data determines the number of evenly spaced points.

• If you set Breakpoints specification to ```Explicit values```, enter the breakpoint set that corresponds to each dimension of table data in each Breakpoints row. For each dimension, specify breakpoints as a 1-by-n or n-by-1 vector whose values are strictly monotonically increasing.

Edit table and breakpoints

Click this button to open the Lookup Table Editor. For more information, see Edit Lookup Tables in the Simulink documentation.

Clicking this button for a lookup table object lets you edit the object and save the new values for the object.

Sample time
 Note:   This parameter is not visible in the block dialog box unless it is explicitly set to a value other than `-1`. To learn more, see Blocks for Which Sample Time Is Not Recommended.

### Algorithm Tab

Interpolation method

Select `Flat`, `Nearest`, `Linear`, or `Cubic spline`. See Interpolation Methods in the Simulink documentation for more information.

If you select `Cubic spline`, the block supports only scalar signals. The other interpolation methods support nonscalar signals.

Extrapolation method

Select `Clip`, `Linear`, or `Cubic spline`. See Extrapolation Methods in the Simulink documentation for more information.

To select `Cubic spline` for Extrapolation method, you must also select `Cubic spline` for Interpolation method.

Use last table value for inputs at or above last breakpoint

Using this check box, specify the indexing convention that the block uses to address the last element of a breakpoint set and its corresponding table value. This check box is relevant if the input is larger than the last element of the breakpoint data. This parameter is visible only when:

• Interpolation method is `Linear`.

• Extrapolation method is `Clip`.

Check BoxBlock Uses Index Of The...Interval Fraction
SelectedLast element of breakpoint data on the Table and Breakpoints tab0
ClearedNext-to-last element of breakpoint data on the Table and Breakpoints tab1

Given an input u within range of a breakpoint set bp, the interval fraction f, in the range 0 ≤ f ≤ 1, is computed as shown below.

Suppose the breakpoint set is `[1 4 5]` and input u is `5.5`. If you select this check box, the index is that of the last element (`5`) and the interval fraction is 0. If you clear this checkbox, the index is that of the next-to-last element (`4`) and the interval fraction is 1.

Diagnostic for out-of-range input

Specify whether to produce a warning or error when the input is out of range. Options include:

• `None` — no warning or error

• `Warning` — display a warning in the MATLAB Command Window and continue the simulation

• `Error` — halt the simulation and display an error in the Diagnostic Viewer

Remove protection against out-of-range input in generated code

Specify whether or not to include code that checks for out-of-range breakpoint input values.

Check BoxResultWhen to Use

Selected

Generated code does not include conditional statements to check for out-of-range breakpoint inputs.

For code efficiency

Cleared

Generated code includes conditional statements to check for out-of-range breakpoint inputs.

For safety-critical applications

Depending on your application, you can run the following Model Advisor checks to verify the usage of this check box:

• By Product > Embedded Coder > Identify lookup table blocks that generate expensive out-of-range checking code

• By Product > Simulink Verification and Validation > Modeling Standards > DO-178C/DO-331 Checks > Check usage of lookup table blocks

For more information about the Model Advisor, see Run Model Checks in the Simulink documentation.

Index search method

Select `Evenly spaced points`, ```Linear search```, or `Binary search`. Each search method has speed advantages in different circumstances:

• For evenly spaced breakpoint sets (for example, 10, 20, 30, and so on), you achieve optimal speed by selecting ```Evenly spaced points``` to calculate table indices.

This algorithm uses only the first two breakpoints of a set to determine the offset and spacing of the remaining points.

• For unevenly spaced breakpoint sets, follow these guidelines:

• If input signals do not vary much between time steps, selecting `Linear search` with Begin index search using previous index result produces the best performance.

• If input signals jump more than one or two table intervals per time step, selecting `Binary search` produces the best performance.

A suboptimal choice of index search method can lead to slow performance of models that rely heavily on lookup tables.

 Note:   The generated code stores only the first breakpoint, the spacing, and the number of breakpoints when:The breakpoint data is not tunable.The index search method is ```Evenly spaced points```.
Begin index search using previous index result

Select this check box when you want the block to start its search using the index found at the previous time step. For inputs that change slowly with respect to the interval size, enabling this option can improve performance. Otherwise, the linear search and binary search methods can take longer, especially for large breakpoint sets.

Use one input port for all input data

Select this check box to use only one input port that expects a signal that is N elements wide for an N-dimensional table. This option is useful for removing line clutter on a block diagram with many lookup tables.

 Note:   When you select this check box, one input port with the label `u` appears on the block.
Support tunable table size in code generation

Select this check box to enable tunable table size in the generated code. This option enables you to change the size and values of the lookup table and breakpoint data in the generated code without regenerating or recompiling the code.

If you set Interpolation method to ```Cubic spline```, this check box is not available.

Maximum indices for each dimension

Specify the maximum index values for each table dimension using zero-based indexing. You can specify a scalar or vector of positive integer values using the following data types:

• Built-in floating-point types: `double` and `single`

• Built-in integer types: `int8`, `int16`, `int32`, `uint8`, `uint16`, and `uint32`

Here are some examples of valid specifications:

• `[4 6]` for a 5-by-7 table

• `[int8(2) int16(5) int32(9)]` for a 3-by-6-by-10 table

• A `Simulink.Parameter` whose value on generating code is one less than the dimensions of the table data. For more information, see Tunable Table Size in the Generated Code.

This parameter is available when you select Support tunable table size in code generation. On tuning this parameter in the generated code, provide the new table data and breakpoints along with the tuned parameter value.

### Data Types Tab

 Note:   The dialog box can expand to show additional data type options. Up to 30 breakpoint data type specifications can appear.
Table data > Data Type

Specify the table data type. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Same as output```

• The name of a built-in data type, for example, `single`

• The name of a data type object, for example, a `Simulink.NumericType` object

• An expression that evaluates to a data type, for example, `fixdt(1,16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the table data type.

 Tip   Specify a table data type different from the output data type for these cases:Lower memory requirement for storing table data that uses a smaller type than the output signalSharing of prescaled table data between two n-D Lookup Table blocks with different output data typesSharing of custom storage table data in the generated code for blocks with different output data types
Table data > Minimum

Specify the minimum value for table data. The default value is `[]` (unspecified).

Table data > Maximum

Specify the maximum value for table data. The default value is `[]` (unspecified).

Breakpoints > Data Type

Specify the data type for a set of breakpoint data. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Same as corresponding input```

• The name of a built-in data type, for example, `single`

• The name of a data type object, for example, a `Simulink.NumericType` object

• An expression that evaluates to a data type, for example, `fixdt(1,16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the breakpoint data type.

See Specify Data Types Using Data Type Assistant in the Simulink documentation for more information.

 Tip   Specify a breakpoint data type different from the corresponding input data type for these cases:Lower memory requirement for storing breakpoint data that uses a smaller type than the input signalSharing of prescaled breakpoint data between two n-D Lookup Table blocks with different input data typesSharing of custom storage breakpoint data in the generated code for blocks with different input data types
Breakpoints > Minimum

Specify the minimum value that a set of breakpoint data can have. The default value is `[]` (unspecified).

Breakpoints > Maximum

Specify the maximum value that a set of breakpoint data can have. The default value is `[]` (unspecified).

Fraction > Data Type

Specify the fraction data type. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Inherit via internal rule```

• The name of a built-in data type, for example, `single`

• The name of a data type object, for example, a `Simulink.NumericType` object

• An expression that evaluates to a data type, for example, `fixdt(1,16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the fraction data type.

See Specify Data Types Using Data Type Assistant in the Simulink documentation for more information.

Intermediate results > Data Type

Specify the intermediate results data type. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Same as output```

• The name of a built-in data type, for example, `single`

• The name of a data type object, for example, a `Simulink.NumericType` object

• An expression that evaluates to a data type, for example, `fixdt(1,16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the intermediate results data type.

 Tip   Use this parameter to specify higher (or lower) precision for internal computations than for table data or output data.
Output > Data Type

Specify the output data type. You can set it to:

• A rule that inherits a data type, for example, ```Inherit: Inherit via back propagation```

• The name of a built-in data type, for example, `single`

• The name of a data type object, for example, a `Simulink.NumericType` object

• An expression that evaluates to a data type, for example, `fixdt(1,16,0)`

Click the Show data type assistant button to display the Data Type Assistant, which helps you set the output data type.

See Control Signal Data Types for more information.

Output > Minimum

Specify the minimum value that the block outputs. The default value is `[]` (unspecified). Simulink software uses this value to perform:

Output > Maximum

Specify the maximum value that the block outputs. The default value is `[]` (unspecified). Simulink software uses this value to perform:

Internal rule priority

Specify the internal rule for intermediate calculations. Select `Speed` for faster calculations. If you do, a loss of accuracy might occur, usually up to 2 bits.

Require all inputs to have the same data type

Select to require all inputs to have the same data type.

Lock data type settings against changes by the fixed-point tools

Select to lock all data type settings of this block against changes by the Fixed-Point Tool and the Fixed-Point Advisor. For more information, see Fixed-Point Tool and Preparation for Fixed-Point Conversion in the Fixed-Point Designer™ documentation.

Integer rounding mode

Specify the rounding mode for fixed-point lookup table calculations that occur during simulation or execution of code generated from the model. For more information, see Rounding in the Fixed-Point Designer documentation.

This option does not affect rounding of values of block parameters. Simulink rounds such values to the nearest representable integer value. To control the rounding of a block parameter, enter an expression using a MATLAB rounding function into the edit field on the block dialog box.

Saturate on integer overflow
ActionReasons for Taking This ActionWhat Happens for OverflowsExample

Select this check box.

Your model has possible overflow and you want explicit saturation protection in the generated code.

Overflows saturate to either the minimum or maximum value that the data type can represent.

An overflow associated with a signed 8-bit integer can saturate to -128 or 127.

Do not select this check box.

You want to optimize efficiency of your generated code.

You want to avoid overspecifying how a block handles out-of-range signals. For more information, see Checking for Signal Range Errors.

Overflows wrap to the appropriate value that is representable by the data type.

The number 130 does not fit in a signed 8-bit integer and wraps to -126.

 Tip   If you save your model as version R2009a or earlier, this check box setting has no effect and no saturation code appears. This behavior preserves backward compatibility.

When you select this check box, saturation applies to every internal operation on the block, not just the output or result. In general, the code generation process can detect when overflow is not possible. In this case, the code generator does not produce saturation code.

## Examples

### Interpolation and Extrapolation Behavior

For an example that illustrates linear interpolation and extrapolation methods of this block, see Create a Logarithm Lookup Table in the Simulink documentation.

For an example of entering breakpoint and table data, see Entering Data in a Block Parameter Dialog Box in the Simulink documentation.

### Tunable Table Size in the Generated Code

Suppose that you have a lookup table and want to make the size tunable in the generated code. When you use `Simulink.LookupTable` and `Simulink.Breakpoint` objects to configure lookup table data for calibration in the generated code, use the `SupportTunableSize` property of the objects to enable a tunable table size. When you do not use these classes, use the Support tunable table size in code generation parameter in an n-D Lookup Table block to enable a tunable table size.

Assume that:

• You define a `Simulink.Parameter` structure in the preload function of your model:

```p = Simulink.Parameter; p.Value.MaxIdx = [2 2]; p.Value.BP1 = [1 2 3]; p.Value.BP2 = [1 4 16]; p.Value.Table = [4 5 6; 16 19 20; 10 18 23]; p.DataType = 'Bus: slLookupTable'; p.CoderInfo.StorageClass = 'ExportedGlobal'; % Create bus object slBus1 from MATLAB structure Simulink.Bus.createObject(p.Value); slLookupTable = slBus1; slLookupTable.Elements(1).DataType = 'uint32';```
• The following block parameters apply in the n-D Lookup Table block dialog box:

ParameterValue
Number of table dimensions`2`
Table data`p.Table`
Breakpoints 1`p.BP1`
Breakpoints 2`p.BP2`
Support tunable table size in code generation`on`
Maximum indices for each dimension`p.MaxIdx`

The generated `model_types.h` header file contains a type definition that looks something like this:

```typedef struct { uint32_T MaxIdx[2]; real_T BP1[3]; real_T BP2[3]; real_T Table[9]; } slLookupTable; ```

The generated `model.c` file contains code that looks something like this:

```/* Exported block parameters */ slLookupTable p = { { 2U, 2U }, { 1.0, 2.0, 3.0 }, { 1.0, 4.0, 16.0 }, { 4.0, 16.0, 10.0, 5.0, 19.0, 18.0, 6.0, 20.0, 23.0 } } ; /* More code */ /* Model output function */ static void ex_lut_nd_tunable_table_output(int_T tid) { /* Lookup_n-D: '<Root>/n-D Lookup Table' incorporates: * Inport: '<Root>/In1' * Inport: '<Root>/In2' */ Y = look2_binlcpw(U1, U2, p.BP1, p.BP2, p.Table, ... p.MaxIdx, p.MaxIdx[0] + 1U); /* Outport: '<Root>/Out1' */ ex_lut_nd_tunable_table_Y.Out1 = Y; /* tid is required for a uniform function interface. * Argument tid is not used in the function. */ UNUSED_PARAMETER(tid); } ```

The highlighted line of code specifies a tunable table size for the lookup table. You can change the size and values of the lookup table and breakpoint data without regenerating or recompiling the code.

## Characteristics

 Data Types Double | Single | Base Integer | Fixed-Point Sample Time Inherited from driving block Multidimensional Signals No Variable-Size Signals No Zero-Crossing Detection No Code Generation Yes

## See Also

#### Introduced in R2011a

Was this topic helpful?

Download now