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

Logged Data Properties

A Simulink.SimulationOutput object contains a property for each logging variable created in simulation. 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 Name	Logging Source	Value
tout	Time logging	Format specified by the Format parameter.
yout	Output logging	Format specified by the Format parameter.
xout	States logging	Format specified by the Format parameter.
xFinal	Final states logging	When you select Save final operating point, 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.
logsout	Signal logging	Simulink.SimulationData.Dataset object.
dsmout	Data stores logging	Simulink.SimulationData.Dataset object.
simout	To Workspace block	Format specified by the Save format block parameter.
recordout	Record, XY Graph block	Simulink.SimulationData.Dataset object.
ScopeData	Scope block	Format specified by the 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

SimulationMetadata — Information about simulation

Simulink.SimulationMetadata object

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

ErrorMessage — Message for errors from simulation

character vector

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

find	Query and access properties on Simulink.SimulationOutput object
get	Access simulation results in Simulink.SimulationOutput object
getSimulationMetadata	Access simulation metadata in Simulink.SimulationOutput object
plot	Plot simulation results in Simulation Data Inspector
removeProperty	Remove property from Simulink.SimulationOutput object
setUserData	Add data to metadata in Simulink.SimulationOutput object
setUserString	Add string to metadata in Simulink.SimulationOutput object
who	Get names of editable properties on Simulink.SimulationOutput object

Examples

Access Data in Simulink.SimulationOutput Object

When you simulate a model in a way that returns simulation results as a single object, you 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 dot notation, the get function, or the find function.

Use dot notation 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 dot notation 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]

Modify Contents of Simulink.SimulationOutput Object

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

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

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

mdl = "LoggingBlocks"

mdl = 
"LoggingBlocks"

open_system(mdl);

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

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

Simulate the model.

simOut = sim(mdl);

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 want 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)

This Simulink.SimulationOutput object contains these editable properties:

    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 want to save the parameter values for the Sine Wave block as a property on the Simulink.SimulationOutput object. Add the property SineWaveParameters by using dot notation the same way you add a field to a structure.

simOut.SineWaveParameters = sinConfig;
who(simOut)

This Simulink.SimulationOutput object contains these editable properties:

    SineWaveParameters    logsout    simout    tout    

Display Errors in Diagnostic Viewer

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