simulation

Control simulation execution and tune variable, block parameter, and model parameter values

Since R2024a

Description

The Simulation object represents a simulation of a model and provides an interface to control the simulation. The Simulation object supports all simulation modes, including rapid accelerator, and deployment with Simulink^® Compiler™. Simulation execution does not block the MATLAB^® command prompt except when you advance the simulation by calling the step function.

You can use a Simulation object to:

• Initialize, start, and stop simulations.

• Pause and step through simulations.

• Tune variable, block parameter, and model parameter values before and during simulations.

• Build custom apps to interact with simulations by using App Designer.

For more information about building apps to interact with simulations, see Create App for Simulink Model.

While you can programmatically interact with simulations you run using Simulation objects:

• You cannot interact with the model or simulation associated with a Simulation object using the Simulink Editor while the simulation has a status other than inactive.

• Modifications that are never saved when you save a model, such as breakpoints and port value labels, do not apply to simulations run using the Simulation object.

By controlling simulation execution programmatically, you can integrate the systems and algorithms implemented in Simulink models into MATLAB scripts. For example, if you step to a point in the middle of a simulation, you can use MATLAB code to analyze the simulation results up to that point to determine whether to modify parameter values, the new value for a parameter, or how far to advance the simulation before analyzing the results again.

Creation

Syntax

s = simulation(mdlname)

s = simulation(simin)

Description

s = simulation(mdlname) creates the Simulation object s for the model mdlname.

s = simulation(simin) creates the Simulation object s and sets property values according to the corresponding property values of the Simulink.SimulationInput object simin.

Properties of the Simulink.SimulationInput object that do not have a corresponding property on the Simulation object are not applied to the Simulation object. For example, the Simulation object does not support or have property values for any of the callback functions you can specify on a SimulationInput object, including the callback functions, such as the external inputs callback function, that are available with Simulink Compiler.

Input Arguments

mdlname — Model name

string | character vector

Model name, specified as a string or a character vector.

Data Types: char | string

simin — Simulation inputs and configuration

Simulink.SimulationInput object

Simulation inputs and configuration, specified as a Simulink.SimulationInput object.

Properties

Model Information

ModelName — Name of model to simulate

Read-only: string | character vector

This property is read-only.

Name of model to simulate, returned as a string or a character vector.

LoadModel — Option to load model automatically as needed

true or 1 (default) | false or 0

Option to load model automatically as needed, specified as logical true (1) or false (0).

• true or 1 — The Simulation object automatically loads the model upon creation if the model is not already open or loaded. When you call a function that requires the model, such as the start or initialize function, the Simulation object checks that the model is loaded and loads the model if needed.

• false or 0 — The Simulation object does not automatically load the model. If the model is not open or loaded when you perform an action that requires the model, such as starting or initializing the simulation, the software issues an error.

Simulation Status and Results

Time — Current simulation time

Read-only: scalar number

This property is read-only.

Current simulation time, returned as a scalar number.

Data Types: double

Status — Simulation status

Read-only: "inactive" | "initializing" | "initialized" | "paused" | "running" | "stopping" | "terminating" | "restarting"

This property is read-only.

Simulation status, returned as a string that indicates the status of the simulation that corresponds to the Simulation object.

• "inactive" — Simulation is not active and not initialized.

• "initializing" — Simulation is initializing.

• "initialized" — Simulation is initialized.

• "paused" — Simulation is paused.

• "running" — Simulation is actively running.

• "stopping" — Simulation is stopping.

• "terminating" — Simulation is terminating.

• "restarting" — Simulation initialized in fast restart is restarting.

Data Types: string

SimulationOutput — Simulation results

Read-only: Simulink.SimulationOutput object

This property is read-only.

Simulation results, returned as a Simulink.SimulationOutput object. You can access the property value while the simulation status is paused or inactive.

Simulation Configuration

InitialState — Initial state or operating point for simulation

Simulink.op.ModelOperatingPoint object | Simulink.SimulationData.Dataset object | structure

Initial state or operating point for simulation, specified using one of these options:

• Simulink.op.ModelOperatingPoint object

• Simulink.SimulationData.Dataset object

• Structure that matches the Structure or Structure without time logging format

By default, the property value is an empty Simulink.op.ModelOperatingPoint object. When you create the Simulation object using a Simulink.SimulationInput object, the property value matches the value of the InitialState property of the SimulationInput object.

To specify the value of the InitialState property for a Simulation object, use the setInitialState function. The initial state specified in the InitialState property overrides the value saved in the model during simulation and is reverted when the simulation completes.

When you do not specify an initial state for the InitialState property, the simulation uses the initial state saved in the model.

ExternalInput — External input data to load using top-level input ports

Simulink.SimulationData.Dataset object | timetable | timeseries object | ...

External input data to load using top-level input ports, specified in a format supported by the Input parameter, such as a Simulink.SimulationData.Dataset object.

By default, the property value is an empty double array ([]). When you create the Simulation object using a SimulationInput object, the property value matches the value of the ExternalInput property of the SimulationInput object.

To specify the value of the ExternalInput property for a Simulation object, use the setExternalInput function.

The external input data specified in the ExternalInput property overrides the input data parameter values saved in the model during simulation. The model is updated to load the specified external input data for the simulation, and the modifications revert when the simulation completes.

When you do not specify external input data for the ExternalInput property, the simulation uses the value of the Input parameter saved in the model.

ModelParameters — Model parameter values specified for simulation

array of Simulink.Simulation.ModelParameter objects | ...

Model parameter values specified for simulation, returned as an array of Simulink.Simulation.ModelParameter objects. To specify a model parameter value for a Simulation object or to tune a model parameter value during simulation, use the setModelParameter function. The setModelParameter function creates a ModelParameter object for each parameter you specify and adds the object to the array in the ModelParameters property.

By default, the property value is an empty array of ModelParameter objects.

When you create the Simulation object using a SimulationInput object, the property value specifies the same model parameters and values as the ModelParameters property of the Simulation object.

The model parameter values specified in the ModelParameters property override the parameter values saved in the model during simulation and revert when the simulation completes.

BlockParameters — Block parameter values specified for simulation

array of Simulink.Simulation.BlockParameter objects | ...

Block parameter values specified for simulation, returned as an array of Simulink.Simulation.BlockParameter objects. To specify the value of a block parameter for a Simulation object or to tune a block parameter value during simulation, use the setBlockParameter function. The setBlockParameter function creates a BlockParameter object for each block parameter you specify and adds the object to the array in the BlockParameters property.

By default, the property value is an empty array of BlockParameter objects.

When you create the Simulation object using a SimulationInput object, the property value specifies the same block parameters and values as the BlockParameters property of the SimulationInput object.

The block parameter values specified in the BlockParameters property override the block parameter values saved in the model during simulation and revert when the simulation completes.

Variables — Variable values specified for simulation

array of Simulink.Simulation.Variable objects

Variable values specified for simulation, returned as an array of Simulink.Simulation.Variable objects. To specify the value of a variable for a Simulation object or to tune a variable value during simulation, use the setVariable function. The setVariable function creates a Variable object for each variable you specify and adds the object to the array in the Variables property.

By default, the property value is an empty array of Variable objects.

When you create the Simulation object from a SimulationInput object, the property value specifies the same variable values as the Variables property of the SimulationInput object.

You can specify values for variables that the model accesses from the base workspace, a data dictionary, or the model workspace. The variable values you specify override the value of the variable saved in the base workspace, data dictionary, or model workspace during simulation and revert when the simulation completes.

App Designer

These properties support tuning variables and visualizing logged signal data in custom apps built using App Designer. For more information, see bind.

TunableVariables — Run-to-run and run-time tunable variables

Read-only: simulink.sim.Variables object

This property is read-only.

Run-to-run and run-time tunable variables, returned as a simulink.sim.Variables object. When you build an app in App Designer that interacts with a simulation, the TunableVariables property provides access to the variables you can tune using components in the app.

The Variables object stores information about all variables used in the model or simulation that you can modify between simulations or during simulation. Whether a given variable is run-to-run or run-time tunable depends on the simulation configuration. Variable tunability depends on:

• The simulation mode

• Whether the simulation uses fast restart

• Whether the simulation disables the rapid accelerator up-to-date check

• Whether the simulation is deployed using Simulink Compiler

To see the list of tunable variables for a Variables object, use the keys function.

keys(s.TunableVariables)

To tune a variable value, use the setVariable function.

LoggedSignals — Signals logged in model

Read-only: simulink.sim.Signals object

This property is read-only.

Signals logged in model, returned as a Signals object.

When you build an App Designer app that interacts with a simulation, use the LoggedSignals property to access logged data you can visualize in the app.

Object Functions

Control Simulation Execution

initialize	Initialize simulation represented by Simulation object
start	Start simulation represented by Simulation object
step	Advance simulation represented by Simulation object by specified amount
pause	Pause active simulation represented by Simulation object
resume	Continue paused simulation represented by Simulation object
stop	Stop simulation represented by Simulation object
terminate	Terminate simulation represented by Simulation object

Configure Simulation

setExternalInput	Specify external input data for top-level input ports using SimulationInput or Simulation object
setInitialState	Specify initial state for simulation using SimulationInput or Simulation object
setVariable	Set variable values for simulation using SimulationInput or Simulation object
setModelParameter	Set model parameter values for simulation using SimulationInput or Simulation object
setBlockParameter	Set block parameter values for simulation using SimulationInput or Simulation object

Tune Parameter and Variable Values During Simulation

setVariable	Set variable values for simulation using SimulationInput or Simulation object
setModelParameter	Set model parameter values for simulation using SimulationInput or Simulation object
setBlockParameter	Set block parameter values for simulation using SimulationInput or Simulation object

Examples

Control Simulation Execution and Check Simulation Status

Open the model vdp.

mdl = "vdp";
open_system(mdl)

Create a Simulation object to represent a simulation of the model.

sm = simulation(mdl);

The model vdp is small and simple and simulates very fast. Configure the simulation to run at a slower pace relative to real or wall clock time so the simulation runs long enough for you to interact with it. This code configures the simulation to run at a rate of approximately two simulation seconds per one second of real time.

sm = setModelParameter(sm,EnablePacing="on");
sm = setModelParameter(sm,PacingRate="2");

Configure the simulation to run to a stop time of 40 seconds.

sm = setModelParameter(sm,StopTime="40");

Check the simulation status by using the Status property. Before you start or initialize the simulation, the simulation status is inactive.

sm.Status

ans = 
"inactive"

You can initialize the simulation without starting it. Initializing the simulation compiles the model and sets up resources, such as memory, for running the simulation. After you initialize the simulation, the simulation status is initialized. The Simulink® Editor locks to prevent modifications to the model or simulation by anything other than the Simulation object that controls the simulation.

initialize(sm)
sm.Status

ans = 
"initialized"

Start the simulation and check the simulation status. Once the simulation starts, the status is running.

start(sm)
sm.Status

ans = 
"running"

Because simulation execution does not block the MATLAB® command prompt, this example uses the MATLAB® pause function to mimic an interactive workflow. This pause command pauses the execution of the script to allow the simulation to run for five seconds.

pause(5) % pause script execution

Pause the simulation using the pause function for the Simulation object and check the simulation status. While paused, the simulation status is paused.

pause(sm) % pause simulation
sm.Status

ans = 
"paused"

The plot in the Scope block updates during the simulation. Logged data also streams to the Simulation Data Inspector.

Check the simulation time. While the script was paused for five seconds, the simulation advanced to a simulation time of approximately 10 seconds. The Time property value is not exactly 10 because:

• The pacing rate of two simulation seconds per second of wall clock time is approximate.

• The variable-step solver determines the major time hits in the simulation.

sm.Time

ans = 
10.3212

Use the pause function to pause a running simulation on demand. To pause the simulation at or after a specific simulation time, use the step function with the PauseTime argument.

For example, advance the simulation through a simulation time of 25 seconds.

step(sm,PauseTime=25);

Check the simulation time. The simulation pauses at the top of the first major time hit with a simulation time greater than or equal to the specified pause time.

sm.Time

ans = 
25.2251

Because the simulation pauses at the top of the major time hit, output values are not available for the current simulation time. Check the time of the last value in the simulation outputs.

sm.SimulationOutput.yout{1}.Values.Time(end)

ans = 
24.5986

The status bar in the Scope window and the status bar in the Simulink® Editor both indicate the simulation time of the last output calculation.

In the Simulink Editor, the asterisk next to the time indicates that the current simulation time is ahead of the time the status bar reports.

Advance the simulation through the current major time hit.

step(sm);

The output results are now available for the time hit.

sm.SimulationOutput.yout{1}.Values.Time(end)

ans = 
25.2251

To continue the simulation, use the resume function.

resume(sm)

Because simulation execution does not block the MATLAB® command prompt, this example uses the MATLAB® pause function to mimic an interactive workflow. This pause command pauses the execution of the script to allow the simulation to run for five seconds.

pause(5) % pause script execution

To stop the simulation before the simulation completes, use the stop function.

out = stop(sm)

out = 
  Simulink.SimulationOutput:

                logsout: [1x1 Simulink.SimulationData.Dataset] 
                   tout: [141x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char] 

Check the simulation status. Because the simulation did not enable fast restart, stopping the simulation also terminates the simulation. After stopping, the simulation status is inactive.

sm.Status

ans = 
"inactive"

The stop function returns the Simulink.SimulationOutput object that contains the simulation results. You can also access the results from the SimulationOutput property of the Simulation object.

outprop = sm.SimulationOutput

outprop = 
  Simulink.SimulationOutput:

                logsout: [1x1 Simulink.SimulationData.Dataset] 
                   tout: [141x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char] 

When you run another simulation using the Simulation object sm, the results from the current simulation overwrite the SimulationOutput property.

Version History

Introduced in R2024a

R2025a: Log data to file with simulation object

You can log data to file when using simulation object with the setModelParameter. You can log data to an MLDATX file with the simulation object only in normal mode simulations.