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 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 or using the Simulation object.

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

  For more information, see sim.

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

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 using the Save format model configuration parameter.
yout	Output logging	Format specified using the Save format model configuration parameter.
xout	States logging	Format specified using the Save format model configuration 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 Save format model configuration 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 using 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 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

Read-only: 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

Read-only: 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
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 Results as Single Output

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 model LoggingBlocks_NotSSO is saved with the Single simulation output parameter disabled. In some workflows, simulating the model does not return the simulation results as a single Simulink.SimulationOutput object.

To simulate the model, click Run. Alternatively, in the Command Window, issue the start simulation command.

set_param(mdl,SimulationCommand="start")

When a simulation does not return results as a single output, the software saves data from each logging method and logging block to a separate variable in the workspace. For example, data logged for top-level output ports is saved to the workspace with the default variable name yout.

You can access logged data programmatically using the name of the variable associated with the logging method. For example, to access the data logged using the Record block, in the Command Window, type recordout.

Because the Single simulation output parameter is disabled, if you simulate the model programmatically by using the model-name syntax of the sim function without specifying any name-value arguments, the simulation returns only the time vector.

out = sim(mdl)

out = 51×1

         0
    0.2000
    0.4000
    0.6000
    0.8000
    1.0000
    1.2000
    1.4000
    1.6000
    1.8000
    2.0000
    2.2000
    2.4000
    2.6000
    2.8000
      ⋮

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.

1. In the Simulink Toolstrip, on the Modeling tab, click Model Settings.

2. In the Configuration Parameters dialog box, select the Data Import/Export pane.

3. Select Single simulation output.

4. Click OK.

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 simulations return data logged to the workspace 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, clear the variables that contain logging data from the previous simulation from the workspace.

clear logsout recordout ScopeData simout tout yout

Simulate the model again. Click Run or simulate the model programmatically using the sim function.

out = sim(mdl);

Now, a single variable named out contains all simulation data logged to the workspace.

The Simulink.SimulationOutput object out contains a property for each logging method and logging block used in the 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: [1×1 Simulink.SimulationData.BlockPath]
          PortType: 'outport'
         PortIndex: 1
            Values: [1×1 timeseries]


  Methods, Superclasses

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: [1x1 tsdata.timemetadata]
            Data: [51x1 double]
        DataInfo: [1x1 tsdata.datametadata]

  More properties, Methods

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
    1.8186
    1.6170
    1.3509
    1.0310
    0.6700
      ⋮

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 returns results as 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 signal Big Sine, which was logged using the To Workspace block.

simout = out.simout

  timeseries

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

  More properties, Methods

Use the get function to access the signal Sine, which was 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 signal Square Wave, which was 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.

Access the simulation metadata in the SimulationMetadata property of the SimulationOutput object.

simmetadata = out.SimulationMetadata

simmetadata = 
  SimulationMetadata with properties:

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

The simulation metadata is returned as a Simulink.SimulationMetadata object. The SimulationMetadata object groups information as structures in the object properties.

View 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: [0×1 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";
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.

out = 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(out)

props = 5×1 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.

out = removeProperty(out,["recordout" "yout"]);
who(out)

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

out.SineWaveParameters = sinConfig;
who(out)

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.

Create a Simulink.SimulationInput object to configure a simulation of the model ex_sldemo_bounce.

mdl = "ex_sldemo_bounce";
simin = Simulink.SimulationInput(mdl);

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

blk = mdl + "/Initial Velocity";
simin = setBlockParameter(simin,blk,"Value","z");

To prevent the error from interrupting the script execution, enable the CaptureErrors parameter on the SimulationInput object. When the CaptureErrors parameter is enabled, errors and warnings that occur during the simulation are captured in the SimulationOutput object and are not reported in the Command Window or script.

simin = setModelParameter(simin,CaptureErrors="on");

Simulate the model. To run the simulation, the sim function loads the model without opening the model in the Simulink Editor.

out = sim(simin);

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

sldiagviewer.reportSimulationMetadataDiagnostics(out)

Version History

Introduced in R2009b

R2017a: Access simulation metadata using SimulationMetadata property

To access simulation metadata, you can now use the SimulationMetadata property of the Simulink.SimulationOutput object. To access simulation metadata in previous releases, you had to use the getSimulationMetadata function.