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, see Nonlinearity.
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 – outputu1 –
indexu2 –
fractionu3 – table
datau4 – table dimension length |
y1 = interp2D(u1, u2, u3, u4, u5, u6, u7) | y1 – outputu1, u3 –
indexu2, u4 –
fractionu5 – table
datau6, u7 – table dimension lengths |
y1 = interp3D(u1, u2, u3, u4, u5, u6, u7, u8, u9,
u10) | y1 – outputu1, u3, u5 –
indexu2, u4, u6 –
fractionu7 – table
datau8, u9, u10 – table dimension
lengths |
y1 = interp4D(u1, u2, u3, u4, u5, u6, u7, u8, u9, u10, u11, u12,
u13) | y1 – outputu1, u3, u5,
u7 – indexu2, u4, u6, u8 –
fractionu9 – table
datau10, 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 – outputu1, u3, u5, u7,
u9 – indexu2, u4, u6, u8, u10 –
fractionu11 – table
datau12, u13, u14, u15, u16 – table dimension
lengths |
y1 = interpND({u | y1 –
outputu ,
u is an index and fraction pair
per dimension u –
table datau – table
dimension lengths |
Explicit values | y1 – outputu1 –
inputu2 – breakpoint
datau3 – table
datau4 – table dimension length |
Even spacing | y1 – outputu1 –
inputu2 – first point of breakpoint
datau3 – spacing of
breakpointsu4 – table
datau5 – table dimension length |
Explicit values | y1 – outputu1, u2 –
inputu3, u4 – breakpoint
datau5 – table
datau6, u7 – table dimension lengths |
Even spacing | y1 – outputu1, u2 –
inputu3, u5 – first point of breakpoint
datau4, u6 – spacing of
breakpointsu7 – table
datau8, u9 – table dimension lengths |
Explicit spacing | y1 – outputu1, u2, u3 –
inputu4, u5, u6 – breakpoint
datau7 – table
datau8, u9, u10 – table dimension
lengths |
Even spacing | y1 – outputu1, u2, u3 –
inputu4, u6, u8 – first point of breakpoint
datau5, u7, u9 – spacing of
breakpointsu10 – table
datau11, u12, u13 – table dimension
lengths |
Explicit values | y1 – outputu1, u2, u3,
u4 – inputu5, u6, u7, u8 –
breakpoint datau9 – table
datau10, u11, u12, u13 – table dimension
lengths |
Even spacing | y1 – outputu1, u2, u3,
u4 – inputu5, u7, u9, u11 – first
point of breakpoint data u6, u8, u10, u12 –
spacing of breakpointsu13 – table
datau14, u15, u16, u17 – table dimension
lengths |
Explicit values | y1 – outputu1, u2, u3, u4,
u5 – inputu6, u7, u8, u9, u10 –
breakpoint datau11 – table
datau12, u13, u14, u15, u16 – table dimension
lengths |
Even spacing | y1 – outputu1, u2, u3, u4,
u5 – inputu6, u8, u10, u12, u14 –
first point of breakpoint datau7, u9, u11, u13,
u15 – spacing of breakpointsu16 –
table datau17, u18, u19, u20, u21 – table
dimension lengths |
Explicit values | y1 –
outputu , input
per dimensionu ,
breakpoint per
dimensionu –
table datau – table
dimension lengths |
Even spacing | y1 –
outputu – input
per dimensionu –
first point of breakpoint data per
dimensionu –
spacing of breakpoint per
dimensionu –
table datau – table
dimension lengths |
y1 = lookupND_Direct(u1, u2,...ui, ui+1) | y1 – outputu1...ui –
inputui+1 – table data |
Explicit values | y1 – indexy2 –
fractionu1 –
inputu2 – breakpoint
datau3 – number of breakpoints |
Evenly spaced | y1 – indexy2 –
fractionu1 –
inputu2 – first point of breakpoint
datau3 – spacing of
breakpointsu4 – number of breakpoints |
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.
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:
>>crtool
Create a table.
From the crtool context menu, select File > New Table.
In the right pane, name the table crl_LUT
. Click
Apply.
Create an entry. From the crtool context menu, select File > New entry > Function.
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 the
algorithm parameters as shown in the crtool snapshot below.
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, specify the return argument,
y1
, and the input argument u1
with the
Data Type of double
and
u4
, with the Data Type of
uint32
and the Argument Type of
Scalar
.
Specify the Argument Type of input arguments
u2
and u3
as Matrix
and
Data Type as double
. Set the
Algorithm parameters as shown in the figure below.
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, select the Make conceptual and implementation argument types the same check box.
Add the return argument y1
and the arguments u1, u2,
u3
and u4
.
Specify a Name for the replacement function under Function prototype.
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. Click Validate entry. In the crtool context menu, select File > Save table > Save.
Register a code replacement library. Registration creates a library composed of the tables that you specify. Select File > Generate registration file. In the Generate registration file dialog box, fill out these fields:
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.
Open the programmatic interface from the MATLAB menu by selecting New > Function.
Create a table.
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.
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);
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'; 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);
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.
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
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
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.
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('rtwbuild(bdroot)');
View the generated code. Here is a portion of crl_LUTfunction.c
.
cfile = fullfile('crl_LUTfunction_ert_rtw','crl_LUTfunction.c'); rtwdemodbtype(cfile,'/* Model step function ','/* Model initialize function',1, 1);
/* Model step function */ void crl_LUTfunction_step(void) { int32_T iU; /* Lookup_n-D: '<Root>/1-D Lookup Table2' incorporates: * Constant: '<Root>/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: '<Root>/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'); rtwdemoclean;