Main Content

Simulink.SimulationOutput

Access simulation outputs and metadata

Description

The Simulink.SimulationOutput object provides a single point of access for all data associated with a simulation. Properties on the object contain all data logged from simulation and complete simulation metadata, including information about the model configuration, simulation timing, and errors or warnings that occur during simulation. Accessing simulation results in a single object helps distinguish the simulation results from other workspace data and makes it easier to manage data from multiple simulations.

Creation

Simulating a model creates one or more Simulink.SimulationOutput objects in any of these situations:

  • You enable the Single simulation output parameter.

    By default, the Single simulation output parameter is enabled when you create a new model. You can enable the parameter using the Configuration Parameters dialog box. On the Modeling tab, under Settings, click Model Settings. Then, in the Configuration Parameters dialog box, select Data Import/Export and select Single simulation output.

  • You run a set of simulations using the Multiple Simulations pane.

  • You simulate the model programmatically using one or more Simulink.SimulationInput objects.

    You can configure simulations using SimulationInput objects when you run simulations using the sim, parsim, and batchsim functions.

  • You simulate the model using a sim function syntax that returns results as a single simulation output.

    For more information, see sim.

Properties

expand all

Logged Data Properties

When you log data to the workspace and return a single simulation output, the Simulink.SimulationOutput object contains a property for each logging variable. The name of the property matches the name you specify for the logging variable. For example, when you log data using signal logging and use the default variable name logsout, the Simulink.SimulationOutput object has the property logsout that contains the logged signal data.

Configure data to log and variable names using the Data Import/Export pane of the Configuration Parameters dialog box or by adding logging blocks, such as the To Workspace block, to your model. The table summarizes the default property name for several common logging techniques.

Default Property NameLogging SourceValue
toutTime loggingFormat specified by Format parameter.
youtOutput loggingFormat specified by Format parameter.
xoutStates loggingFormat specified by Format parameter.
xFinalFinal states logging

When Save final operating point is selected, final states are saved as a Simulink.op.ModelOperatingPoint object.

When Save final operating point is not selected, final states are saved according to the value of the Format parameter.

For more information, see Save Block States and Simulation Operating Points.

logsoutSignal loggingSimulink.SimulationData.Dataset object.
dsmoutData stores loggingSimulink.SimulationData.Dataset object.
simoutTo Workspace blockFormat specified by Save format block parameter.
recordoutRecord, XY Graph blockSimulink.SimulationData.Dataset object.
ScopeDataScope blockFormat specified by Save format block parameter.

Data you log to a file using To File blocks, Record blocks, or the Log Dataset data to file parameter is not captured as a property of the Simulink.SimulationOutput object.

Custom Properties

You can add properties to a Simulink.SimulationOutput object to store additional data or metadata. For example, when you run parallel simulations using parsim or batchsim, you can define properties on the Simulink.SimulationOutput object to send data from parallel workers to the client.

Adding a property to a Simulink.SimulationOutput object is similar to defining a field in a structure. For example, this code adds the property NewProperty with a value of 1 to the Simulink.SimulationOutput object simOut.

simOut.NewProperty = 1;

Simulation Metadata Properties

This property is read-only.

Information about simulation, returned as a Simulink.SimulationMetadata object. The SimulationMetadata object contains:

  • Detailed information about the model, including the model version and the version of software used to create the model

  • Warnings and errors that occur during simulation

  • Timing information, such as the amount of time spent in the initialization and execution phases of the simulation

This property is read-only.

Message for errors from simulation, returned as a character vector. When a simulation runs without error, the ErrorMessage property is empty.

Tips

When you run a simulation using the sim function, specify the CaptureErrors name-value argument as 'on' to capture error messages in the ErrorMessage property. By default, errors are reported in the MATLAB® Command Window and not captured in the Simulink.SimulationOutput object.

Object Functions

findQuery simulation results in Simulink.SimulationOutput object
getAccess simulation results in Simulink.SimulationOutput object
getSimulationMetadataAccess simulation metadata in Simulink.SimulationOutput object
plotPlot simulation results in Simulation Data Inspector
removePropertyRemove property from Simulink.SimulationOutput object
setUserDataAdd data to metadata in Simulink.SimulationOutput object
setUserStringAdd string to metadata in Simulink.SimulationOutput object
whoGet names of editable properties on Simulink.SimulationOutput object

Examples

collapse all

When simulation results are returned as a single output object, you can access all logged data and simulation metadata using the Simulink.SimulationOutput object.

The model in this example has the Single simulation output parameter enabled and logs data using several different logging methods.

  • The output of the Sine Wave block is logged using signal logging.

  • The output of the Gain block is logged using a To Workspace block.

  • The outputs of the Gain, Chirp Signal, and Square Wave Generator blocks are logged using a Record block.

  • The output of the Square Wave Generator block is logged using output logging.

The model is also configured to log time data.

Open the model.

mdl = "LoggingBlocks";
open_system(mdl)

Create a Simulink.SimulationInput object to configure the simulation for the model. Use the setModelParameter function to set the StopTime parameter to 20.

simIn = Simulink.SimulationInput(mdl);
simIn = setModelParameter(simIn,'StopTime','20');

Simulate the model. The sim function output out is a Simulink.SimulationOutput object that contains all data logged from the simulation. The data for each block and each type of logging is stored as a property that matches the name of the logging variable specified in the block or model.

out = sim(simIn);

You can access logged data using a dot, the get function, or the find function. Each method operates on the logging variable name, and you can use any method to access any kind of logged data.

Use a dot to access the Big Sine signal logged using the To Workspace block.

simout = out.simout
  timeseries

  Common Properties:
            Name: 'Big Sine'
            Time: [51x1 double]
        TimeInfo: tsdata.timemetadata
            Data: [51x1 double]
        DataInfo: tsdata.datametadata

Use the get function to access the Sine signal logged using signal logging.

logsout = get(out,"logsout")
logsout = 
Simulink.SimulationData.Dataset 'logsout' with 1 element

                         Name  BlockPath               
                         ____  _______________________ 
    1  [1x1 Signal]      Sine  LoggingBlocks/Sine Wave

  - Use braces { } to access, modify, or add elements using index.

Use the find function to access the Square Wave signal logged using output logging.

yout = find(out,"yout")
yout = 
Simulink.SimulationData.Dataset 'yout' with 1 element

                         Name         BlockPath             
                         ___________  _____________________ 
    1  [1x1 Signal]      Square Wave  LoggingBlocks/Outport

  - Use braces { } to access, modify, or add elements using index.

You can access the simulation metadata using a dot or using the getSimulationMetadata function.

simMetadata = getSimulationMetadata(out)
simMetadata = 
  SimulationMetadata with properties:

        ModelInfo: [1x1 struct]
       TimingInfo: [1x1 struct]
    ExecutionInfo: [1x1 struct]
       UserString: ''
         UserData: []

The simulation metadata is returned as a Simulink.SimulationMetadata object. The SimulationMetadata object groups information about the simulation in properties with structure values and has properties that allow you to specify a string and additional data related to the simulation.

Access the ExecutionInfo property on the SimulationMetadata object. The execution information shows that the simulation ran through its stop time of 20 without warnings or errors.

simMetadata.ExecutionInfo
ans = struct with fields:
               StopEvent: 'ReachedStopTime'
         StopEventSource: []
    StopEventDescription: 'Reached stop time of 20'
         ErrorDiagnostic: []
      WarningDiagnostics: [0x1 struct]

A Simulink.SimulationOutput object represents the result of a simulation. The SimulationOutput object contains all data logged from simulation and simulation metadata. You can modify the contents of a Simulink.SimulationOutput object by adding or removing information about the simulation.

Open the model LoggingBlocks, which logs several input signals using multiple logging techniques.

open_system("LoggingBlocks");

Use the get_param function to save the values for the Amplitude and Frequency parameters of the Sine Wave block. Store the values in the structure sinConfig.

sinConfig.sinAmp = get_param("LoggingBlocks/Sine Wave","Amplitude");
sinConfig.sinFreq = get_param("LoggingBlocks/Sine Wave","Frequency");

Simulate the model.

simOut = sim("LoggingBlocks");

The simulation results contain all logging variables created in simulation. Use the who function to get a list of properties you can modify.

props = who(simOut)
props = 5x1 cell
    {'logsout'  }
    {'recordout'}
    {'simout'   }
    {'tout'     }
    {'yout'     }

For this simulation, suppose you wanted to save only the data for the signal path related to the Sine Wave block. Use the removeProperty function to remove the recordout and yout properties.

simOut = removeProperty(simOut,["recordout" "yout"]);
who(simOut)
Contents of the Simulink.SimulationOutput object are:

    logsout    simout    tout    

You can also add data to a Simulink.SimulationOutput object by adding your own properties to the object or by using the setUserData function to specify the value for the UserData property on the Simulink.SimulationMetadata object. Suppose you wanted to save the parameter values for the Sine Wave block as a property on the Simulink.SimulationOutput object. Add the property SineWaveParameters by using a dot the same way you add a field to a structure.

simOut.SineWaveParameters = sinConfig;
who(simOut)
Contents of the Simulink.SimulationOutput object are:

    SineWaveParameters    logsout    simout    tout    

You can use the sldiagviewer.reportSimulationMetadataDiagnostics function to display error and warning messages captured in a Simulink.SimulationOutput object using the Diagnostic Viewer.

Open the model ex_sldemo_bounce.

model = "ex_sldemo_bounce";
open_system(model)

Introduce an error into the model by specifying the Value parameter for the block Initial Velocity as the undefined variable z.

set_param("ex_sldemo_bounce/Initial Velocity","Value","z");

Create a Simulink.SimulationInput object to configure the simulation.

simIn = Simulink.SimulationInput(model);

Simulate the model. When you specify the StopOnError option as off, errors and warnings that occur during simulation are captured in the SimulationOutput object are not reported in the Command Window or script and do not interrupt the process of the script.

simOut = sim(simIn,"StopOnError","off","ShowProgress","off");
Warning: One or more simulations completed with errors. For more information, inspect the SimulationOutput objects at these indices: 
[1]

Use the sldiagviewer.reportSimulationMetadataDiagnostics function to display the warning and error messages from the simulation in the Diagnostic Viewer.

sldiagviewer.reportSimulationMetadataDiagnostics(simOut)

Version History

Introduced in R2009b