Lookup Table Function Code Replacement - MATLAB & Simulink (original) (raw)

You can configure the algorithm for table lookup operations and index searches and generate code. If the code generated for available algorithm options does not meet requirements for your application, create custom code replacement table entries to replace the generated algorithm code. You can develop a code replacement library to optimize the performance of algorithms in a lookup table block. For more information, see Develop a Code Replacement Library. For more information about using lookup table blocks, seeNonlinearity.

Lookup Table Function Signatures

To create code replacement table entries for a function corresponding to a lookup table algorithm, you must have:

Information about the conceptual function signature.
Relevant algorithm parameters.

This table provides the conceptual function signature information.

Conceptual Function Signature	Argument Summary
y1 = interp1D(u1, u2, u3, u4)	y1 – output u1 – index u2 – fraction u3 – table data u4 – table dimension length
y1 = interp2D(u1, u2, u3, u4, u5, u6, u7)	y1 – output u1, u3 – index u2, u4 – fraction u5 – table data u6, u7 – table dimension lengths
y1 = interp3D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10)	y1 – output u1, u3, u5 – index u2, u4, u6 – fraction u7 – table data u8, u9, u10 – table dimension lengths
y1 = interp4D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13)	y1 – output u1, u3, u5, u7 – index u2, u4, u6, u8 – fraction u9 – table data u10, u11, u12, u13 – table dimension lengths
y1 = interp5D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13, u14, u15, u16)	y1 – output u1, u3, u5, u7, u9 – index u2, u4, u6, u8, u10 – fraction u11 – table data u12, u13, u14, u15, u16 – table dimension lengths
y1 = interpND({u_i_, u_f_,}... u_t_, u_n_...)	y1 – output u_i_,u_f_ is an index and fraction pair per dimension u_t_ – table data u_n_ – table dimension lengths
Explicit values y1 = lookup1D(u1, u2, u3, u4)	y1 – output u1 – input u2 – breakpoint data u3 – table data u4 – table dimension length
Even spacing y1 = lookup1D(u1, u2, u3, u4, u5)	y1 – output u1 – input u2 – first point of breakpoint data u3 – spacing of breakpoints u4 – table data u5 – table dimension length
Explicit values y1 = lookup2D(u1, u2, u3, u4, u5, u6, u7)	y1 – output u1, u2 – input u3, u4 – breakpoint data u5 – table data u6, u7 – table dimension lengths
Even spacing y1 = lookup2D(u1, u2, u3, u4, u5, u6, u7, u8, u9)	y1 – output u1, u2 – input u3, u5 – first point of breakpoint data u4, u6 – spacing of breakpoints u7 – table data u8, u9 – table dimension lengths
Explicit spacing y1 = lookup3D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10)	y1 – output u1, u2, u3 – input u4, u5, u6 – breakpoint data u7 – table data u8, u9, u10 – table dimension lengths
Even spacing y1 = lookup3D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13)	y1 – output u1, u2, u3 – input u4, u6, u8 – first point of breakpoint data u5, u7, u9 – spacing of breakpoints u10 – table data u11, u12, u13 – table dimension lengths
Explicit values y1 = lookup4D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13)	y1 – output u1, u2, u3, u4 – input u5, u6, u7, u8 – breakpoint data u9 – table data u10, u11, u12, u13 – table dimension lengths
Even spacing y1 = lookup4D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13, u14, u15, u16, u17)	y1 – output u1, u2, u3, u4 – input u5, u7, u9, u11 – first point of breakpoint data u6, u8, u10, u12 – spacing of breakpoints u13 – table data u14, u15, u16, u17 – table dimension lengths
Explicit values y1 = lookup5D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13, u14, u15, u16)	y1 – output u1, u2, u3, u4, u5 – input u6, u7, u8, u9, u10 – breakpoint data u11 – table data u12, u13, u14, u15, u16 – table dimension lengths
Even spacing y1 = lookup5D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12, u13, u14, u15, u16, u17, u18, u19, u20, u21)	y1 – output u1, u2, u3, u4, u5 – input u6, u8, u10, u12, u14 – first point of breakpoint data u7, u9, u11, u13, u15 – spacing of breakpoints u16 – table data u17, u18, u19, u20, u21 – table dimension lengths
Explicit values y1 = lookupND(u_n_,..., u_b_,..., u_t_, u_n_...)	y1 – output u_n_, input per dimension u_b_, breakpoint per dimension u_t_ – table data u_n_ – table dimension lengths
Even spacing y1 = lookupND(u_n_,..., {u_fn_, u_sn,}... u_t, u_n_...)	y1 – output u_n_ – input per dimension u_fn_ – first point of breakpoint data per dimension u_sn_ – spacing of breakpoint per dimension u_t_ – table data u_n_ – table dimension lengths
y1 = lookupND_Direct(u1, u2,...ui, ui+1)	y1 – output u1...ui – input ui+1 – table data
Explicit values y1, y2 = prelookup(u1, u2, u3)	y1 – index y2 – fraction u1 – input u2 – breakpoint data u3 – number of breakpoints
Evenly spaced y1, y2 = prelookup(u1, u2, u3, u4)	y1 – index y2 – fraction u1 – input u2 – first point of breakpoint data u3 – spacing of breakpoints u4 – number of breakpoints

For the table and breakpoint data, the conceptual function uses matrix arguments by default. If the lookup table object has the parameter Allow multiple instances of this type to have different table and breakpoint sizes enabled, the conceptual function uses pointer arguments for the table and breakpoint data. To replace a lookup table function that uses pointer arguments, you must create the entry programmatically.

When defining a table entry programmatically, you might also need to change the values of required (primary) and optional algorithm parameters.

Set values for required parameters to achieve code replacement.
If you do not set a value for an optional parameter, the algorithm parameter software applies don't care. The code replacement software ignores the parameter while searching for matches.

Interactively Develop a Code Replacement Library

This example shows how to specify a code replacement table entry for a lookup table algorithm interp1D by using the Code Replacement Tool.

Open the Code Replacement Tool (crtool), from the MATLAB command line with the following command:
Create a table.
1. From the toolstrip of the Code Replacement tool, click > .
2. In the right pane, name the table crl_LUT. ClickApply.
Create an entry. Click > > .
Create entry parameters. In the Function drop-down list, select Custom. Function information appears in the crtool. For this example, specify the parameter as lookup1D. Set these algorithm parameters as shown in the crtool snapshot below:
- Extrapolation method — Linear
- Interpolation method — Linear point-slope
- Integer rounding mode — Round
- Saturate on overflow — off
- Index search method — Linear search
- Remove out-of-range input protection — off
- Support tunable table size — off
- Use last table value for inputs at or above last breakpoint — off
- Begin index search using previous index result — off
- Use algorithms optimized for row-major array layout — off
Create the conceptual representation. The conceptual representation describes the signature of the function that you want to replace. In the Conceptual function subsection of the crtool, add these arguments and specify these properties:
- y1 — Data Type ofdouble and Argument Type ofScalar
- u1 — Data Type ofdouble and Argument Type ofScalar
- u2 — Data Type ofdouble and Argument Type ofMatrix
- u3 — Data Type ofdouble and Argument Type ofMatrix
- u4 — Data Type ofuint32 and Argument Type ofScalar
Create the implementation representation. The implementation representation describes the signature of the optimization function. For this example, to specify that the implementation arguments have the same order and properties as the conceptual arguments, add the return argument y1 and the arguments u1, u2, u3 and u4. Select theMake conceptual and implementation argument types the same check box.
Specify the Name for the replacement function asmy_Lookup1D_Repl.
Specify build information. Click the Build Information tab to open the build requirements pane. Specify the files (source, header, object) that the code generator requires for code replacement. For this example, you do not need to specify build information.
Validate and save the table. Click the Mapping Information tab and verify the fields are filled in as shown. ClickApply, then click Validate entry. On the toolstrip, click Save and save the table.
Register a code replacement library. Registration creates a library composed of the tables that you specify. Click Generate Registration File. In the Generate registration file dialog box, fill in these fields:
- Registry name — CRL for LUT-1D
- Table list — crl_LUT
- Base CRL — None
- Target HW device — *
- Description — Example code replacement library
  
  Click OK. To use your code replacement library, refresh your current MATLAB session with the command:
  
  sl_refresh_customizations
Verify the code replacement library. From the MATLAB command line, open the library by using the Code Replacement Viewer and verify that the table and entry are correctly specified. For more information, see Verify Code Replacement Library. Configure your model to use the code replacement library, generate code, and verify that replacement occurs as expected. If unexpected behavior occurs, examine the hit and miss logs to troubleshoot the issues.

Programmatically develop a code replacement library

Open the programmatic interface from the MATLAB menu by selecting New > Function.
Create a table.
1. Create a function with the name of your code replacement library table that does not have arguments and returns a table object. You can use this function to call your code replacement library table.
2. Create a table object by calling RTW.TflTable.
  function hTable = my_lookup_replacement_table
  % Create a function to call the code replacement library table
  %% Create a table object
  hTable = RTW.TflTable;
Create an entry. Because this example replaces a function, create a code replacement entry in your table by calling the entry function RTW.TflCFunctionEntry.
function hTable = my_lookup_replacement_table
% Create a code replacement library table
%% Create a table object
hTable = RTW.TflTable;
%% Create an entry
hEntry = RTW.TflCFunctionEntry;
Create entry parameters. Because this examples replaces a function, create entry parameters by calling the function setTflCFunctionEntryParameters.
function hTable = my_lookup_replacement_table()
% Create a code replacement library table
%% Create a table object
hTable = RTW.TflTable;
%% Create an entry
hEntry = RTW.TflCFunctionEntry;
%% Create entry parameters
setTflCFunctionEntryParameters(hEntry, ...
'Key', 'lookup1D', ...
'Priority', 100, ...
'ImplementationName', 'my_Lookup1D_Repl', ...
'ImplementationHeaderFile', 'myLookup1D.h', ...
'ImplementationSourceFile', 'myLookup1D.c', ...
'GenCallback', 'RTW.copyFileToBuildDir');
Create the conceptual representation. The conceptual representation describes the signature of the function that you want to replace. To explicitly specify argument properties, call the function getTflArgFromString.
function hTable = my_lookup_replacement_table()
% Create a code replacement library table
%% Create a table object
hTable = RTW.TflTable;
%% Create an entry
hEntry = RTW.TflCFunctionEntry;
%% Create entry parameters
setTflCFunctionEntryParameters(hEntry, ...
'Key', 'lookup1D', ...
'Priority', 100, ...
'ImplementationName', 'my_Lookup1D_Repl', ...
'ImplementationHeaderFile', 'myLookup1D.h', ...
'ImplementationSourceFile', 'myLookup1D.c', ...
'GenCallback', 'RTW.copyFileToBuildDir');

%% Create the conceptual representation
arg = hEntry.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEntry, arg);
arg = hEntry.getTflArgFromString('u1','double');
addConceptualArg(hEntry, arg);
arg = RTW.TflArgMatrix('u2', 'RTW_IO_INPUT', 'double');
arg.DimRange = [0 0; Inf Inf];
addConceptualArg(hEntry, arg);
arg = RTW.TflArgMatrix('u3', 'RTW_IO_INPUT', 'double');
arg.DimRange = [0 0; Inf Inf];
addConceptualArg(hEntry, arg);
arg = hEntry.getTflArgFromString('u4','uint32');
addConceptualArg(hEntry, arg); 6. Create the implementation representation. The implementation representation describes the signature of the optimization function. To specify that the implementation arguments have the same order and properties as the conceptual arguments, call the function getTflArgFromString.
function hTable = my_lookup_replacement_table()
% Create a code replacement library table
%% Create a table object
hTable = RTW.TflTable;
%% Create an entry
hEntry = RTW.TflCFunctionEntry;
%% Create entry parameters
setTflCFunctionEntryParameters(hEntry, ...
'Key', 'lookup1D', ...
'Priority', 100, ...
'ImplementationName', 'my_Lookup1D_Repl', ...
'ImplementationHeaderFile', 'myLookup1D.h', ...
'ImplementationSourceFile', 'myLookup1D.c', ...
'GenCallback', 'RTW.copyFileToBuildDir');
%% Create the conceptual representation
arg = hEntry.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
addConceptualArg(hEntry, arg);
arg = hEntry.getTflArgFromString('u1','double');
addConceptualArg(hEntry, arg);
arg = RTW.TflArgMatrix('u2', 'RTW_IO_INPUT', 'double');
arg.DimRange = [0 0; Inf Inf];
addConceptualArg(hEntry, arg);
arg = RTW.TflArgMatrix('u3', 'RTW_IO_INPUT', 'double');
arg.DimRange = [0 0; Inf Inf];
addConceptualArg(hEntry, arg);
arg = hEntry.getTflArgFromString('u4','uint32');
addConceptualArg(hEntry, arg);
algParams = getAlgorithmParameters(hEntry);
algParams.InterpMethod = 'Linear';
algParams.ExtrapMethod = 'Clip';
algParams.UseRowMajorAlgorithm = 'off';
algParams.RndMeth = 'Round';
algParams.IndexSearchMethod = 'Linear search';
algParams.UseLastTableValue = 'off';
algParams.RemoveProtectionInput = 'off';
algParams.SaturateOnIntegerOverflow = 'off';
algParams.SupportTunableTableSize = 'off';
algParams.BPPower2Spacing = 'off';
algParams.BeginIndexSearchUsingPreviousIndexResult = 'off';
setAlgorithmParameters(hEntry, algParams);
%% Create the Implementation Representation
arg = hEntry.getTflArgFromString('y1','double');
arg.IOType = 'RTW_IO_OUTPUT';
hEntry.Implementation.setReturn(arg);
arg = hEntry.getTflArgFromString('u1','double');
hEntry.Implementation.addArgument(arg);
arg = hEntry.getTflArgFromString('u2','double*');
hEntry.Implementation.addArgument(arg);
arg = hEntry.getTflArgFromString('u3','double*');
hEntry.Implementation.addArgument(arg);
arg = hEntry.getTflArgFromString('u4','uint32');
hEntry.Implementation.addArgument(arg);
%% Add the entry to the table
hTable.addEntry(hEntry); 7. Specify build information. In the entry parameters, specify files (header, source, object) that the code generator needs for code replacement. For this example, build information is not required. 8. Validate and save the customization file. From the MATLAB menu, save this customization file by selecting File >Save. From the command line, validate the code replacement library table by calling it:

hTable = my_lookup_replacement_table 9. Register the code replacement library. Registration creates a code replacement library by defining the library name, code replacement tables, and other information. Create a registration file (a new function file) with these specifications:
function rtwTargetInfo(cm)

cm.registerTargetInfo(@loc_register_crl);
end

function this = loc_register_crl

this(1) = RTW.TflRegistry;
this(1).Name = 'CRL for LUT 1D function replacement';
this(1).TableList = {'my_lookup_replacement_table.m'}; % table created in this example
this(1).TargetHWDeviceType = {'*'};
this(1).Description = 'Example code replacement library';
end
To use your code replacement library, refresh your current MATLAB session with the command:

sl_refresh_customizations 10. Verify the code replacement library. From the MATLAB command line, open the library by using the Code Replacement Viewer and verify that the table and entry are correctly specified. For more information, see Verify Code Replacement Library. Configure your model to use the code replacement library, generate code, and verify that replacement occurs as expected. If unexpected behavior occurs, examine the hit and miss logs to troubleshoot the issues.

Generate Code by Using Lookup Table Code Replacement Library

In this section, you generate code using the code replacement library that you created in the first two sections of this example. A Lookup table function is replaced with a call to a custom function in the generated code. This example does not provide an implementation function. Write your own implementation.

Example Model

Open the model crl_LUTfunction for configuring the code replacement library.

open_system('crl_LUTfunction');

copyfile LutFnRtwTargetInfo.txt rtwTargetInfo.m

Run the MATLAB customization file to create a code replacement table and register the file. The customization file has already been executed. Run the sl_refresh_customizations function to load the library.

sl_refresh_customizations;

Enable Code Replacement Library

Open the Configuration Parameters dialog box.
On the Interface pane, set Code Replacement Library by clicking Select and adding CRL for LUT function replacement to the Selected code replacement libraries - prioritized list pane.

% % Alternatively, use the command-line API to enable the code replacement: set_param('crl_LUTfunction', 'CodeReplacementLibrary', 'CRL for LUT function replacement');

Generate code from the model:

evalc('slbuild(bdroot)');

View the generated code. Here is a portion of crl_LUTfunction.c.

cfile = fullfile('crl_LUTfunction_ert_rtw','crl_LUTfunction.c'); coder.example.extractLines(cfile,'/* Model step function ','/* Model initialize function',1, 1);

/* Model step function */ void crl_LUTfunction_step(void) { int32_T iU;

/* Lookup_n-D: '/1-D Lookup Table2' incorporates:

Constant: '/Constant2' */ for (iU = 0; iU < 9; iU++) { crl_LUTfunction_Y.Y1[iU] = my_Lookup1D_Repl (crl_LUTfunction_ConstP.Constant2_Value[iU], &crl_LUTfunction_ConstP.uDLookupTable2_bp01Data[0], &crl_LUTfunction_ConstP.uDLookupTable2_tableData[0], 10U); }

/* End of Lookup_n-D: '/1-D Lookup Table2' */ }

The Lookup Table function is replaced with a custom my_Lookup1D_Repl function.

Close the model and code generation report.

delete ./rtwTargetInfo.m bdclose('crl_LUTfunction');

Lookup Table Function Code Replacement - MATLAB & Simulink (original) (raw)

Lookup Table Function Signatures

Interactively Develop a Code Replacement Library

Programmatically develop a code replacement library

Generate Code by Using Lookup Table Code Replacement Library

See Also

Topics