Allow Shape Agnostic Match

Code replacement shape-agnostic match allows matrix inputs for certain operations to be matched based on the number of elements as opposed to matrix shape. For example, a 6x1 matrix matches a 2x3 matrix in shape-agnostic match because both have a total of 6 elements. Such matches can only be made if the output and inputs are contiguously allocated in memory and if the replacement function can be performed element-wise. Shape-agnostic matrix match increases replacement rate so it is advantageous for replacement that does not require matrix shape to be considered.

Shape-agnostic code replacement entries can be created either with the user interface of the Code Replacement Tool or programmatically.

User Interface Method- Code Replacement Tool

This example shows how to set up shape-agnostic matrix replacement for an addition code replacement table entry.

1. Open the Code Replacement Tool. From the MATLAB^® command line, enter crtool.

2. Create a code replacement table. Go to File > New Table.

3. Create a table entry. Shape-agnostic matrix replacement only supports Math Operation table entries. Either right-click on your table or go to File > New Entry and select Math Operation. Mapping information appears. From the Operation drop down menu, select addition.

4. Create conceptual arguments. The Conceptual operation section defines each of your conceptual arguments. To enable shape-agnostic replacement set the Argument type: to matrix to open the Matrix entry properties menu.

5. Set entry parameters. In the Matrix entry properties menu, select the Allow shape-agnostic match checkbox to enable shape-agnostic replacement.

6. Validate your table entry. Either click the validate entry button or right-click the entry and select Validate entries.

7. Click save.

   This display shows the Code Replacement Tool settings for this example.

Programmatic Method

This example shows how to set up a shape-agnostic matrix replacement for an addition code replacement table entry.

1. Create the code replacement table. Create a function definition with the table name 'ShapeAgnosticTable'. Call RTW.TflTable to create the table.

   function hLib = ShapeAgnosticTable
   hLib = RTW.TflTable;
   

2. Create a table entry for code replacement. Shape-agnostic replacement only supports operation entries, as specified with a call to RTW.TflCOperationEntry.

   hEnt = RTW.TflCOperationEntry;
   

3. Set entry parameters to customize input processing. You can enable shape-agostic matrix replacement by setting the entry parameter 'AllowShapeAgnosticMatch' to true.

   hEnt.setTflCOperationEntryParameters( ...
             'Key', 'RTW_OP_ADD', ...
             'Priority', 100, ...
             'AllowShapeAgnosticMatch', true, ...
             'ImplementationName', 'MyAdd_Matrix', ...
             'SideEffects', true);

4. Create conceptual arguments. For this example, create conceptual arguments y1, u1, and u2 with calls to the create function, RTW.TflArgMatrix, and add function, addConceptualArg.

   arg = RTW.TflArgMatrix('y1', 'RTW_IO_OUTPUT',  'double');
   arg.DimRange = [2 2; 50 50];
   hEnt.addConceptualArg(arg);
   
   arg = RTW.TflArgMatrix('u1', 'RTW_IO_INPUT',  'double');
   arg.DimRange = [2 3; 2 3];
   hEnt.addConceptualArg(arg);
   
   arg = RTW.TflArgMatrix('u2', 'RTW_IO_INPUT',  'double');
   arg.DimRange = [2 3; 2 3];
   hEnt.addConceptualArg(arg);

5. Create implementation arguments. For this example, call the function getTflArgFromString to create the arguments. Define the implementation return argument as a void output argument. Define the conceptual output argument, y1, as a pointer with the IOType as output.

   arg = hEnt.getTflArgFromString('unused','void');
   arg.IOType = 'RTW_IO_OUTPUT';
   hEnt.Implementation.setReturn(arg); 
   
   arg = hEnt.getTflArgFromString('u1','double*');
   hEnt.Implementation.addArgument(arg);
   
   arg = hEnt.getTflArgFromString('u2','double*');
   hEnt.Implementation.addArgument(arg);
   
   arg = hEnt.getTflArgFromString('y1','double*');
   arg.IOType = 'RTW_IO_OUTPUT';
   hEnt.Implementation.addArgument(arg);
   
   arg = hEnt.getTflArgFromString('numElements','uint32',6);
   hEnt.Implementation.addArgument(arg);
   

6. Add this entry to a code replacement table with the function addEntry.

   hLib.addEntry( hEnt ); 
   

7. Save the table as its function name. For this example, ShapeAgnosticTable.

8. Validate your entry at the MATLAB command line. Invoke the table definition file with the following command.

   hTbl = ShapeAgnosticTable
   

Example Model

An example of this code replacement table entry is demonstrated through the following model. Even though the matrix shape in this model does not match the entry, the operation can be performed element-wise and the entry enables shape-agnostic match, so code replacement is observed in the generated code.

 /* Outport: '<Root>/Out1' incorporates:
   *  Inport: '<Root>/In1'
   *  Inport: '<Root>/In2'
   *  Sum: '<Root>/Add'
   */
  MyAdd_Matrix(Demo_U.In1, Demo_U.In2, Demo_Y.Out1, 6U);

Limitations

• If you enable shape-agnostic match for an operation that is inherently not computed element-wise, a regular match is performed.

• When shape-agnostic match is enabled, code replacement does not honor the setting for 'DimRange'. Instead, it computes the number of elements and uses that value to match.

• If you are working with customized code replacement entries, adjust the 'do_match' function to accept the total number of elements as opposed to matrix dimensions. For more information, see Customize Match and Replacement Process.