n-D Lookup Table - Approximate N-dimensional function

Library

Lookup Tables

Description

Supported Block Operations

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

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 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 Parameter	Purpose
Number of table dimensions	Specifies the number of dimensions of your lookup table.
Breakpoints	Specifies a breakpoint vector that corresponds to each dimension of your lookup table.
Table data	Defines 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 sets	Outputs 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 range	Interpolates appropriate table values, using the Interpolation method you select
Do not match the values of indices in breakpoint data sets, and are out of range	Extrapolates 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

The Table and Breakpoints pane of the n-D Lookup Table block dialog box appears as follows:

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 Lookup Table Editor.

Sample time (-1 for inherited)

Specify the time interval between samples. To inherit the sample time, set this parameter to -1. See How to Specify the Sample Time for more information.

The Algorithm pane of the n-D Lookup Table block dialog box appears as follows:

Interpolation method

Select Flat, Linear, or Cubic spline. See Interpolation Methods 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 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

Specify the indexing convention that the block uses to address the last element of a breakpoint set and its corresponding table value.

Check Box	Index That the Block Uses	Interval Fraction
Selected	Last element of a breakpoint set	0
Cleared	Next-to-last element of a breakpoint set	1

This parameter is visible only when:

Interpolation method is Linear.
Extrapolation method is Clip.

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 Simulation Diagnostics 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 Box	Result	When 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-178B Checks > Check usage of lookup table blocks

For more information about the Model Advisor, see Consulting the Model Advisor 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 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.

The Data Types pane of the n-D Lookup Table block dialog box appears as follows:

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 signal
Sharing of prescaled table data between two n-D Lookup Table blocks with different output data types
Sharing 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 Using the Data Type Assistant 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 signal
Sharing of prescaled breakpoint data between two n-D Lookup Table blocks with different input data types
Sharing 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 Using the Data Type Assistant 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 Specifying Block Output 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:

Parameter range checking (see Checking Parameter Values)
Simulation range checking (see Signal Ranges)
Automatic scaling of fixed-point data types

Output > Maximum

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

Parameter range checking (see Checking Parameter Values)
Simulation range checking (see Signal Ranges)
Automatic scaling of fixed-point data types

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 Fixed-Point Advisor in the Simulink Fixed Point 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 Simulink Fixed Point User's Guide.

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

Action	Reasons for Taking This Action	What Happens for Overflows	Example
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.

Action

Reasons for Taking This Action

What Happens for Overflows

Example

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 Example of a Logarithm Lookup Table in the Simulink User's Guide.

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

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:

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:
Parameter Value

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

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

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

Search MATLAB Documentation
R2012a Documentation → Simulink
View documentation for other releases	Learn more about Simulink