Simulink.SimulationMetadata class

Package: Simulink
Superclasses:

Access metadata of simulation runs

Description

The SimulationMetadata class contains information about a simulation run including:

• Model information

• Timing information

• Execution and diagnostic information

• Custom character vector to tag the simulation

• Custom data to describe the simulation

SimulationMetadata packages this information with the SimulationOutput object. To use SimulationMetadata, use one of these approaches:

• In Configuration Parameters > Data Import/Export, under Save options, select Single simulation output.

• Use set_param to set ReturnWorkspaceOutputs to on.

  set_param(model_name,'ReturnWorkspaceOutputs','on');

To retrieve the SimulationMetadata object, use the getSimulationMetadata method on a SimulationOutput object.

Properties

ModelInfo — Information about the model and simulation operating environment

structure

The ModelInfo structure has these fields.

Field Name	Type	Description
ModelName	char	Name of the model
ModelVersion	char	Version of the model
ModelFilePath	char	Absolute location of the .mdl/.slx file
UserID	char	System user ID of the machine used for the simulation
MachineName	char	Hostname of the machine used for the simulation
Platform	char	Operating system of the machine used for the simulation
ModelStructuralChecksum	4–by–1 uint32	Structural checksum of the model calculated after an update diagram
SimulationMode	char	Simulation mode
StartTime	double	Simulation start time
StopTime	double	Time at which the simulation was terminated
SolverInfo	structure	Solver information: Fixed-step solvers – Solver type, name, and fixed step size Variable solvers – Solver type, name, and max step size (initial setting)
SimulinkVersion	structure	Version of Simulink®
LoggingInfo	structure	Metadata about logging to persistent storage: LoggingToFile field — Indicates whether logging to persistent storage is enabled ('on' or 'off') LoggingFileName field — Specifies the resolved file name for the persistent storage MAT-file (if LoggingToFile is 'on').

ExecutionInfo — Structure to store information about a simulation run

structure

Structure to store information about a simulation run, including the reason a simulation stopped and any diagnostics reported during the simulation. The structure has these fields.

Field Name	Type	Description
StopEvent	Nontranslated character vector	Reason the simulation stopped, represented by one of the following: ReachedStopTime – Simulation stopped upon reaching stop time and no errors were reported during execution. StopEvent has value ReachedStopTime, even if errors are reported in the stop callbacks, which are executed after the simulation ends. ModelStop – Simulation stopped by a block or by solver before reaching stop time. StopCommand – Simulation stopped manually by clicking the Stop button or using the set_param command. DiagnosticError – Simulation stopped because an error was reported during simulation. KeyboardControlC – Simulation stopped using keystroke Ctrl+C. PauseCommand – Simulation paused manually by clicking the Pause button or using the set_param command. ConditionalPause – Simulation paused using a conditional breakpoint. PauseTime – Simulation paused at or after specified pause time. StepForward – Simulation paused after clicking step forward. StepBackward – Simulation paused after clicking step backward. TimeOut – Simulation stopped because execution time exceeded timeout specified by TimeOut.
StopEventSource	Simulink.SimulationData.BlockPath	Source of stop event, if it is a valid Simulink object.
StopEventDescription	Translated character vector	Superset of information stored in StopEvent and StopEventSource.
ErrorDiagnostic	struct	Error reported during simulation, represented by the following fields: Diagnostic – MSLDiagnostic object that includes object paths, ID, message, cause, and stack. SimulationPhase – Represented by one of these: Initialization, Execution, or Termination. SimulationTime – Simulation time represented as a double, if reported during Execution; else, represented as []. By passing the name–value pair 'CaptureErrors', 'on' to the sim command, errors generated during simulation are reported in ExecutionInfo.ErrorDiagnostic. The sim command does not capture generated errors.
WarningDiagnostics	Array of struct	Array of all warnings reported during the simulation. Each array item is represented by the following fields: Diagnostic – MSLDiagnostic object that includes object paths, ID, message, cause, and stack. SimulationPhase – Represented as: Initialization, Execution, or Termination. SimulationTime – Simulation time represented as a double, if reported during Execution; else, represented as [].

TimingInfo — Structure to store profiling information about the simulation

structure

Structure to store profiling information about the simulation, including the time stamps for the start and end of the simulation. The structure has these fields.

Field Name	Type	Description
WallClockTimestampStart	character vector	Wall clock time when the simulation started, in YYYY-MM-DD HH:MI:SS format with microsecond resolution
WallClockTimestampStop	character vector	Wall clock time when the simulation stopped, in YYYY-MM-DD HH:MI:SS format with microsecond resolution
InitializationElapsedWallTime	double	Time spent before execution, in seconds
ExecutionElapsedWallTime	double	Time spent during execution, in seconds
TerminationElapsedWallTime	double	Time spent after execution, in seconds
TotalElapsedWallTime	double	Total time spent in initialization, execution, and termination, in seconds
ProfilerData	Simulink.profiler.Data	Profiling results of the model, returned as a Simulink.profiler.Data object Note The ProfilerData field is shown only when the Profile and ReturnWorkspaceOutputs model parameters are enabled

The ExecutionElapsedWallTime does not include time that the simulation is paused. For example, when you step through a simulation, the simulation pauses after each step, and the ExecutionElapsedWallTime does not count the time the simulation is paused between steps. When you step through a simulation with stepping back enabled, the ExecutionElapsedWallTime does include the time required to step back in the simulation.

UserString — Custom character vector to describe the simulation

character vector

Use Simulink.SimulationOutput.setUserString to directly store a character vector in the SimulationMetadata object that is contained in the SimulationOutput object.

UserData — Custom data to store in SimulationMetadata object that is contained in the SimulationOutput object

character vector

Use Simulink.SimulationOutput.setUserData to store custom data in the SimulationMetadata object that is contained in the SimulationOutput object.

Copy Semantics

Value. To learn how value classes affect copy operations, see Copying Objects.

Examples

Get a SimulationMetadata Object for vdp Simulation

Simulate the vdp model. Retrieve metadata from a SimulationMetadata object of the simulation.

Simulate the vdp model. Save the results of the Simulink.SimulationOutput object in simout.

 open_system('vdp');
 simout = sim(bdroot,'ReturnWorkspaceOutputs','on');

Retrieve metadata information about this simulation using mData. This is the SimulationMetadata object that simout contains.

 mData=simout.getSimulationMetadata()

mData = 

  SimulationMetadata with properties:

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

Store custom data or string in simout.

 simout=simout.setUserData(struct('param1','value1','param2','value2','param3','value3'));
 simout=simout.setUserString('Store first simulation results');

Retrieve the custom data you stored from mData.

 mData=simout.getSimulationMetadata()
 disp(mData.UserData)

mData = 

  SimulationMetadata with properties:

        ModelInfo: [1x1 struct]
       TimingInfo: [1x1 struct]
    ExecutionInfo: [1x1 struct]
       UserString: 'Store first simulation results'
         UserData: [1x1 struct]

    param1: 'value1'
    param2: 'value2'
    param3: 'value3'

Retrieve the custom string you stored from mData.

 mData=simout.getSimulationMetadata()
 disp(mData.UserString)

 % Copyright 2018-2022 The MathWorks, Inc.

mData = 

  SimulationMetadata with properties:

        ModelInfo: [1x1 struct]
       TimingInfo: [1x1 struct]
    ExecutionInfo: [1x1 struct]
       UserString: 'Store first simulation results'
         UserData: [1x1 struct]

Store first simulation results

Version History

Introduced in R2015a

R2023b: Initialization time includes time to set up simulations configured using Simulink.SimulationInput objects

The initialization time captured as part of the TimingInfo property now captures the time required to set up a simulation based on the configuration in a Simulink.SimulationInput object, such as:

• Model reference build time, including time to set up parallel workers

• Time to run the presimulation callback function specified using the setPreSimFcn function

• Time to set variable, block parameter, and model parameter values