Simulink.SimulationMetadata

Information about model, environment, execution, and timing of simulation

expand all in page

Description

A Simulink.SimulationMetadata object contains information about the configuration and environment in which a simulation ran.

  • The simulation configuration, such as model name and version, simulation start and stop time, and the simulation mode

  • The environment in which the simulation ran, such as the name of the machine that ran the simulation and the operating system platform on which the simulation ran

  • Diagnostics issued during simulation

  • Simulation timing, including a breakdown of the time spent in the initialization, execution, and termination phases

The SimulationMetadata object has properties you can modify to store additional data and metadata and to save a description of the simulation.

When you run a profiling simulation using the Simulink Profiler, the Simulink.profiler.Data object that contains the profiling results is returned in the SimulationMetadata object.

Creation

The software creates a SimulationMetadata object for every simulation you run that returns results as a single SimulationOutput object. The SimulationMetadata object is returned in the SimulationMetadata property of the Simulink.SimulationOutput object that contains the simulation results. To extract the SimulationMetadata object from a SimulationOutput object, use dot notation.

simmetadata = out.SimulationMetadata;

To ensure each simulation returns results as a single SimulationOutput object, use one of these approaches:

  • Save the model with the Single simulation output enabled.

  • Enable the Single simulation output parameter for the simulation.

    For example, in simulations you run using the sim function without a SimulationInput object, enable the ReturnWorkspaceOutputs parameter by specifying a name-value argument or by setting the parameter in the parameter structure or Simulink.ConfigSet input argument. This code enables the parameter by specifying a name-value argument.

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

The software always returns simulation results as a single output in these situations:

  • 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

expand all

This property is read-only.

Information about simulated model and environment in which simulation ran, returned as a structure.

The table describes the fields of the ModelInfo structure.

Field NameDescription

ModelName

Name of the simulated model, returned as a character vector.

ModelVersion

Version of the simulated model, returned as a character vector.

ModelFilePath

Absolute location of the .mdl or .slx file that contains the simulated model, returned as a character vector.

UserID

System user ID of the machine on which the simulation ran, returned as a character vector.

MachineName

Hostname of the machine on which the simulation ran, returned as a character vector.

Platform

Operating system on which the simulation ran, returned as a character vector.

ModelStructuralChecksum

Structural checksum of the simulated model, determined after compiling the model for simulation, returned as a 4-by-1 uint32 vector.

SimulationMode

Simulation mode, returned as a character vector.

StartTime

Simulation start time, returned as a double.

StopTime

Simulation stop time, returned as a double.

SolverInfo

Information about the solver and solver settings used in the simulation, returned as a structure.

  • For fixed-step solvers, the structure contains the solver type, solver name, and the fixed step size.

  • For variable-step solvers, the structure contains the solver type, solver name, and the value of the Max step size parameter at the start of the simulation.

SimulinkVersion

Information about the version of Simulink® software used to run the simulation, returned as a structure.

LoggingInfo

Information about data logged to file using the Log data to file parameter, returned as a structure that contains these fields:

  • LoggingToFile — Value of the Log data to file parameter for the simulation, returned as 'on' or 'off'.

  • LoggingFileName — Name of file to which the simulation logged data. The structure contains this field only if the Log data to file parameter is enabled for the simulation.

OperatingPointMismatches (since R2025a)

Information about mismatches between the simulated model and the specified initial operating point, returned as a structure. The ModelInfo structure contains this field only if the simulation configuration meets all of these conditions:

The structure contains these fields:

  • BlockNotInOperatingPoint — String array that contains an element for each block in the simulated model that has states but has a path that does not match the block path of any data in the initial operating point

  • BlockNotInModel — String array that contains an element for each block path in the initial operating point data that does not match the path of any block in the simulated model

  • BlockChecksumMismatch — String array that contains an element for each block in the simulated model for which the corresponding initial operating point data is invalid due to differences in the block type or configuration

  • LoggedStatesUsed — String array that identifies states in the loggedStates property of the initial operating point used to initialize blocks listed in the BlockChecksumMismatch field. Each string includes the state type, state name, and the path of the initialized block. Blocks listed in the LoggedStatesUsed field were initialized using only data from the loggedStates property of the initial operating point.

  • LoggedStatesNotUsed — String array that identifies states in the loggedStates property that correspond to blocks listed in the BlockChecksumMismatch field but were not used to initialize the blocks due to differences in the block type or block configuration. Each string includes the state type, state name, and the path of the block that was not initialized using any data from the initial operating point.

This property is read-only.

Information about simulation execution and diagnostics, returned as a structure.

The table describes the fields of the ExecutionInfo structure.

FieldDescription

StopEvent

Reason simulation stopped or paused, returned as one of these values:

  • 'ReachedStopTime' — Simulation stopped due to reaching the simulation stop time. This value indicates that no errors occurred during simulation but does not provide information about whether the 'StopFcn' callback issued an error.

  • 'ModelStop' — Simulation stopped by a block or by the solver before reaching the stop time.

  • 'StopCommand' — Simulation stopped manually by clicking Stop or by issuing the stop simulation command using the set_param function.

  • 'DiagnosticError' — Simulation stopped due to an error.

  • 'KeyboardControlC' — Simulation stopped by pressing Ctrl+C.

  • 'PauseCommand' – Simulation paused manually by clicking Pause or by issuing the pause simulation command using the set_param function.

  • 'ConditionalPause' — Simulation paused on breakpoint.

  • 'PauseTime' — Simulation paused due to reaching specified pause time.

  • 'StepForward' — Simulation paused after manual advance by clicking Step Forward.

  • 'StepBackward' — Simulation paused after manual advance by clicking Step Back.

  • 'TimeOut' — Simulation stopped because the elapsed execution time exceeded the specified timeout.

StopEventSource

Source of ModelStop stop event, if a block stopped the simulation, returned as a Simulink.SimulationData.BlockPath object.

StopEventDescription

Translated description of simulation stop conditions, returned as a character vector.

ErrorDiagnostic

Information about errors reported during simulation, returned as a structure that contains these fields:

  • Diagnostic — Error issued from simulation, returned as a MSLDiagnostic object.

  • SimulationPhase — Phase of simulation in which error occurred, returned as Initialization, Execution, or Termination.

  • SimulationTime — Simulation time at which simulation issued error, returned as a double value if the error occurred during the execution phase and as [] if the error occurred during the initialization or termination phase.

Errors are stored in the simulation metadata when you enable the CaptureErrors parameter. For more information, see sim and setModelParameter.

WarningDiagnostics

Information about warnings issued during the simulation, returned as an array of structures. Each structure contains these 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 [].

This property is read-only.

Information about simulation performance and timing, returned as a structure.

The table describes the fields of the TimingInfo structure.

FieldDescription

WallClockTimestampStart

Wall clock time at which the simulation started, returned as a character vector with the format YYYY-MM-DD HH:MI:SS.

WallClockTimestampStop

Wall clock time at which the simulation stopped, returned as a character vector with the format YYYY-MM-DD HH:MI:SS.

InitializationElapsedWallTime

Time spent initializing simulation, in seconds, returned as a double with microsecond resolution.

ExecutionElapsedWallTime

Time spent in execution phase of simulation, in seconds, returned as a double with microsecond resolution.

The ExecutionElapsedWallTime field value does not include time that the simulation is paused. For example, when you step through a simulation by clicking Step Forward or using the step function for the Simulation object, the time the simulation spends paused between steps is not included in the value of the ExecutionElapsedWallTime field.

When you step through a simulation and enable stepping back, the ExecutionElapsedWallTime field value does include the time taken to step back in the simulation.

TerminationElapsedWallTime

Time spent terminating simulation, in seconds, returned as a double with microsecond resolution.

TotalElapsedWallTime

Total time spent in initialization, execution, and termination phases of simulation, in seconds, returned as a double with microsecond resolution.

ProfilerData

Data from profiling simulation run using the Simulink Profiler, returned as a Simulink.profiler.Data object or as a character vector that indicates the SimulationMetadata object does not correspond to a profiling simulation.

Custom description of simulation, specified as a string or a character vector. You can set the UserString property by:

  • Using dot notation to specify the property on the SimulationMetadata object.

    This code extracts the SimulationMetadta object from a SimulationOutput object named out and then sets the UserString property on the SimulationMetadata object.

    simmetadata = out.SimulationMetadata;
simmetadata.UserString = "Startup phase";

  • Calling the setUserString function on the SimulationOutput object that contains the SimulationMetadata object.

    This command sets the UserString property of the SimulationMetadata object stored in a SimulationOutput object named out.

    out = setUserString(out,"Startup phase");

Custom data to store with simulation metadata, specified using any MATLAB data type. You can set the UserString property by:

  • Using dot notation to specify the property on the SimulationMetadata object.

    This code extracts the SimulationMetadta object from a SimulationOutput object named out and then sets the UserData property on the SimulationMetadata object.

    simmetadata = out.SimulationMetadata;
simmetadata.UserData = 123;

  • Calling the setUserData function on the SimulationOutput object that contains the SimulationMetadata object.

    This command sets the UserData property of the SimulationMetadata object stored in a SimulationOutput object named out.

    out = setUserData(out,123);

Examples

collapse all

Open Live Script

Simulate the model vdp. To run the simulation, the sim function loads the model. After the simulation, close the model.

mdl = "vdp";
out = sim(mdl);
close_system(mdl)

Use dot notation to get the metadata for the simulation, stored as a Simulink.SimulationMetadata object in the SimulationMetadata property of the Simulink.SimulationOutput object returned by the simulation.

vdpmetadata = out.SimulationMetadata
vdpmetadata = 
  SimulationMetadata with properties:

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

The simulation metadata contains information about the model and the conditions of the simulation in the ModelInfo property of the SimulationMetadata object. The property value is a structure that contains a field for each piece of metadata.

View the value of the ModelName field of the ModelInfo structure. The field contains a character vector that defines the name of the simulated model, vdp.

vdpmetadata.ModelInfo.ModelName
ans = 
'vdp'

View the value of the SolverInfo field of the ModelInfo structure. The field contains information about the solver type and solver name. Because this simulation used a variable-step solver, the field also contains the value of the Max step size parameter at the start of the simulation.

 vdpmetadata.ModelInfo.SolverInfo
ans = struct with fields:
           Type: 'Variable-Step'
         Solver: 'ode45'
    MaxStepSize: 0.4000

To analyze the simulation performance, inspect the TimingInfo property of the SimulationMetadta object. The property value is a structure that includes timing information about the simulation, including the wall-clock start and stop times, total elapsed time, and a breakdown of the time spent in each phase of the simulation.

The total simulation time is about 1 second, with the majority of the time spent in the initialization phase. The ProfilerData property indicates that the simulation did not enable the Simulink Profiler.

vdpmetadata.TimingInfo
ans = struct with fields:
          WallClockTimestampStart: '2025-02-01 17:01:30'
           WallClockTimestampStop: '2025-02-01 17:01:31'
    InitializationElapsedWallTime: 0.7000
         ExecutionElapsedWallTime: 0.0086
       TerminationElapsedWallTime: 0.0435
             TotalElapsedWallTime: 0.7520
                     ProfilerData: 'Profiler is not enabled'

Version History

Introduced in R2015a

expand all

See Also

Objects

Model Settings

Functions

Tools

Topics