Run Simulations Programmatically
To programmatically run a simulation, you can write scripts or issue commands in the MATLAB® Command Window:
Using the
sim
functionUsing the
set_param
function to issue simulation commands using theSimulationCommand
name-value argument.
Each of these options provides different capabilities for configuring the simulation behavior and interacting with the simulation as it runs.
Simulations you run programmatically using the sim
function or the
set_param
function run one at a time, in serial. To run parallel or
batch simulations, use the parsim
function or the batchsim
.
Decide How to Run Programmatic Simulations
In general, the sim
function supports most requirements for running
and scripting individual and serial programmatic simulations where you do not intend to
interact with the model during the simulation.
When you want to interact with a model programmatically during the simulation, you can
use the set_param
function to issue simulation commands. Simulation
commands are supported in simulations you start by clicking Run or by
issuing the start
simulation command using the
set_param
function. Issuing simulation commands can be convenient in
workflows that involve switching between the MATLAB Command Window and the Simulink® Editor.
Fast restart is supported for programmatic simulations you run by issuing simulation
commands and by using the sim
function. No matter how you enable fast
restart,the model remains initialized in fast restart at the end of the simulation, and you
can run the next simulation by clicking Run, by issuing a simulation
command, or by calling the sim
function.
The table summarizes differences between simulations run using the
sim
function and those run using the set_param
function.
Action or Option | sim Function | set_param Simulation Commands |
---|---|---|
Configure model for simulation | Specify values for model configuration parameters, block parameters, and
variables to use in simulation using input arguments for the
The values you specify are
applied during simulation and reverted after the simulation completes. Configuring
simulations using input arguments for the | Specify values for model configuration parameters and block parameters
programmatically using the You can also configure the simulation using tools such as the Property Inspector, the Configuration Parameters dialog box, and the Block Parameters dialog box. Configuring the model for this type of simulation dirties the model. |
Start simulation | Call the |
set_param(mdl,"SimulationCommand","Start") In the Simulink Toolstrip, click Run. |
Stop simulation | In the MATLAB Command Window, press Ctrl+C. |
set_param(mdl,"SimulationCommand","Stop") In the Simulink Toolstrip, click Stop. |
Pause simulation | Not supported. |
set_param(mdl,"SimulationCommand","Pause") In the Simulink Toolstrip, click Pause. |
Resume simulation | Not applicable because pausing simulation is not supported. |
set_param(mdl,"SimulationCommand","Continue") In the Simulink Toolstrip, click Continue. |
Issue command in MATLAB Command Window | Not supported.
| Supported. |
Visualization blocks such as Scope blocks | Visualizations update during only normal and accelerator mode simulations. | Visualizations update during normal, accelerator, and rapid accelerator simulations. |
Port value labels | Not supported. | Port value labels display signal values in the block diagram during normal, accelerator, and rapid accelerator mode simulations. |
Step forward and backward in simulation | Not supported. | Supported for normal and accelerator mode simulations. In the Simulink Toolstrip, on the Simulation tab, click Step Forward or Step Back. |
Signal breakpoints | Not supported. | Supported for normal mode in simulations to pause within a time step. Supported for normal and accelerator mode in simulations configured to pause only between time steps. |
Pause at or after specified time | Not supported. | Supported for normal and accelerator mode simulations. |
Fast restart | To run simulations using fast restart:
| Use the set_param(mdl,"FastRestart","on") In the Simulink Toolstrip, on the Simulation tab, in the Simulate section, click Fast Restart. |
Simulation pacing | Configure simulation pacing by specifying values for the simulation pacing parameters for the model.
| Configure simulation pacing options by using the Simulation Pacing Options dialog box or by specifying values for the simulation pacing parameters programmatically.
|
Simulation timeout | Specify a maximum amount of time to allow the | Not supported. Stop the simulation at any time by issuing a simulation command or by clicking Stop. |
Error handling | Specify whether to capture errors in the simulation output or issue errors as MATLAB exceptions:
| Errors are reported to the Diagnostic Viewer. |
Query simulation status | Not supported.
|
get_param(mdl,"SimulationStatus") |
Run simulation in MATLAB session started using the -nodesktop or
-nodisplay options for matlab (macOS) or matlab (Linux) . | Supported. | Not supported. |
Run Simulations Using the sim
Function
The sim
function has several syntaxes you can use to run and
configure simulations programmatically. When you want to simulate the model using the
current values for all model configuration parameter values, block parameter values,
variable values, and so on, use the most basic
syntax.
out = sim("ModelName");
This syntax returns a single Simulink.SimulationOutput
object that
contains all simulation results except when the Single simulation output parameter is disabled. To ensure you can write
consistent code for all simulations you run programmatically, enable the Single
simulation output parameter.
When you want to configure the simulation, for example by specifying values for model
configuration parameter values, block parameter values, and variables values, use a Simulink.SimulationInput
object to specify the simulation configuration.
out = sim(simIn);
The table summarizes the options you can configure and use cases for using each syntax.
sim Syntax | Simulation Configuration Options |
---|---|
out = sim("ModelName"); | Simulate model using current values for configuration parameter, block parameter, and variable values. |
out = sim(simIn); | Specify simulation configuration using
Use name-value arguments to configure additional options, such as whether to:
|
out = sim("ModelName",Name=Value); | Use name-value arguments to configure simulation options, such as:
|
out = sim("ModelName",paramStruct); | Specify model configuration parameter values and simulation options using a structure with field names that match each parameter name and field values that specify the value to use for each parameter. For example, to specify
the paramStruct.StopTime = "20"; |
out = sim("ModelName",configSet); | Specify model configuration parameter values using a |
Run and Control Simulations by Issuing Simulation Commands
When you start a simulation from a user interface, such as the Simulink Editor, or by using the set_param
function to issue a
simulation command, you can:
Control and interact with the simulation by using the
set_param
function to issue simulation commands.Use the
get_param
function to query the simulation status.
When you issue simulation commands during simulation, the software does not execute the command immediately. The software issues the command only after currently running processes that cannot be interrupted have finished. For example, if you issue a simulation command while the solver is determining the next time step, the software executes the simulation command only after the solver finishes propagating time.
Not all actions available in the Simulink Editor have a corresponding simulation command. The table describes each simulation command and the corresponding user interface actions and keyboard shortcuts.
Simulation Command | Description | Equivalent User Interface Action | Keyboard Shortcut |
---|---|---|---|
set_param(mdl,"SimulationCommand","start"); | Start simulation. | Click Run. | Ctrl+T or F5 |
set_param(mdl,"SimulationCommand","stop"); | Stop simulation. | Click Stop. | Ctrl+Shift+T |
set_param(mdl,"SimulationCommand","pause"); | Pause simulation. | Click Pause. | Ctrl+T or F5 |
set_param(mdl,"SimulationCommand","continue"); | Resume paused simulation. | Click Continue. | Ctrl+T or F5 |
set_param(mdl,"SimulationCommand","update"); | Update diagram. | In the Simulink Toolstrip, in the Prepare section, click Update Model. | Ctrl+D |
set_param(mdl,"SimulationCommand","writedatalogs"); | Write data logging variables to the workspace. | Not supported. | Not supported. |
This table describes the simulation status that corresponds to each return value for the
SimulationStatus
name-value argument.
SimulationStatus Value | Description |
---|---|
stopped | Simulation stopped. |
initializing | Executing initialization phase. |
running | Running execution phase. |
paused | Paused in execution phase. |
compiled | Model compiled. |
updating | Updating diagram. |
terminating | Executing termination phase. |
external | Simulating with Simulink Coder™. |