Map Signal Data to Root Input Ports

After you import data, map signal data to root input ports by selecting map modes and options and selecting data.

For a summary of the other steps involved in using the Root Inport Mapper tool, see Import and Mapping Workflow.

Select Map Mode

To map signal data to root-level ports, use one of these map modes in the Map To Model section of the Root Inport Mapper toolstrip. The mapping mode you select from the toolstrip, such as Block Name or Port Order, is maintained between MATLAB^® sessions and models. You do not have to select the map mode each time you want to map signal data to root input ports.

Goal	Map Mode
Assign signals to ports according to the name of the root-inport block. If the name of a signal or bus element matches the name of a root-input port block, the data is mapped to the corresponding port.	Block Name
Assign signals to ports according to the block path of the root-input port block. If the block path of a signal matches the block path of a root-inport block, the data is mapped to the corresponding port.	Block Path
Assign signals to ports according to the name of the signal on the port. If the signal name of a data element matches the name of a signal at a port, the signal is mapped to the corresponding port.	Signal Name
Assign sequential port numbers to the imported data, starting at 1. Map signals to the corresponding input ports. If there is more data than input ports, the remaining data is mapped to enable and then trigger input ports. If the data is not in the form of a dataset, it is processed in the order in which it appears in the data file.	Port Order
Assign signals to ports according to the definitions in a custom file. To create a custom mapping mode, see Create and Use Custom Map Modes.	Custom

Set Options for Mapping

If you want to set up mapping options, in the Map To Model section on the Root Inport Mapper toolstrip, click Options. The option you select from the toolstrip, such as Update Model or Allow Partial, is maintained between MATLAB sessions and models. You do not have to select the option each time you want to map signal data to root inports.

To map the signals, see Map Data.

Goal	Option
Update the model and review the data types of root-level input ports and imported data.	Update Model. Compare the signal data and input port parameters to the root-level port and display the results. If you do not select this option, the tool maps the imported data to the root-level input port but does not update the model.
Use strong data typing when mapping data from spreadsheets.	Use Strong Data Typing with Spreadsheets. Clear this check box to allow the Root Inport Mapper tool to automatically convert spreadsheet input signals to the data types of the corresponding root inports. The Root Inport Mapper tool can cast the spreadsheet data to only these data types: `double`, `single`, `int8`, `uint8`, `int16`, `uint16`, `int32`, `uint32`. If you select this check box or if the root input port is not one of these data types, you may receive a data type mismatch error.
Import bus data that is only partially defined.	Allow partial. Confirm that any partially specified bus data you import maps properly to root-level input ports.
Identify unassigned root input ports and detect incomplete input data sets.	Notify of Missing Signals. Show inputs with missing signals.

Select Data to Map

To specify a subset of scenarios to map, click the down arrow on the Map to Model button. You can choose different mapping modes for different scenarios.

Goal	Option
Map all the scenario datasets (default).	Map All
Map the datasets of the scenarios currently selected in the Scenario Dataset section.	Map Selected
Map the disconnected datasets.	Map Unconnected
Map datasets that previously failed a mapping.	Map Failed
Map datasets that previously caused warnings.	Map Warned

Map Data

After you import signals or buses, you can map data.

On the Root Inport Mapper toolbar, click Map to Model.
The results of a signal mapping appear in the Scenario Dataset tab.
In the FILE section, click a data set to see the mapping results
- The Simulation Readiness section lists the input data and the status of the mapping.
  Note
  See Understand Mapping Results.
- The mapping definition for the input data is applied to the model.

After you save and close the model, when you load input data of the same scenario to the workspace, the model uses the mapping defined for that scenario.

For an example of mapping signal data to root-level inputs, see Converting Harness-Driven Models to Use Harness-Free External Inputs.

After you save the mapping definition for a model, you can automate data loading. For more information, see Alternative Workflows to Load Mapping Data.

Understand Mapping Results

When you complete the import and map process, the Simulation Readiness section displays the results in the status area. The results depend on whether you select the Update Model option when you set up the mapping.

Status Update Model Continue Without Update Model

Status	Update Model	Continue Without Update Model
	The properties of the mapped data and the input port are appropriate for simulation.	The data type, dimension, and signal type properties of the data and input port are compatible.
	Not applicable	Comparison of data and root-level port data type, dimension, and signal type properties cannot determine whether there is a match. If you do not update the model before mapping, the tool cannot evaluate whether all the data types match unless you explicitly specify the input port data types. Confirm that you set these block parameters correctly: Inport block parameter Data type is not set to `Inherit:auto`. Inport block parameter Dimension is not set to `-1`. Inport block parameter Signal type cannot be `auto`.
	The properties of the mapped data and the input port are not appropriate for simulation.	One or more of the data types, dimensions, or signal types of the signal data are not compatible with the root-level input port.

The properties of the mapped data and the input port are appropriate for simulation.

The data type, dimension, and signal type properties of the data and input port are compatible.

Not applicable

Comparison of data and root-level port data type, dimension, and signal type properties cannot determine whether there is a match. If you do not update the model before mapping, the tool cannot evaluate whether all the data types match unless you explicitly specify the input port data types. Confirm that you set these block parameters correctly:

Inport block parameter Data type is not set to Inherit:auto.

Inport block parameter Dimension is not set to -1.

Inport block parameter Signal type cannot be auto.

The properties of the mapped data and the input port are not appropriate for simulation.

One or more of the data types, dimensions, or signal types of the signal data are not compatible with the root-level input port.

To enable the model to simulate, if Root Inport Mapper does not find input port signals to map, it maps these input ports to ground and displays the mapped signal as empty ([]).

This figure shows mapping successes, failures, and ground assignments. If there are issues, the status column displays suggested resolutions. Read through and diagnose the issues.

Sometimes the Simulation Readiness section shows a warning or error, but your investigation of the elements indicates that there is no problem with mapping the data. In these cases, if you did not select the Update Model check box from the Options menu, select it and click Map to Model again.

In the Root Inport Mapper tool, clicking Mark for Simulation selects the Input check box in the Data Import/Export pane in the model Configuration Parameters dialog box. It also sets the value to the imported data variables. To apply the changes to the model configuration, in the Data Import/Export pane, click OK.

If your model uses configuration references to reference configuration sets, you cannot mark the model for simulation. To use this data to simulate the model with the Root Inport Mapper tool, use the Model Explorer to activate a configuration set first.

This graphic illustrates the application of the changes to the model configuration for the model in Map Data.

To inspect the imported data, you can:

Connect the output to a scope, simulate the model, and observe the data.
Log the signals and use the Simulation Data Inspector tool to observe the data.

To highlight the Inport block that is associated with the signal, select an item in the Simulation Readiness section. The selected Inport block is outlined with blue.

Note

When the input is a bus, click the levels of the bus object to see the individual elements in the bus.

Converting Harness-Driven Models to Use Harness-Free External Inputs

Open Model

This example shows how to convert a harness model that uses a Signal Builder block as an input to a harness-free model with root inports. The example collects data from the harness model and stores it in MAT-files for the harness-free model. After storing the data, the example removes the Signal Builder block from the harness model and adds root inports to create a harness-free model. Then, the data in the MAT-files is mapped to the root inports of the model.

Save Harness Data to MAT-Files

Before converting the model to be harness-free, collect the test cases in the harness.

For this example, you will modify the model sldemo_autotrans from the Modeling an Automatic Transmission Controller example.

Open the example model. In the MATLAB Command Window, type sldemo_autotrans.

Exporting Signal Builder Block Groups

Export data that defines Signal Builder block signal groups to a MAT-file from the Signal Builder window. To export Signal Builder signal data, formatted as Simulink.SimulationData.Dataset, to a MAT-file, open the Signal Builder window and select File > Export Data > To MAT-File. In the dialog, enter a name for the MAT-file to contain the data and the number of the group you want to export. For this example, the file name is slexAutotransRootInportPassingManeuver.mat and the group number is 1 for the Passing Maneuver group.

Remove the Signal Builder Block

Remove the Signal Builder block named ManeuversGUI and replace it with two inports.

Delete the Signal Builder block named ManeuversGUI.
From the Simulink/Commonly Used Blocks library, drag two inport blocks into the model.
Connect the input ports to the lines previously connected to the Signal Builder block.
Rename the inport ports. Name the input port connected to the Throttle line Throttle. Name the input port connected to the BrakeTorque line Brake.

Save the model as slexAutotransRootInportsExample1.slx or use the example slexAutotransRootInportsExample.slx.

The remaining steps of this example use the model slexAutotransRootInportsExample.slx. If you saved the model with a different name use your model name in the steps going forward.

Set Up Harness-Free Inputs

Now that the model is harness-free, set up the inputs that you already saved (See "Save Harness Data to MAT-Files").

In the Modeling tab, select Model Settings. In the Data Import/Export pane, click the Connect Input button.

Map Signals to Root Inport

The Root Inport Mapper tool opens.

The example uses this tool to set up the model inputs from the MAT-file and map those inputs to an input port, based on a mapping algorithm. To select the MAT-file that contains the input data, click the From MAT-File button on the Root Inport Mapper toolbar. When the link dialog appears, click the Browse button. In the browser, select the MAT-file that you saved earlier.

Select a Mapping Mode

When you select the MAT-file slexAutotransRootInportPassingManeuver.mat that contains the input data, determine the root input port to which to send input data. Simulink matches input data with input ports based on one of five 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.

Earlier in this example, you saved input data to variables of the same name as the harness signals Throttle and Brake, and added input ports with names matching the variables. Given the set of conditions for the input data and the model input ports, the best choice for a mapping criteria is Block Name. Using this criteria, Simulink tries try to match input data variable names to the names of the input ports. To select this option:

Click the Block Name radio button.
Click the Options button and select Update Model. This verifies the mapping.
Click the Map button.

When compiling the data, Simulink evaluates inports against the following criteria to determine compatibility issues. The status of this compatibility is reflected by the table colors green, orange, or red. Warnings and errors are flagged with diagnostic messages. If the Options > Update Model option is not selected, Root Inport Mapper determines the compatibility status by evaluating these block parameters and assigned signals:

Data Type - Double, single, enum, ....
Complexity - Real or complex
Dimensions - Signal dimensions vs port dimensions

Finalize the Inputs to the Model

Review the results of the mapping compatibility. Click the Scenario Dataset 'PassingManeuver' in the scenario dataset list. To prepare for simulation, click Mark for Simulation. This action applies the mapping variables to the Configuration Parameter Data Import/Export > External Input text box. If this text box has content, it is overwritten.

Simulating the Model

With the changes applied you can now simulate the model and view the results. Run the model. To view the results of the simulation, double-click the Scope Block PlotResults.

Alternative Workflows to Load Mapping Data

After you save the mapping definition to a model, you can automate data loading and simulation. Consider one of the following methods.

Command Line or Script

To load data and simulate the model from the MATLAB command line, use commands similar to:

load('signaldata.mat');
simout = sim('model_name');

To automate testing and load different signal groups, consider using a script.

The following example code creates timeseries data and simulates a model after loading each signal group. It:

Creates signal groups with variable names In1, In2, and In3, and saves these variables to MAT-files.
Simulates a model after loading each signal group.

Note

The variable names must match the import data variables in the Configuration Parameters > Data Import/Export > Input parameter.

% Create signal groups
fileName = 'testCase';
for k =1 :3
    
    % Create the timeseries data
    var1 = timeseries(rand(10,1));
    var2 = timeseries(rand(10,1));
    var3 = timeseries(rand(10,1));
    
    %create a dataset
    ds = Simulink.SimulationData.Dataset();
    ds = ds.addElement( var1, 'var1');
    ds = ds.addElement( var2, 'var2');
    ds = ds.addElement( var3, 'var3');
    
    % Save the data 
    save([fileName '_' num2str(k) '.mat' ],'ds');
end
clear all
 
% After mapping and saving the model loop over signal groups and simulate
% Set the filename to append testcase # to
fileName = 'testCase';
% Loop backwards to preallocate
for k=3:-1:1
   % Load the MAT-file.
   load([fileName '_' num2str(k) '.mat']);
   
   % Simulate the model
   simOut{k} = sim('model_name');
end

Use the PreLoadFcn Model Callback

When you are satisfied with the data and mapping, you can configure your model to load a MAT-file containing the signal group into the MATLAB workspace. Call the load function in the PreLoadFcn callback for the model.

After saving the MAT-file, on the Modeling tab, click the Model Settings drop-down and select Model Properties.
In the Model Properties window, select the Callbacks tab and then the PreLoadFcn node.
Enter a command to load the MAT-file containing the signal data. For example:
```
load d_signal_data.mat;
```
Click OK and save the model.

Documentation