Attaching Input Data to External Inputs via Custom Input Mappings
This example shows how to create a custom mapping function for the Root Inport Mapper tool. The Root Inport Mapper tool associates MAT-file data with a specific input port, based on one of these criteria.
Port Order- Maps in the order it appears in the file to the corresponding port number.
Block Name- Maps by variable name to the corresponding root inport with the matching block name.
Signal Name- Maps by variable name to the corresponding root inport with the matching signal name.
Block Path- Maps by the BlockPath parameter to the corresponding root inport with the matching block path.
Custom- Maps using a MATLAB function.
Use a custom mapping criteria when the data you are trying to map does not match any of the other mapping criteria.
Custom Mapping Scenario
If the combination of input data and the model input ports does not match Port Order, Block Name, Signal Name, or Block Path mapping criteria, you can do one of the following:
Rename the input data in the MAT-file
Rename the input ports on the model
Use the custom mapping mode
This example shows how to write a custom mapping function.
The workflow described below includes
Create a MATLAB File to contain the custom mapping function
Declare the custom mapping function name, inputs, and outputs
Initialize the output for assignment of the return value
Define and implement your mapping algorithm
Validate your mapping algorithm
Create a New MATLAB Function File
Create a MATLAB function file. This file will contain your custom mapping function.
Declare Custom Mapping Function
Declare a custom mapping function name, and specify the inputs and outputs.slexCustomMappingMyCustomMapis the custom mapping function in this example. It declares the function inputs and outputs as defined below.
Inputs
modelName- String that contains the model name.
signalNames- Cell array of strings that contain variable names of signals to map
signals- Cell array of signal data aligned with signalNames such that signalNames{1} is the variable name of the signal stored in signals{1}.
Outputs
inputMap- Array or scalar of objects that result from the getRootInportMap function.
Initialize the Output
Initialize the value of the output variable inputMap. To do this use thegetRootInportMap
command with the empty property as shown in the example functionslexCustomMappingMyCustomMapor in the code snippet below. This initializes the output variable to empty so that a value can be assigned to the output.
inputMap = getRootInportMap('empty');
Define Your Custom Mapping Algorithm
Things to think about when defining your custom mapping algorithm.
What is the criteria for mapping signals to a root-level inport , for example BlockName mapping matches the name of the input signal to the name of the root-level inport block name.
What information is needed to create a mapping.
如果映射标准决定了that there is no match between signal and root-level inport.
The example addresses these items by
Using the root-level port number and signal name for mapping criteria.
Using a utility functionslexCustomMappingGetPortNamesto get root-level inport block names to provide as input along with the variable|signalName| to the
getRootInportMap
function which creates the mapping.
Including a logical condition to handle the case where there is no match between port number and signal name.
Implement Your Mapping Algorithm
Next, implement your mapping algorithm.
In theslexCustomMappingMyCustomMapimplementation, the root-level inport port number is the mapping criteria criteria. The algorithm gets this port number from the root-level inport block. It then gets the numerical values appended to the names of the signals that are passed into the function, and compares the port number with the numerical values.
NOTE: In addition to implementing your mapping algorithm, you should also include a logical statement to handle situations where a mapping is not possible. The example function does this by using anif
statement with theisempty
function to determine if a mapping can be made.
Create the Mapping
The final step is to use thegetRootInportMap
function to create a custom map. ThegetRootInportMap
function uses Property-Value pairs to create a custom map. The properties are:
model- String that represents the model name.
signalName- String or cell of strings that contains the value of the variable name of the signal to map.
blockName- String or cell of strings that contains the value of the block name of the port to be mapped.
The following code is an example of this function. This same code appears in the example functionslexCustomMappingMyCustomMap.
inputMap = getRootInportMap(...'model',modelName,...'signalName',signalNames,...'blockName',portNames);
Validate the Custom Mapping Function
To validate the custom mapping function at the command line:
Open the model against which you want to test your function.
Create some input signals to support the model.
Call your custom mapping function with the correct input parameters.
Validate the expected input string to send to the
sim
command, or to place in the model configuration parameters External Input String edit box.
执行以下示例中的代码行. This code uses the custom mapping function provided with this example. If the custom map function succeeds, you should see a comma-separated list of variable names displayed in the order of the port number to which they are assigned ('port1,port2'
).
load_system('slexAutotransRootInportsExample'); port1 = timeseries(ones(10,1)*10); port2 = timeseries(zeros(10,1)); inputMap = slexCustomMappingMyCustomMap('slexAutotransRootInportsExample',{'port1','port2'},{port1 , port2}); externalInputString = getInputString(inputMap,'base'); close_system('slexAutotransRootInportsExample',0);
If your signals are in a Simulink.SimulationData.Dataset, you can execute the lines of code in the following example. This code uses the custom mapping function provided with this example. If the custom mapping function succeeds, you should see a comma-separated list of variable names displayed in the order of the port number to which they are assigned ('ds.getElement(1),port1,ds.getElement(2)'
).
load_system('slexAutotransRootInportsExample'); ds = Simulink.SimulationData.Dataset; ds = ds.addElement( timeseries(ones(10,1)*10),'port1'); ds = ds.addElement( timeseries(zeros(10,1)),'port1'); inputMap = slexCustomMappingMyCustomMap('slexAutotransRootInportsExample',{'ds'},{ ds }); externalInputString = getInputString(inputMap,'base'); close_system('slexAutotransRootInportsExample',0);
See Also
getRootInportMap
|getSlRootInportMap
Related Examples
- Create and Use Custom Map Modes
- Create Harness-Free Models With MAT-File Input Data
- Map Data Using Root Inport Mapper Tool