Documentation

Prelookup

Compute index and fraction for Interpolation Using Prelookup block

Library

Lookup Tables

Description

The Prelookup block calculates the index and interval fraction that specify how its input value u relates to the breakpoint dataset. The Prelookup block works best with the Interpolation Using Prelookup block. Feed the resulting index and fraction values into an Interpolation Using Prelookup block to interpolate an n-dimensional table. These two blocks have distributed algorithms. When combined together, they perform the same operation as the integrated algorithm in the n-D Lookup Table block. However, the Prelookup and Interpolation Using Prelookup blocks offer greater flexibility and more efficient simulation and code generation than the n-D Lookup Table block. For more information, see Efficiency of Performance.

Supported Block Operations

To use the Prelookup block, you specify a set of breakpoint values directly on the dialog box or feed values into the bp input port. Typically, this breakpoint data set corresponds to one dimension of the table data in an Interpolation Using Prelookup block. The Prelookup block generates a pair of outputs for each input value u by calculating:

  • The index of the breakpoint set element that is less than or equal to u and forms an interval containing u

  • The interval fraction in the range 0 ≤ f < 1, representing the normalized position of u on the breakpoint interval between the index and the next index value for in-range input

For example, if the breakpoint data set is [0 5 10 20 50 100] and the input value u is 55, the index is 4 and the fractional value is 0.1. Labels for the index and interval fraction appear as k and f on the Prelookup block icon. The index value is zero based.

The interval fraction can be negative or greater than 1 for out-of-range input. See the documentation for the Extrapolation method block parameter for more information.

Data Type Support

The Prelookup block accepts real signals of numeric data types that Simulink® supports, except Boolean. The Prelookup block supports fixed-point data types for signals and breakpoint data. You can also use a bus object as the output data type, which can help to simplify a model.

For more information, see Data Types Supported by Simulink in the Simulink documentation.

Parameters

Main Tab

Specification

Specify whether to enter data as explicit breakpoints, as parameters that generate evenly spaced breakpoints, or via a breakpoint object. If you set this parameter to:

  • Explicit values, the Source and Value parameters are visible on the dialog box.

  • Even spacing, the First point, Spacing, and Number of points parameters are visible on the dialog box.

  • Breakpoint object, the Name parameter is visible on the dialog box.

Source

Specify whether to enter breakpoint data in the dialog box or to inherit the data from an input port. This parameter is available when Specification is set to Explicit values. If you set Source to:

  • Dialog, enter breakpoint data in the text box under Value.

  • Input port, verify that an upstream signal supplies breakpoint data to the bp input port. Each breakpoint data set must be a strictly monotonically increasing vector that contains two or more elements. For this option, your block inherits breakpoint attributes from the bp input port.

Value

If you set:

  • Specification to Explicit values and Source to Dialog, explicitly specify the breakpoint data. Each breakpoint data set must be a strictly monotonically increasing vector that contains two or more elements. For this option, you specify breakpoint attributes on the Data Types pane. This parameter is available when Source is set to Dialog.

  • Source to Input port, verify that an upstream signal supplies table data to the bp input port. Each breakpoint data set must be a strictly monotonically increasing vector that contains two or more elements. For this option, you specify breakpoint attributes on the Data Types pane. This parameter is available when Source is set to Dialog.

Click Edit to open the Lookup Table Editor (see Edit Lookup Tables in the Simulink documentation).

First point

Specify the first point in your evenly spaced breakpoint data. To enable this parameter, set Specification to Even spacing.

Spacing

Specify the spacing between points in your evenly spaced breakpoint data. To enable this parameter, set Specification to Even spacing.

Number of points

Specify the number of evenly spaced points in your breakpoint data. To enable this parameter, set Specification to Even spacing.

Name

If you set Specification to Breakpoint object, specify the name of an existing Simulink.Breakpoint object. An existing breakpoint object already contains breakpoint data.

Index search method

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

  • 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 values for u do not vary significantly between time steps, selecting Linear search with Begin index search using previous index result produces the best performance.

    • If input values for u 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.

Output selection

Specify the signals (index, fraction, or both) that the block outputs. If you want the block to output the index and interval fraction, you can have it output either individual signals or a bus signal that includes both the index and fraction signals.

  • Index only outputs just the index, without the fraction. Typical applications for this option include:

    • Feeding a Direct Lookup Table (n-D) block, with no interpolation on the interval

    • Feeding selection ports of a subtable selection for an Interpolation Using Prelookup block

    • Performing nonlinear quantizations

  • Index and fraction outputs the index and fraction as individual signals.

  • Index and fraction as bus outputs a bus signal that includes the index and fraction signals. Using a bus for these signals:

    • Simplifies the model by tying these two related signals together.

    • Creates a testpoint DpResult structure for the AUTOSAR 4.0 library.

    • For the AUTOSAR 4.0 library, avoids the creation of extra copies during code generation when the Prelookup and Interpolation Using Prelookup blocks are in separate models.

      Note:   Selecting Index and fraction as bus displays the Output parameter in the Data Types pane and sets the Output parameter to Inherit: auto. Change this default value to specify a user-defined bus object. For details about defining the bus object, see the Output parameter description.

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 input values of u 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.

Extrapolation method

Specify how to handle out-of-range values for the block input u. Options include:

  • Clip

    Block InputBlock Outputs

    Less than the first breakpoint

    • Index of the first breakpoint (for example, 0)

    • Interval fraction of 0

    Greater than the last breakpoint

    • Index of the next-to-last breakpoint

    • Interval fraction of 1

    Suppose the range is [1 2 3] and you select this option. If u is 0.5, the index is 0 and the interval fraction is 0. If u is 3.5, the index is 1 and the interval fraction is 1.

  • Linear

    Block Input Block Outputs

    Less than the first breakpoint

    • Index of the first breakpoint (for example, 0)

    • Interval fraction that represents the linear distance from u to the first breakpoint

    Greater than the last breakpoint

    • Index of the next-to-last breakpoint

    • Interval fraction that represents the linear distance from the next-to-last breakpoint to u

    Suppose the range is [1 2 3] and you select this option. If u is 0.5, the index is 0 and the interval fraction is -0.5. If u is 3.5, the index is 1 and the interval fraction is 1.5.

    Note:   The Prelookup block supports linear extrapolation only when all of these conditions apply:

    • The input u, breakpoint data, and fraction output use floating-point data types.

    • The index uses a built-in integer data type.

Use last breakpoint for input at or above upper limit

Specify how to index input values of u that are greater than or equal to the last breakpoint. The index value is zero-based. When input equals the last breakpoint, block outputs differ as follows:

Check BoxBlock Outputs

Selected

  • Index of the last element in the breakpoint data set

  • Interval fraction of 0

Cleared

  • Index of the next-to-last breakpoint

  • Interval fraction of 1

This check box is visible only when:

  • Output only the index is cleared.

  • Extrapolation method is Clip.

However, when Output only the index is selected and Extrapolation method is Clip, the block behaves as if this check box is selected even though it is invisible.

    Tip   When you select Use last breakpoint for input at or above upper limit for a Prelookup block, you must also select Valid index input may reach last index for the Interpolation Using Prelookup block to which it connects. This action allows the blocks to use the same indexing convention when accessing the last elements of their breakpoint and table data sets.

Diagnostic for out-of-range input

Specify whether to produce a warning or error when the input u 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 inputs.

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.

Sample time

Data Types Tab

    Note:   The parameters for breakpoint attributes (data type, minimum, and maximum) are not available when you set Source to Input port. In this case, the block inherits all breakpoint attributes from the bp input port.

Breakpoint > Data Type

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

  • A rule that inherits a data type, for example, Inherit: Same as 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 for more information.

    Tip   Specify a breakpoint data type different from the data type of input u for these cases:

    • Lower memory requirement for storing breakpoint data that uses a smaller type than the input signal u

    • Sharing of prescaled breakpoint data between two Prelookup blocks with different data types for input u

    • Sharing of custom storage breakpoint data in the generated code for blocks with different data types for input u

Breakpoint > Minimum

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

Breakpoint > Maximum

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

Index > Data Type

    Note:   This parameter displays only when you set Main Tab > Output selection to Index and fraction or Index only.

Specify a data type that can index all elements in the breakpoint data set. You can:

  • Select a built-in integer data type from the list.

  • Specify an integer data type using a fixed-point representation.

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

See Specify Data Types Using Data Type Assistant for more information.

Fraction > Data Type

    Note:   This parameter displays only when you set Main Tab > Output selection to Index and fraction.

Specify the data type of the interval fraction. You can:

  • Select a built-in data type from the list.

  • Specify data type inheritance through an internal rule.

  • Specify a fixed-point data type using the [Slope Bias] or binary-point-only scaling representation.

    • If you use the [Slope Bias] representation, the scaling must be trivial — that is, the slope is 1 and the bias is 0.

    • If you use the binary-point-only representation, the fixed power-of-two exponent must be less than or equal to zero.

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 for more information.

Output

    Note:   This parameter displays only when you set Main Tab > Output selection to Index and fraction as bus

Output a nonvirtual bus. Use the Bus: <object name> template to specify a bus object. Replace <object name> with the name of a bus object that contains the index and fraction signals.

  • The bus object must contain two elements. The first element corresponds to the index signal and the second to the fraction signal.

  • The index and fraction bus element signals cannot be bus signals.

  • The data type and the complexity of the bus elements must meet the same constraints that apply to the index and fraction signals if you set Output selection to Index and fraction.

To create the bus object with the index and fraction bus elements, use MATLAB code similar to this, customizing the bus object name and the names and data types of the bus elements.

% Bus object: kfBus 
elems(1) = Simulink.BusElement;
elems(1).Name = 'Index';
elems(1).DataType = 'int8';
 
elems(2) = Simulink.BusElement;
elems(2).Name = 'Fraction';
elems(2).DataType = 'double';
 
kfBus = Simulink.Bus;
kfBus.Elements = elems;
clear elems;

Alternatively, you can use the Bus Editor to create or modify the bus object to use with the Prelookup block.

If you feed the bus output signal from this block to an Interpolation Using Prelookup block, select the Require index and fraction as bus check box in that block.

    Note:   Using the Fixed-Point Tool data type override option overrides bus objects with new bus objects that replace fixed-point data types with floating-point data types.

    Overridden bus objects used with the Prelookup block can cause an error because the block does not accept floating-point data types for the first element in the bus.

    If you encounter this issue, using the Fix button redefines the original bus object to protect it from being overridden. For example, suppose you define the first element of the bus object to be an int32.

    myBus.Elements(1).DataType
    
    int32

    Clicking the Fix button redefines the first bus element to be:

    myBus.Elements(1).DataType = 'fixdt(''int32'',''DataTypeOverride'',''Off'')'
Lock output data type setting against changes by the fixed-point tools

Select to lock the output data type setting of this block against changes by the Fixed-Point Tool and the Fixed-Point Advisor. For more information, see Use Lock Output Data Type Setting.

Integer rounding mode

Specify the rounding mode for fixed-point operations. For more information, see Rounding in the Simulink Fixed Point™ documentation.

Block parameters always round to the nearest representable value. To control the rounding of a block parameter, enter an expression using a MATLAB rounding function into the mask field.

Examples

Prelookup with External Breakpoint Specification

In the following model, a Constant block feeds the breakpoint dataset to the bp input port of the Prelookup block.

The Prelookup block inherits the following breakpoint attributes from the bp input port:

Breakpoint AttributeValue
MinimumInf
MaximumInf
Data typesingle

Similarly, a Constant block feeds the table data values to the T input port of the Interpolation Using Prelookup block, which inherits the following table attributes:

Table AttributeValue
MinimumInf
MaximumInf
Data typesingle

Simulink uses double-precision, floating-point data to perform the computations in this model. However, the model stores the breakpoint and table data as single-precision, floating-point data. Using a lower-precision data type to store breakpoint and table data reduces the memory requirement.

Prelookup with Even Spaced Breakpoint Specification

In this model, you specify evenly spaced breakpoint data to the Prelookup block.

The Breakpoint Specification parameter is set to Even Spacing. The parameters First point, Spacing, and Number of points are set to 25, 12, and 4 respectively. Specifying these parameters creates four evenly spaced breakpoints: [25, 37, 49, 61].

Specifying even spacing is an alternative way to specify breakpoints that are evenly spaced. You can also set Breakpoint Specification to Explicit values and set Value to [25:12:61].

Simulink uses double-precision, floating-point data to perform the computations in this model. However, the model stores the breakpoints and table data as double.

For other examples, see Prelookup and Interpolation Blocks in the Simulink documentation.

Use a Bus for Index and Fraction

You can use a bus object to specify the index (k) and fraction (f) in the Prelookup block and then use that bus as input to an Interpolation Using Prelookup block. This example shows how to use a bus signal and how to get the same results without using a bus object.

Open the model and simulate it.

open_system(docpath(fullfile(docroot,'toolbox','simulink',...
'examples','ex_prelookup_bus.slx')))
sim('ex_prelookup_bus')

At the top of the model, open the Prelookup block parameters dialog box. In the Main tab, note that Output selection is set to Index and fraction as bus.

In the Data Types tab, note that Output is set to Bus: myBus.

In the Simulink Editor, select File > Model Properties and open the Callbacks tab. The code defines the bus object myBus, which specifies the index as the first bus element and the fraction as the second element.

In the Interpoloation Using Prelookup block parameters dialog box, in the Main tab, note that Require index and fraction as bus check box is selected. That option configures the block to use the bus output from the Prelookup block.

Characteristics

Data Types

Double | Single | Base Integer | Fixed-Point

Sample Time

Inherited from driving block

Direct Feedthrough

Yes

Multidimensional Signals

No

Variable-Size Signals

No

Zero-Crossing Detection

No

Code Generation

Yes

Introduced in R2006b

Was this topic helpful?