Single simulation output

Option to return simulation results as single Simulink.SimulationOutput object

Model Configuration Pane: Data Import/Export

Description

The Single simulation output parameter provides the option to return a single Simulink.SimulationOutput object that contains all simulation results. Using the single-output format makes processing results from several simulations easier and provides better support for parallel and batch simulations. When you enable the Single simulation output parameter, you can use the same code to process results, no matter how you run the simulation.

Simulating a model creates one or more Simulink.SimulationOutput objects in any of these situations, even when you disable 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 panel.

Settings

on (default) | off

on

All simulation data logged to the workspace is returned as a single Simulink.SimulationOutput object. By default, the name of the variable that stores the SimulationOutput object is out. To use a different variable name, specify a valid MATLAB^® variable name in the text box.

When you simulate a model programmatically, the name you specify in the text box does not determine the name of the variable that stores the SimulationOutput object. The SimulationOutput object is stored in the variable to which you assign the return argument. For example, for this simulation, the SimulationOutput object variable name is simout.

simout = sim(simin);

off

Logged simulation results are returned as one or more variables, depending on the logging options configured in the model and how you run the simulation.

When you simulate the model using the model name syntax of the sim function without specifying any other arguments, the simulation returns only the time vector. To have the simulation return complete results, enable the Single simulation output parameter for the simulation by specifying the ReturnWorkspaceOutputs name-value argument.

out = sim(mdl,ReturnWorkspaceOutputs="on");

Syntaxes of the sim function that return multiple arguments are not recommended. For more information, see Syntaxes that return multiple output arguments are not recommended.

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
      ⋮

Tips

• When you log data using the To File block, the data logs to the specified file and does not appear in the single Simulink.SimulationOutput object.

• When you select Log data to file, the data that logs to the file is not included in the single Simulink.SimulationOutput object.

• Enabling fast restart enables the Single simulation output parameter.

• Use the who function for the Simulink.SimulationOutput object to view a list of the variables in the object.

• To use the Logging intervals parameter, you must select Single simulation output.

Programmatic Use

Parameter: ReturnWorkspaceOutputs

Value: "on" | "off"

Default: "on"

Parameter: ReturnWorkspaceOutputsName

Type: string | character vector

Value: valid MATLAB variable name

Default: "out"

Version History

Introduced in R2009b