Accelerating the pace of engineering and science

# 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 How to Rotate a Block 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 kth 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 and Dialog Box

### 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

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

In each Breakpoints row, enter the breakpoint set that corresponds to each dimension of table data. 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.

Sample time (-1 for inherited)

Specify the time interval between samples. To inherit the sample time, set this parameter to -1. See Specify Sample Time in the Simulink documentation.

### 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

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

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

This parameter is available when you select Support tunable table size in code generation.

### 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.

 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.

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.

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. Assume that:

```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
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 dimensions2
Table datap.Table
Breakpoints 1p.BP1
Breakpoints 2p.BP2
Support tunable table size in code generationon
Maximum indices for each dimensionp.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

 Direct Feedthrough Yes Sample Time Specified in the Sample time parameter Scalar Expansion Yes Dimensionalized Yes, if you do not select Cubic spline for Interpolation method Zero-Crossing Detection No