Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Import and Map Root-Level Inport Data

To import and map signal and bus data to root-level inports at the same time, use the Root Inport Mapping dialog box. (You can open or use the Root Inport Mapping dialog box when the model is stopped. You cannot use it when the model is running or paused.) For alternative ways to import data, see Techniques for Importing Signal Data

    Note:   If data already exists in the MATLAB® workspace, you cannot map it to root-level inports using this dialog box. Use this dialog box to import the data, then map it, in one operation.

Map data to root-level inports using one of these methods:

  • Index — Assigns sequential index numbers, starting at 1, to the data in the MAT-file, and maps this data to the corresponding inport.

    • If there is more data than inports, the remaining data are mapped to enable and then trigger inports, in that order.

    • If the data is not in the form of a dataset, the data are processed in the order in which they are passed or parsed from the data file. This process is the order in which they appear in the file.

  • Signal Name — Assign data 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 data is mapped to the corresponding port.

  • Block Name — Assign data to ports according to the name of the root-inport block. If the block name of a data element matches the name of a root-inport block, the data is mapped to the corresponding port.

  • Block Path — Assign data to ports according to the block path of the root-inport block. If the block path of a data element matches the block path of a root-inport block, the data is mapped to the corresponding port.

  • MATLAB Function — Apply mappings according to the definitions in a custom file.

Importing and Mapping Workflow

  1. Identify the signals you want to import and map to the model root-level inports.

      Tip   Consider using a naming convention for signals and buses such that this grouping of data (signal group) is interchangeable. This convention allows you to quickly switch the groups of input data into and out of a model. For example, you can have two MAT-files whose data has different values but the same variable names.

  2. Create a MAT-file that contains the signal or bus data that you want to import into your model and map to the root-level inports of your model (see MAT-File for Import and Mapping).

  3. Determine how you want to map data (for example, by signal index or signal name), and perform the mapping.

To map data using one of the standard map formats, see:

To create a custom mapping file function to map data to root-level inports, see Create Custom Mapping File Function.

MAT-File for Import and Mapping

The Root Inport Mapping dialog box requires a MAT-file that contains data with one of these data types or formats.

Data FormatsIndex MappingSignal Name MappingBlock Name MappingBlock Path MappingCustom Mapping

Simulink.SimulationData.Dataset

timeseries (MATLAB and Simulink®)

(only for Simulink timeseries)

Simulink.SimulationData.Signal

Structure with Time, Structure without Time

    

TsArray

  

Data Array

    

Time Expression

    

Array of buses

 

Asynchronous function-call signals

 

For example, a signal data MAT-file with three signals (signal1, signal2, and signal3) with block path specified might have workspace variables as shown in this example. This file has signals that have signal names, block names, block paths, and index values. This means that you can map the data using Signal Name, Block Name, Block Path, or Index mapping mode. If there are corresponding root-level inports with corresponding indices, signal names, or block paths, the tool maps the signal to those ports.

signal1 = 

  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
         Name: 'signalGain5'
    BlockPath: [1x1 Simulink.SimulationData.BlockPath]
     PortType: 'outport'
    PortIndex: 1
       Values: [1x1 timeseries]

  Methods, Superclasses
>> signal2

signal2 = 

  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
         Name: 'signalGain10'
    BlockPath: [1x1 Simulink.SimulationData.BlockPath]
     PortType: 'outport'
    PortIndex: 1
       Values: [1x1 timeseries]

  Methods, Superclasses
>> signal3

signal3 = 

  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
         Name: 'signalGain15'
    BlockPath: [1x1 Simulink.SimulationData.BlockPath]
     PortType: 'outport'
    PortIndex: 1
       Values: [1x1 timeseries]

  Methods, Superclasses

Notes:

  • Only one Simulink.SimulationData.Dataset data set per MAT-file can load. If the MAT-file has multiple data sets of this type, the first data set listed alphabetically loads.

  • The number of signals with the formats structures, with and without time, data arrays, and time expressions must be the same as the number of model inports, enable ports, and trigger ports.

  • If you load a MAT-file that contains fixed-point data but you do not have a Fixed-Point Designer™ license, timeseries data is loaded and mapped, but model simulation will be inconsistent.

  • Data arrays are matrices. If you have a data array where the number of columns-1 is equal to the number of root-level inports (including trigger and enable ports), the Root Inport Mapping dialog box tries to map this data for the entire model. In this case, you can choose only the Index mapping method. If the number of columns-1 does not equal the number of root-level inports (including trigger and enable ports), the Root Inport Mapping dialog box tries to map the data array to a single inport. In this case, you can choose any of the mapping methods.

Import and Map Signal Data

Import Signal Data

  1. Before you start, create a MAT-file that contains the signal data you want to import and map.

  2. In the Simulink model you want to import the signal data to, open the Configuration Parameters dialog box.

  3. In the Data Import/Export pane, in the Load from workspace section, click Edit Input.

    The Root Inport Mapping dialog box appears.

  4. In the Signals section, click and select the MAT-file that contains the signal data, and then click Open.

To map the data, see Map Data.

Import and Map Bus Data

You can import and map bus data as well as signal data. This topic assumes that you are familiar with bus objects and how to create them. For more information on buses, see Bus Objects.

Set up to Import Bus Data

  1. In the MATLAB workspace, create a bus object for the bus data you want to import and map.

  2. Save the bus object definition to a MAT-file, for example, d_myBusObj.mat.

  3. Create a different MAT-file that contains the bus data you want to import for the bus object.

  4. Open a model you want to import the data to.

  5. In the Simulink Editor, select File > Model Properties > Model Properties.

    The Model Properties dialog box appears.

  6. In the Callbacks pane, enter a load function to load the bus object definition and click OK. The figure shows an example of loading a bus object from d_myBusObj.mat.

Continue to Import Bus Data.

Import Bus Data

If you have not yet set up to import bus data, see Set up to Import Bus Data.

  1. In the Simulink model you want to import the signal data to, open the Configuration Parameters dialog box.

  2. In the Data Import/Export pane, in the Load from workspace section, click Edit Input.

    The Root Inport Mapping dialog box appears.

  3. In the Signals section, click and select the MAT-file that contains the bus data, and then click Open.

To map the data, see Map Data.

Map Data

This topic assumes that you have already imported signal or bus data. If you have not yet done so:

  1. Select the mapping mode you want to use (for a description of the modes, see Import and Map Root-Level Inport Data), and then click Map Signals.

  2. If you are importing bus data, select the Allow partial specification of bus elements check box to import bus data that is only partially defined in the MAT-file. If you clear this check box and import partially specified bus data, the partially specified bus data cannot map properly to root-level inports.

  3. Respond to the prompt to complete the mapping.

    Select one of the following:

    • Compile — Maps the imported data to the root-level inport and compiles the model to check data types of root-level inports and imported data.

    • Continue without Compilation — Maps the imported data to the root-level inport but does not compile the model. When you select this option, the software compares the data and inport parameters to the root-level port and displays the results. See Understanding Mapping Results. If the comparison data is inherited from the connected block, you receive a warning.

    The results of a signal mapping are displayed in the Status area.

    The Status area of the tool lists the input data and the status of the mapping.

  4. To apply changes to the model, click Apply.

  5. Save and close the model.

    The mapping definition for the input data is saved to the model.

The next time you load input data of the same signal group into the workspace, simulating this model automatically uses the mapping definition.

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

Understanding Mapping Results

When you complete the import and map process, the Root Inport Mapping dialog box displays the results in the status area:

StatusCompileContinue Without Compile

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

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

N/A

Comparison of data and root-level port data type, dimension, and signal type properties unable to determine if there is a match. If you do not compile before mapping, the tool cannot evaluate whether all the data types match unless you explicitly specify the Inport data types. In other words:

  • Inport block parameter Data type cannot be Inherit:auto.

  • Inport block parameter Signal type cannot be -1.

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

One or more of the properties data type, dimensions, and signal type of the data and inport are not compatible.

In the Root Inport Mapping dialog box, click OK or Apply to select the Input check box in the Data Import/Export pane of the Configuration Parameters dialog box. This action 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 or Apply.

Root-level input ports that have not been mapped display as empty ([]).

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.

This graphic shows successes and failures:

If there are warnings or failures, the software highlights the Inport block associated with the data. Warnings display as yellow Inport blocks outlined in orange, failures display as yellow Inport blocks outlined with bold red, and successes display as normal Inport blocks outlined with blue. Selecting the line item highlights the associated Inport block. For example:

To investigate warnings and failures, click the line item you want to correct in the Status section of the Root Inport Mapping dialog box. The Comparison Tool is displayed with the columns in the left-right order of field name, input data, and root-level inport.

If you click a successful line item, the line turns blue and the Inport block is outlined in blue.

    Note:   When the input is a bus, click the levels of the bus object to drill down to the individual elements in the bus.

Use the Comparison Tool to evaluate your next action. For example, you can edit the data in the MAT-file or edit the root-level inport. When you are done, reimport the data again to map it.

    Tip   Each time you click a status item, a new Comparison Tool window appears. To dock all Comparison Tool windows in one window, click the Dock button . Click the Undock button to return to the default .

For more information on the Comparison Tool, see Comparing Files and Folders.

Convert Test Harness Model to Harness-Free Mode

  1. In the MATLAB Command Window, click the question mark.

    The Documentation Center window opens.

  2. Navigate to Simulink > Examples > Modeling Features > Modeling Concurrency > Converting Test Harness Model to Harness-Free Model.

Converting Test Harness Model to Harness-Free 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 use by 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, capture the test cases in the harness.

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

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

Use MATLAB function slexAutotransRootInportsSaveActiveGroupslexAutotransRootInportsSaveActiveGroup to save the Signal Builder block data of the active group into a MAT-file. At the command line type slexAutotransRootInportsSaveActiveGroup('slexAutotransRootInport','ManeuversGUI'). This function creates a MAT-file in the current directory with the same name as the active group. The function slexAutotransRootInportsSaveActiveGroupslexAutotransRootInportsSaveActiveGroup has been provided with this example.

Remove the Signal Builder Block

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

  1. Delete the Signal Builder block named ManeuversGUI.

  2. Open the Simulink Library Browser and select Commonly Used Blocks.

  3. Drag and drop two input ports from the Library Browser to the model.

  4. Connect the input ports to the lines previously connected to the Signal Builder block.

  5. 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").

From the Simulation->Model Configuration Parameters->Data Import/Export pane, click the Edit Input button.

Map Signals to Root Inport

The Root Inport Mapping tool opens.

This 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, navigate to the Signals panel and click the browse(...) MAT-file button. In the browser, select the MAT-file that you saved earlier.

Select a Mapping Mode

Once 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:

  • Index - 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 used the slexAutotransRootInportsSaveActiveGroup to save input data to variables of the same name as the harness signals Throttle and Brake, and you 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:

  1. Click the Block Name radio button.

  2. Click the Map Signals button.

The software prompts you to compile, continue without compiling, or cancel the mapping. Choose to compile the model to verify the mapping.

When compiling the data, Simulink evaluates inports against the following criteria to determine whether or not there is a compatibility issue. The status of this compatibility is reflected by the table colors green, orange, or red. Clicking a cell in the table which has orange or red color will open the Comparison Tool for further inspection.

  • Data Type - Double, single, enum, ....

  • Complexity - Real or complex

  • Dimensions - Signal dimensions vs port dimensions

Finalize the Inputs to the Model

After reviewing the results of the mapping compatibility, finalize the inputs to the model by clicking the Apply or OK button on the Root Inport Mapping tool. These buttons load the data that has been mapped to the input ports from the MAT-file to the base workspace. Simulink sets the Model Configuration Parameters->Data Import/Export->External Input edit box with the proper comma separated list of inputs. To apply the changes to the model, in the Configuration Parameters dialog, click Apply.

Simulating the Model

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

Alternative Workflows to Load Data

After saving the mapping definition to a model, you can automate data loading and/or 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 like:

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

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

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

  1. Creates signal groups with variable names In1, In2, and In3, and saves these variables to MAT-files.

  2. Simulates a model after loading each signal group.

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

% 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));
    
    % Save the data 
    save([fileName '_' num2str(k) '.mat' ],'var1','var2','var3');
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 Pane

If you are satisfied with the data and mapping, you can set up your model to automatically load a MAT-file of the same signal group by calling the load function in the model PreLoadFcn model property node.

  1. After saving the MAT-file, in the Simulink editor, select File > Model Properties > Model Properties.

  2. In the Model Properties window, select the PreLoadFcn node.

  3. Enter a load function to load the signal data MAT-file. For example,

    load d_signal_data.mat;
  4. Click OK and save the model.

Create Custom Mapping File Function

Create a custom mapping file function if you do not want to use the mapping modes in the Root Inport Mapping dialog box to map your data to root-level input ports. For example, consider creating a custom mapping file function if:

  • Your signal data contains a common prefix that is not in your model.

  • You want to explicitly map a signal.

The custom mapping file function is also useful if you want to map by block name, but the data contains a signal whose name does not match one of the block names.

See the following files in matlabroot\help\toolbox\simulink\example for examples:

  • BlockNameIgnorePrefixMap.m — Custom mapping file function that ignores the prefix of a signal name when importing

  • BlockNameIgnorePrefixData.mat — MAT-file of signal data to be imported

  • ex_BlockNameIgnorePrefixExample — Model file into which you can import and map data

Follow these general steps to create a custom mapping file function:

  1. Create a MATLAB function with the following input parameters:

    • Model name

    • Signal names specified as a cell array of strings

    • Signals specified as a cell array of signal data

  2. In the function, call the getRootInportMap function to create a variable that contains the mapping object (for an example, see BlockNameIgnorePrefixMap.m).

  3. Save and close the MATLAB function file.

  4. Add the path for the new function to the MATLAB path.

To use the custom mapping file function:

  1. Open the model you want to import data to (for example, ex_BlockNameIgnorePrefixExample).

  2. Open the Configuration Parameters dialog box for the model and select the Data Import/Export pane.

  3. In the Load from workspace section, click Edit Input.

    The Root Inport Mapping dialog box appears.

  4. In the Signals section, click and select the MAT-file that contains the signal data (for example, BlockNameIgnorePrefixData.mat).

  5. From the Mapping Mode list, click MATLAB Function.

  6. In the MATLAB Function parameter, select the MATLAB function file (for example, BlockNameIgnorePrefixMap.m) using the browser button.

      Tip   The Root Inport Mapping dialog box parses your custom code. Parsing reorders output alphabetically and verifies that data types are consistent.

  7. Click Apply, and click Compile in response to the message:

    The software compiles the model and updates the Root Inport Mapping dialog box.

  8. Click OK.

    To understand the mapping results, see Understanding Mapping Results.

  9. Save and close the model.

The next time you load input data of the same signal group into the workspace, simulating this model automatically uses the mapping definition.

For another example that shows how to create a custom mapping file function, from the Simulink landing page, click Examples > Modeling Features > Custom Mapping for External Inputs of a Model.

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

Custom Mapping Modes Similar to Simulink Modes

If you have a custom mapping mode that is similar to one of the Simulink mapping modes, you can use the getSlRootInportMap function in your custom mapping file function.

For an example of a custom mapping function that uses this function, from the Simulink Documentation Center main page, click Examples > Modeling Features > Using Simulink Mapping Modes in Custom Mapping Functions.

Command-Line Interface for Input Variables

Use the getInputString function to programmatically supply a set of input variables to the sim command or to a list of input variables that you can manually paste in the Configuration Parameters > Data Import/Export > Input parameter.

Was this topic helpful?