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. From the toolstrip of the Code Replacement tool, click New > Table.

  3. Create a code replacement entry. Shape-agnostic matrix replacement only supports Math Operation entries. Click New > Entry > Math Operation Entry. 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.

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

  6. Specify the Name for the replacement function as MyAdd_Matrix.

  7. Validate and save the table. Click the Mapping Information tab and verify the fields are filled in as shown. Click Apply, then click Validate entry. On the toolstrip, click Save and save the table.

Code replacement tool showing the entry for the Addition operation.

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.

Model with a Sum block, two 6 by 1 inputs, and one 6 by 1 output.

 /* 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.

See Also

Topics