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 managing data from multiple simulations easier. The Simulink.SimulationOutput object has a property for each logging variable created during simulation. For example, when you use signal logging to log data, the SimulationOutput object contains a property with the default name logsout that contains the logged signal data. To access logged data when simulation results are returned in a single SimulationOutput object, use dot notation.

out.logsout

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 output data and use the default variable name yout, the Simulink.SimulationOutput object has the property yout that contains the logged output 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 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 data 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

Return Simulation Data as Single Object

The model in this example 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 output of the Chirp Signal block is connected to a Scope block that is configured to log data to the workspace.

• 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_NotSSO";
open_system(mdl)

Access Data Not Returned in Single Simulation Output

The LoggingBlock_NotSSO model is not configured to return simulation results in a single Simulink.SimulationOutput object.

Click Run to simulate the model. Alternatively, simulate the model programmatically.

sim(mdl)

When a model is not configured to return results in a single output object, the software records data from each logging technique to a separate variable in the workspace. For example, output data is logged to the workspace with the default variable name yout.

You can access logged data programmatically using the variable name associated with the logging technique used. For example, access the Simulink.SimulationData.Dataset object named recordout that contains the data logged using the Record block.

recordout

recordout = 
Simulink.SimulationData.Dataset 'Run 1: LoggingBlocks_NotSSO' with 3 elements

                         Name         PropagatedName  BlockPath                   
                         ___________  ______________  ___________________________ 
    1  [1x1 Signal]      Big Sine     Big Sine        LoggingBlocks_NotSSO/Record
    2  [1x1 Signal]      Chirp        Chirp           LoggingBlocks_NotSSO/Record
    3  [1x1 Signal]      Square Wave  Square Wave     LoggingBlocks_NotSSO/Record

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

Access Data Returned as Single Simulation Output

To return simulation results as a single output, in the Configuration Parameters dialog box, select Single simulation output.

Alternatively, enable the Single simulation output parameter programmatically using the set_param function.

set_param(mdl,"ReturnWorkspaceOutputs","on")

When you enable the Single simulation output parameter, all simulation data logged to the workspace is returned as a single Simulink.SimulationOutput object with the default variable name out.

To better see the effect that returning simulation data in a single SimulationOutput object has on the workspace, you can clear the previous logging data from the workspace.

clear

Click Run to simulate the model again. Alternatively, simulate the model programmatically.

mdl = "LoggingBlocks_NotSSO";
out = sim(mdl);

All simulation data logged to the workspace is now contained in a single variable named out.

The Simulink.SimulationOutput object out contains a property for each logging variable created during simulation.

out

out = 
  Simulink.SimulationOutput:
              ScopeData: [1x1 Simulink.SimulationData.Dataset] 
                logsout: [1x1 Simulink.SimulationData.Dataset] 
              recordout: [1x1 Simulink.SimulationData.Dataset] 
                 simout: [1x1 timeseries] 
                   tout: [51x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char] 

You can access logged data using dot notation. For example, access the data logged using the Record block.

out.recordout

ans = 
Simulink.SimulationData.Dataset 'Run 2: LoggingBlocks_NotSSO' with 3 elements

                         Name         PropagatedName  BlockPath                   
                         ___________  ______________  ___________________________ 
    1  [1x1 Signal]      Big Sine     Big Sine        LoggingBlocks_NotSSO/Record
    2  [1x1 Signal]      Chirp        Chirp           LoggingBlocks_NotSSO/Record
    3  [1x1 Signal]      Square Wave  Square Wave     LoggingBlocks_NotSSO/Record

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

To access an element of the Dataset object, use curly braces. For example, access the signal Big Sine using the index 1.

out.recordout{1}

ans = 
  Simulink.SimulationData.Signal
  Package: Simulink.SimulationData

  Properties:
              Name: 'Big Sine'
    PropagatedName: 'Big Sine'
         BlockPath: [1x1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1x1 timeseries]

The signal data is stored in the Values property of the Signal object as a timeseries object.

out.recordout{1}.Values

  timeseries

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

The time values are in the Time property of the timeseries object. The signal values are in the Data property.

out.recordout{1}.Values.Data

ans = 51×1

         0
    0.3973
    0.7788
    1.1293
    1.4347
    1.6829
    1.8641
    1.9709
    1.9991
    1.9477
      ⋮

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");

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