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.SimulationInputobjects.You can configure simulations using
SimulationInputobjects when you run simulations using thesim,parsim, andbatchsimfunctions or using theSimulationobject.You simulate the model using a
simfunction 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
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
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.
In the Simulink Toolstrip, on the Modeling tab, click Model Settings.
In the Configuration Parameters dialog box, select the Data Import/Export pane.
Select Single simulation output.
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.Dataans = 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
⋮
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'
StopEventTime: 20
StopEventSource: []
StopEventDescription: 'Reached stop time of 20'
ErrorDiagnostic: []
WarningDiagnostics: [0×1 struct]
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
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 sldemo_bounce.
mdl = "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)
