setExternalInput - Specify external input data for top-level input ports using

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

Specify external input data for top-level input ports usingSimulationInput or Simulation object

Syntax

Description

[s](#mw%5F8f6f9f58-1442-40b4-8168-2735b7957529) = setExternalInput([s](#mw%5F8f6f9f58-1442-40b4-8168-2735b7957529),[indata](#bvn7wzd-1-tu1uN)) specifies the external input data indata on the Simulink.SimulationInput or Simulation object s. Specifying external input data on a SimulationInput or Simulation object is equivalent to configuring the Input parameter in simulations you run using the object. The model is modified during initialization to load the external input data you specify, and the modifications revert when the simulation completes.

In addition to specifying the data to for top-level input ports to load, thesetExternalInput function:

You do not need to use the setModelParameter orsetVariable function to explicitly manage these aspects of loading external input data for simulation.

example

Examples

collapse all

Use the setExternalInput function to specify external data for the simulation configuration stored in a Simulink.SimulationInput object. Then, configure the Inport block to load the input data as a continuous signal using the setBlockParameter function. Finally, run the simulation using the Simulink.SimulationInput object.

Open the model LoadInputData. The model contains one Inport block that is connected to a Gain block with a Gain value of 2. The output of the Gain block is connected to an Outport block.

mdl = "LoadInputData"; open_system(mdl)

The model LoadInputData

Create a Simulink.SimulationInput object for the model.

simIn = Simulink.SimulationInput(mdl);

Create input data to load using the Inport block. For this example, create data that represents a sine wave using an evenly spaced vector of time values. Then, use the sin function to create a signal value for each time point.

sampleTime = 0.1; numSteps = 100; time = sampleTime*(0:numSteps); time = time';

data = sin(2pi/3time);

You can specify external input data for top-level input ports using several formats. For this example, use the timetable format. To create a timetable, the time data must be a duration vector. Use the seconds function to create a duration vector with units of seconds. Then, create the timetable.

secs = seconds(time); inData = timetable(secs,data);

Use the setExternalInput function to add the external input data inData to the simulation configuration in the Simulink.SimulationInput object simIn.

simIn = setExternalInput(simIn,inData);

You can also configure other aspects of the simulation using the Simulink.SimulationInput object, such as block parameter values, model configuration parameter values, and variable values.

Suppose you want to configure the Inport block to load the input data as a continuous signal. Use the setBlockParameter function to enable the Interpolation parameter and specify the Sample time parameter for the block as continuous (0).

inBlk = mdl + "/Inport"; simIn = setBlockParameter(simIn,inBlk,"Interpolate","on"); simIn = setBlockParameter(simIn,inBlk,"SampleTime","0");

Simulate the model using the configuration on the SimulationInput object.

The simulation runs, loading the input data as a continuous signal.

A Dashboard Scope block displays the output from the Gain block.

When your model contains several top-level input ports, you can specify the input data to load as a Simulink.SimulationData.Dataset object that contains an element with the data for each input port. The first element in the object contains the data for the input port with a port number of 1, the second element contains the data for the input port with a port number of 2, and so on.

When you specify the data to load using the variable that contains the data, the data in the variable you specify is added to the Simulink.SimulationInput object so the data is available for simulations run using the object.

This example shows how to load data for three top-level input ports into a simulation configured using a SimulationInput object. The input data for each input port uses a different format to illustrate several available formats.

Open the model InportLoading. The model contains three Inport blocks that are connected directly to three Outport blocks.

mdl = "InportLoading"; open_system(mdl)

The model InportLoading.

Use the createInputDataset function to create a Dataset object that contains an element for each input port in the model.

inDS = createInputDataset(mdl,'UpdateDiagram',true);

By default, the Dataset object created by the createInputDataset function contains placeholder timeseries objects for each element. Create input data for each input port to replace the placeholder data.

For the first input port, create a timeseries object with data that represents a line with a slope of 0.5. For the time data, create an evenly spaced time vector using a sample time, or spacing, of 0.5. To create the signal values, multiply the time vector by 0.5.

sampleTime = 0.5; numSteps = 20; time = sampleTime*(0:numSteps)';

data = 0.5*time;

lineTS = timeseries(data,time);

For the second input port, create a timetable with data that represents a sine wave.

  1. For the sine wave, create an evenly spaced time vector using a sample time of 0.1.
  2. To create the signal values, use the sin function.
  3. To create a timetable, the time input must be a duration vector. Use the seconds function to convert the time values into a duration vector with units of seconds.
  4. Create the timetable.

sampleTime = 0.1; numSteps = 100; time = sampleTime*(0:numSteps)';

sinVals = sin(2pi/3time);

secs = seconds(time); sinTT = timetable(secs,sinVals);

For the third input port, create a structure that contains data for a constant with a value of 3. For input data loading, the structure format has the fields time and signals. The signals field is an array of structures that each contain the data for a signal in the field values. For this example, the signals array has only one element because the structure specifies input data for one input port.

constStruct.time = [0 10]'; constStruct.signals.values = [3 3]';

Replace the placeholder data with the data created for each input port.

inDS{1} = lineTS; inDS{2} = sinTT; inDS{3} = constStruct;

Create a Simulink.SimulationInput object to configure a simulation of the model.

simIn = Simulink.SimulationInput(mdl);

Use the setExternalInput function to specify the input data to load for all three input ports using the Dataset object. The function adds the variable inDs to the SimulationInput object.

simIn = setExternalInput(simIn,inDS);

Simulate the model using the SimulationInput object.

The simulation runs, loading the input data as specified on the SimulationInput object.

A Dashboard Scope block displays the signals produced by the Inport blocks.

Input Arguments

collapse all

Simulation specification or simulation in which to specify external input data for top-level input ports, specified as a Simulink.SimulationInput object or a Simulation object.

A SimulationInput object represents a simulation specification that includes the initial state, external inputs, model parameter values, block parameter values, and variable values to use in the simulation. When you specify the first input argument as aSimulationInput object, you must specify theSimulationInput object as a return argument.

A Simulation object represents a simulation and provides an interface for controlling and interacting with the simulation. When you specify the first input argument as a Simulation object, specifying the Simulation object as a return argument is optional.

Example: simin = setExternalInput(simin,indata) adds the external input data indata to the simulation configuration stored in the SimulationInput objectsimin.

Example: sm = setExternalInput(sm,indata) configures top-level input ports in the simulation represented by theSimulation object sm to load the external input data indata.

External input data for top-level input ports, specified using a format supported by the Input parameter.

When your model contains multiple top-level input ports, specify the data for all input ports using a single variable that contains the data for all top-level input ports. When you specify the external input data to load as a variable, the setExternalInput function adds the variable and the data it contains to the SimulationInput orSimulation object.

You can use several formats to store the input data for all top-level input ports in a single variable, including:

The software maps the signal data in the variable to each top-level input port based on the order of the signal data within the variable and the port number. For example, the first element in a Dataset object maps to the top-level input port with a port number of1.

You can format the data for each top-level input port to load using several formats, including:

For complete information about supported formats, see Input.

Example: simin = setExternalInput(simin,indata) adds the external input data indata to the simulation configuration stored in the SimulationInput objectsimin.

Example: sm = setExternalInput(sm,indata) configures top-level input ports in the simulation represented by theSimulation object sm to load the external input data indata.

Note

Specifying input data as a comma-separated list on aSimulationInput or Simulation object is not recommended.

When you specify the input data as a comma-separated list, thesetExternalInput function does not add the variables that contain the data to theSimulationInput or Simulation object. You must ensure that the input data is available for the simulations you run by managing the data in the workspace or by adding the variables that contain the input data to theSimulationInput or Simulation object yourself using the setVariable function.

Output Arguments

collapse all

Simulation specification or simulation with input data added or modified, returned as a Simulink.SimulationInput object or a Simulation object.

When you use the setExternalInput function to specify external input data on a SimulationInput object, you must specify the SimulationInput object as the return argument.

When you use the setExternalInput function to specify external input data on a Simulation object, assigning the return argument is optional.

Tips

Version History

Introduced in R2017a

expand all

The Simulation object represents a simulation and provides an interface to control simulation execution and tune model parameter, block parameter, and variable values during simulation. You can use the setExternalInputs and setInitialState functions to configure the inputs and initial state for simulations you run using the Simulation object.