Main Content

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.

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

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 OutputSupported Input Data FormatsSupported Values for Input ParameterTips and Considerations

Scalar or vector signal

  • 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 busesArray 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.

ApplicationSetting
DebuggingNo impact
TraceabilityNo impact
EfficiencyNo recommendation
Safety precautionNo 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

See Also

Tools

Blocks

Functions

Topics