loadVariablesFromExternalSource - Load variables from a custom file into Simulink.SimulationInput

  object - MATLAB ([original](https://www.mathworks.com/help/simulink/slref/simulink.simulationinput.loadvariablesfromexternalsource.html)) ([raw](?raw))

Load variables from a custom file into Simulink.SimulationInput object

Since R2022b

Syntax

Description

simIn = loadVariablesFromExternalSource([simIn](#mw%5F38b1feae-c7e9-46d7-8a42-97ad7268ec6b),'[filename](#mw%5F1bcde467-6960-4c31-b91a-71613c4c76ad)') loads variables from the custom file filename into theVariables property of the Simulink.SimulationInput object simIn using the custom adapter registered for the file format.

simIn = loadVariablesFromExternalSource([simIn](#mw%5F38b1feae-c7e9-46d7-8a42-97ad7268ec6b),'[filename](#mw%5F1bcde467-6960-4c31-b91a-71613c4c76ad)',[Name,Value](#namevaluepairarguments)) loads variables from a custom file into the Variables property of aSimulink.SimulationInput object simIn with options specified using one or more name-value arguments.

For information on writing a custom file adapter, see Create External File Adapter for Loading Variables into Simulink.SimulationInput Object.

example

Examples

collapse all

This example shows how you can load variables into a Simulink.SimulationInput object from a custom file source, and run parallel simulations with those variables. To enable this, write and register an adapter. In this example, we use a model of a road suspension system. that we want to simulate with different sets of variables. The set of variables and their values for simulations is stored in the Excel files CompactAndMidsizeCar.xls and LargeCars.xls

For the simulations, we have stored different sets of variable values in the Excel files CompactAndMidsizeCar.xls and LargeCars.xls. Normally, you write a script to load variables into the base workspace, and then run your simulation. In this example, you load the variables directly into a Simulink.SimulationInput object and run simulations without changing the base workspace.

Register Adapter

To load the variables from a custom file format, you first must to write and register an adapter. Simulink.data.adapters.excel_example_adapter enables loading data from your custom file format. For more information on creating and registering adapters, see..

Simulink.data.adapters.registerAdapter('Simulink.data.adapters.excel_example_adapter')

Create Simulink.SimulationInput Object

First, create the Simulink.SimulationInput object for the ex_loadvar_sldemo_suspn_3dof model.

mdl = 'ex_loadvar_sldemo_suspn_3dof'; in = Simulink.SimulationInput(mdl)

in = SimulationInput with properties:

           ModelName: 'ex_loadvar_sldemo_suspn_3dof'
        InitialState: [0×0 Simulink.op.ModelOperatingPoint]
       ExternalInput: []
     ModelParameters: [0×0 Simulink.Simulation.ModelParameter]
     BlockParameters: [0×0 Simulink.Simulation.BlockParameter]
           Variables: [0×0 Simulink.Simulation.Variable]
           PreSimFcn: []
          PostSimFcn: []
          UserString: ''
VariantConfiguration: ''

Load Variables from External File Source

You can now use the adapter to load variables from Excel files into a SimulationInput object by using the loadVariablesFromExternalSource function.

Multiple variable sets are saved in different files and in different sheets. To load the variables, first create a cell array named fileAndSectionNames of file-section paris. Each row in this cell array represents the data for a single simulation. Section represents the sheet or sheets present in the excel files.

fileAndSectionNames = { {'CompactAndMidsizeCar.xls', 'CompactCar'}; {'CompactAndMidsizeCar.xls', 'Midsize'}; {'LargeCars.xls', 'LargeCar'}; {'LargeCars.xls', 'LargeSUV'}; }

fileAndSectionNames=4×1 cell array {1×2 cell} {1×2 cell} {1×2 cell} {1×2 cell}

Next, create an array of Simulink.SimulationInput objects and use the loadVariablesFromExternalSource method to load the variable sets into the array. To load variables from specific sheets from the excel files, use the 'Section' argument of the loadVariablesFromExternalSource method.

simIn = Simulink.SimulationInput.empty(length(fileAndSectionNames), 0); for i = 1 : length(fileAndSectionNames) simIn(i) = Simulink.SimulationInput(mdl);
simIn(i) = simIn(i).loadVariablesFromExternalSource(fileAndSectionNames{i}{1}, ... 'Section', fileAndSectionNames{i}{2}) end

simIn = SimulationInput with properties:

           ModelName: 'ex_loadvar_sldemo_suspn_3dof'
        InitialState: [0×0 Simulink.op.ModelOperatingPoint]
       ExternalInput: []
     ModelParameters: [0×0 Simulink.Simulation.ModelParameter]
     BlockParameters: [0×0 Simulink.Simulation.BlockParameter]
           Variables: [1×5 Simulink.Simulation.Variable]
           PreSimFcn: []
          PostSimFcn: []
          UserString: ''
VariantConfiguration: ''

simIn=1×2 SimulationInput array with properties: ModelName InitialState ExternalInput ModelParameters BlockParameters Variables PreSimFcn PostSimFcn UserString VariantConfiguration

simIn=1×3 SimulationInput array with properties: ModelName InitialState ExternalInput ModelParameters BlockParameters Variables PreSimFcn PostSimFcn UserString VariantConfiguration

simIn=1×4 SimulationInput array with properties: ModelName InitialState ExternalInput ModelParameters BlockParameters Variables PreSimFcn PostSimFcn UserString VariantConfiguration

Run Multiple Simulations

To run multiple simulations, use the parsim function with the Simulink.SimulationInput object. Data in each file is isolated and has no impact on simulations that use data from the other files, regardless of the order in which the files are specified.

[01-Feb-2025 17:01:44] Checking for availability of parallel pool... [01-Feb-2025 17:01:44] Running simulations... [01-Feb-2025 17:01:50] Completed 1 of 4 simulation runs [01-Feb-2025 17:01:54] Completed 2 of 4 simulation runs [01-Feb-2025 17:01:58] Completed 3 of 4 simulation runs [01-Feb-2025 17:02:02] Completed 4 of 4 simulation runs

simOut = 1x4 Simulink.SimulationOutput array

To plot the results, plotResult uses a MATLAB® timeseries object. The timeseries object ts stores the time and data values for the logged signal. The plot function plots the data against the simulation time. The plot shows the results for the simulations that uses the variable values loaded from the Excel files.

plotResult(fileAndSectionNames, simOut)

Figure contains an axes object. The axes object with title Response of a 3-DoF Suspension Model, xlabel Time (s), ylabel Vehicle vertical displacement (m) contains 4 objects of type line. These objects represent CompactCar, Midsize, LargeCar, LargeSUV.

As the last step, unregister the adapter.

Simulink.data.adapters.unregisterAdapter('Simulink.data.adapters.excel_example_adapter')

Input Arguments

collapse all

Simulation inputs and configuration, specified as aSimulink.SimulationInput object.

Name of custom external file, specified as a character vector or a string.

To use a custom file format, register an adapter that the method loadVariablesFromExternalSource uses to load variables fromfilename into the Simulink.SimulationInput object.filename must be specified with its extension.

Example: 'myFile'

Name-Value Arguments

collapse all

Specify optional pairs of arguments asName1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: simIn = loadVariablesFromExternalSource(simIn,'filename','Append','on')

Section names in custom file from which variables are loaded, specified as a character vector or a string.

Option to append new loaded variables to existing variables in aSimulink.SimulationInput object, specified as'off' or 'on'.

By default, the loaded variables and their values override the variables and values already present in the Variable property of theSimulink.SimulationInput object.

Workspace for loaded variables, specified as 'global-workspace' or 'modelName'.

Context for loaded variables within global workspace, specified as a string.

When the parameter 'EnforceDataConsistency' is set tooff, the current model and the models below it in the model hierarchy can use variables with the same name but different values as long as each model in the hierarchy can see only one definition of the variable. These variables that have the same name are only attached to their respective models. In such a case, the Context option allows you to set the scope of the variable.

Output Arguments

Version History

Introduced in R2022b