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 thaninactive
.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
Description
s = simulation(
creates the
simin
)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
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
or1
— TheSimulation
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 thestart
orinitialize
function, theSimulation
object checks that the model is loaded and loads the model if needed.false
or0
— TheSimulation
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
scalar number
This property is read-only.
Current simulation time, returned as a scalar number.
Data Types: double
Status
— Simulation status
"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
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:
Structure that matches the
Structure
orStructure 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
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
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.0521
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.4339
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.8081
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.4339
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: tout: [97x1 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: tout: [97x1 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
See Also
Objects
Functions
MATLAB 命令
您点击的链接对应于以下 MATLAB 命令:
请在 MATLAB 命令行窗口中直接输入以执行命令。Web 浏览器不支持 MATLAB 命令。
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)