Decide How to Run or Script 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 simulation programmatically during the simulation, use a Simulation object. Using a Simulation object, you can control the simulation execution and tune parameter and variable values during simulation. You can write MATLAB scripts that modify parameter or variable values based on results and values computed in the simulation.

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. Issuing simulation commands using the set_param function allows you to interact with a model both programmatically from the MATLAB command prompt and interactively using the Simulink Editor. Simulation commands are supported in simulations you start by clicking Run in the Simulink Editor or by issuing the start simulation command.

The table summarizes the functionality available for scripting programmatic simulations that use the sim function and for those that use the Simulation object.

Run and Script Simulations Using 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, specifying only the name of the model as an input argument.

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. This command shows the basic syntax for using a SimulationInput object. The SimulationInput object, stored in a variable named simin, is the only input argument. The simulation results are always returned as a single Simulink.SimulationOutput object.

out = sim(simin);

The table summarizes the options you can configure and use cases for using each syntax.

out = sim("ModelName");

out = sim(simin);

out = sim("ModelName",Name=Value);

out = sim("ModelName",paramstruct);

paramStruct.StopTime = "20";

out = sim("ModelName",configset);

Run and Script Simulations Using Simulation Objects

A Simulation object represents a simulation of a model and provides an interface to control and interact with the simulation as it runs. The MATLAB command prompt is available while the simulation is running, unlike simulations you run using the sim function. Using the Simulation object, you can:

The table summarizes the Simulation object functions you can use to control the simulation execution.

You can configure simulations by specifying the initial state, external inputs, model parameter, block parameter, and variable values to use in the simulation. The values you specify override the values saved in the model during simulation and revert when the simulation completes. You can also modify the values of tunable parameter and variable values during simulation. The table summarizes the Simulation object functions available for configuring the simulation.

Interact with Simulations by Issuing Simulation Commands

Starting a simulation by using the set_param function to issue a simulation command is equivalent to starting a simulation from a user interface, such as by clicking Run in the Simulink Editor. The simulation commands programmatically initiate the same actions you can initiate using a user interface, such as the Simulink Editor. Use simulation commands as a convenience in workflows that involve switching between the MATLAB Command Window and the Simulink Editor or another user interface.

To issue a simulation command, specify the SimulationCommand name-value argument for the set_param function. For example, this command issues the start simulation command for a model named MyModel.

set_param("MyModel",SimulationCommand="start")

Because issuing the start simulation command performs the same action as starting a simulation from a user interface, you can issue simulation commands to control and interact with simulations that you start from a user interface or by issuing the start simulation command. Simulations that you start by issuing the start simulation command offer the same functionality and support as simulations you start from a user interface, including:

Errors that occur as a result of issuing a simulation command or during simulations that you start by issuing the start simulation command are reported to the Diagnostic Viewer, except for errors that occur while executing the update simulation command.

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.

set_param(mdl,SimulationCommand="start")

set_param(mdl,SimulationCommand="stop")

set_param(mdl,SimulationCommand="pause")

set_param(mdl,SimulationCommand="continue")

set_param(mdl,SimulationCommand="update")

set_param(mdl,SimulationCommand="writedatalogs")

When you start a simulation from a user interface or by issuing a simulation command, you can query the simulation status using the get_param function. For example, this command queries the simulation status for a model named MyModel.

simstatus = get_param("MyModel","SimulationStatus")

This table describes the simulation status that corresponds to each return value for the SimulationStatus argument.