Input

Option to load external input data for simulation using top-level input ports

Model Configuration Pane: Data Import/Export

Description

The Input parameter specifies whether to load external input data for top-level input ports. When you select the Input parameter, you must also specify the external input data to load for each top-level input port.

When you simulate a model hierarchy, only input ports in the top model load data from the workspace. The Input parameter value for referenced models is ignored except when you simulate a referenced model as a top model. To load data into a referenced model that is not simulated as a top model, use a loading block other than the Inport block or In Bus Element block, for example the From Workspace block.

For more information, see Load Data to Root-Level Input Ports.

Settings

off (default) | on

off

By default, the Input parameter is disabled. Leave this parameter disabled when your model does not contain top-level input ports.

on

When your model contains top-level input ports, select the Input parameter to specify input data to load for each port during simulation. In the text box, specify the external input data to load as a MATLAB^® variable that contains the data for all top-level input ports or as a comma-separated list where each item in the list contains data for one top-level input port. You can use several formats to represent the data for all top-level input ports and to represent the data for each top-level input port. For all data formats:

• Time values must have double data type and increase monotonically.

• Time and signal data must not contain Inf or NaN values.

The table summarizes supported data formats for specifying the value of the Input parameter as a variable that contains data for all top-level input ports.

Format	Description	Tips and Considerations
Simulink.SimulationData.Dataset	Each element in the Dataset object contains data for a top-level input port.	The Dataset object can contain data for top-level ports that produce scalar, vector, and multidimensional signals as well as buses and arrays of buses. To create a Dataset object that contains an element for each top-level input port, use the createInputDataset function. Dataset is the default format for most types of logging, including output, states, and signal logging.
Simulink.SimulationData.DatasetRef	The DatasetRef object references a Dataset object saved in a MAT file. Each element of the Dataset object that the DatasetRef object references contains data for a top-level input port.	The simulation incrementally loads the data referenced by a DatasetRef object instead of loading all of the data into memory at the start of the simulation. Consider using a DatasetRef object when you need to load large amounts of data. For more information, see: Load Big Data for Simulations Stream Data from MAT File as Input for Parallel Simulations
Structure	Structure that contains these fields: signals — Array of structures where each structure contains data for a top-level input port time — Optional array of time values that correspond to the signal values for all top-level input ports	This format does not support input data for buses or arrays of buses. When you load only data for discrete input signals, consider omitting the time field. For more information, see Control How Models Load Input Data. To create an evenly spaced time vector, create an integer vector that contains the desired number of time steps, then scale the values in the vector by the sample time. time = sampleTime*(0:numSteps); Using other options, such as linspace, can introduce discrepancies in the data due to floating-precision rounding.
Array	The first column in the array contains time values that must increase monotonically. Subsequent columns contain data for each top-level input port in sequential order by port number.	Array format supports loading only real scalar signals and real wide or vector signals. Values in the array must have double data type. When your model has a top-level Trigger block, specify the data for the trigger signal in the last column.

In addition to choosing whether to specify the data to load as a single variable or a comma-separated list, you must also choose how to represent the input data for each port. The supported formats depend on the way that you specify the value of the Input parameter and the type of output produced by the port. The table summarizes the formats you can use to specify the data for a top-level input port based on the type of output the port produces in the model.

Type of Output	Supported Input Data Formats	Supported Values for Input Parameter	Tips and Considerations
Scalar or vector signal	timetable that contains a single column timeseries object Simulink.SimulationData.Signal object matlab.io.datastore.SimulationDatastore object Structure with fields and hierarchy that match the Structure or Structure with time logging format Two-dimensional array in which the first column is time and one or more additional columns contain the signal value for each timestamp	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Structure Array Comma-separated list	For scalar and vector signals, the number of rows in the signal data must match the number of rows in the time vector. To create a timetable, the time values must be a duration vector. Simulation time always uses units of seconds. When you create a duration vector that uses units other than seconds, the software converts the value to seconds for use in the simulation. Array format does not support signal values that are complex or that have a data type other than double.
Multidimensional signal	timeseries object timetable that contains a single column Simulink.SimulationData.Signal object matlab.io.datastore.SimulationDatastore object Structure with fields and hierarchy that match the Structure or Structure with time logging format	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Structure Comma-separated list	For a multidimensional signal with values that have two or more dimensions, the length of the last dimension must match the length of the time vector. For example, input data for 10 samples of a 2-by-2 matrix signal has a time vector that contains 10 rows and an array of signal values that has dimensions 2-by-2-by-10. To create a timetable, the time values must be a duration vector. Simulation time always uses units of seconds. When you create a duration vector that uses units other than seconds, the software converts the value to seconds for use in the simulation.
Variable-size signal	Structure with fields and hierarchy that match the Structure or Structure with time logging format	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Structure Comma-separated list	To log a variable-size signal in a format you can load using the From Workspace block, connect the signal to a top-level Outport block and set the Format configuration parameter for the model to Structure or Structure with time.
Bus	Structure of timetable, timeseries, or matlab.io.datastore.SimulationDatastore objects: Specify the Output data type parameter as the Simulink.Bus object that defines the bus. The hierarchy and field names of the structure must match the hierarchy and element names of the bus. Each timetable or timeseries object contains data for a leaf signal in the bus. Each timetable must contain only one column.	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Comma-separated list	To partially specify input data for a bus, set bus elements for which you do not need to load data to [] in the input data structure.
Array of buses	Array of structures that each represent data for a bus within the array of buses	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Comma-separated list	To partially specify input data for an array of buses, set bus elements for which you do not need to load data to [] in the structure that represents the data for that bus.
Function-call signal	n-by-1 column vector that specifies the time for each function-call event	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Structure Comma-separated list	To configure a top-level Inport block to produce a function-call signal, select the Output function call parameter for the block.
Ground	[]	Simulink.SimulationData.Dataset object Simulink.SimulationData.DatasetRef object Structure Comma-separated list	When you do not want to load external input data for an input port, specify the data for that port as []. The input port produces ground values in the model during simulation.

Tips

• You can use the Root Inport Mapper to facilitate mapping input data to top-level input ports in models with several top-level Inport or In Bus Element blocks. To open the Root Inport Mapper, click Connect Inputs.

• You cannot use a data dictionary to store external input data for top-level input ports. The Input parameter does not include data dictionaries when resolving the value you specify for the input data. When a model uses a data dictionary and you disable access to the base workspace, the Input parameter still accesses simulation input data in the base workspace. For more information about how the software resolves symbols, see Symbol Resolution.

• Inport blocks in the top model interpolate and extrapolate input data values according to block parameter values.

• In Bus Element blocks in the top model always linearly interpolate and extrapolate input data values.

Recommended Settings

The table summarizes recommended values for this parameter based on considerations related to code generation.

Application	Setting
Debugging	No impact
Traceability	No impact
Efficiency	No recommendation
Safety precaution	No recommendation

Programmatic Use

Parameter: LoadExternalInput

Value: 'on' | 'off'

Default: 'off'

Parameter: ExternalInput

Type: string | character vector

Value: Simulink.SimulationData.Dataset object | Simulink.SimulationData.DatasetRef object | structure | array | time expression | comma-separated list where each item contains data for a top-level input port

Default: '[t,u]'

Version History

Introduced before R2006a