sim

Simulate Simulink model

Syntax

simOut = sim(simIn)

simOut = sim(simIn,Name,Value)

simOut = sim(modelName)

simOut = sim(modelName,Name,Value)

simOut = sim(modelName,paramStruct)

simOut = sim(modelName,configSet)

Description

Simulink.SimulationInput Object Syntax

simOut = sim(simIn) runs one or more simulations of a Simulink^® model according to the properties defined on one or more Simulink.SimulationInput objects.

• If simIn is a scalar Simulink.SimulationInput object, then simOut is a scalar Simulink.SimulationOutput object.

• If simIn is an array of Simulink.SimulationInput objects, then simOut is an array of Simulink.SimulationOutput objects.

You can use a SimulationInput object to configure options and inputs for simulations, including:

• The model to simulate

• Source variables or files for external input data

• Block parameter values to use for the simulation

• Model configuration parameter values to use for the simulation

When a property of the SimulationInput object modifies a model or block parameter value, the value is modified during simulation and reverted at the end of the simulation.

When you configure programmatic simulations using SimulationInput objects, you can easily transition from using the sim function to using other functions, such as parsim and batchsim.

simOut = sim(simIn,Name,Value) simulates a model according to the properties defined on the Simulink.SimulationInput object simIn with additional options specified using one or more name-value arguments.

For a list of name-value arguments supported for the Simulink.SimulationInput syntax, see Simulink.SimulationInput Object Syntax.

Model Name Syntax

simOut = sim(modelName) simulates the model specified by modelName using the current configuration parameter and block parameter values for the model.

• If the model has the Single simulation output parameter enabled, simOut is a Simulink.SimulationOutput object.

• If the model does not have the Single simulation output parameter enabled, simOut is a vector that contains the simulation times. For more information, see Returning multiple output arguments not recommended.

simOut = sim(modelName,Name,Value) simulates the model specified by modelName with options specified using one or more name-value arguments. For example, you can modify a model configuration parameter value for the simulation by specifying the parameter name and value as a name-value argument.

When you modify model configuration parameters by providing inputs to the sim function, the changes are applied during simulation and reverted at the end of the simulation.

For a list of name-value arguments supported for the model name syntax, see Model Name Syntax.

simOut = sim(modelName,paramStruct) simulates the model specified by modelName using the model configuration parameter values specified by the structure paramStruct.

simOut = sim(modelName,configSet) simulates the model specified by modelName using model configuration parameter values in the configuration set configSet.

Examples

Set Block Parameters for Simulation Using Simulink.SimulationInput Object

Modify the parameter values for blocks in a model using a SimulationInput object.

Open the model.

openExample("simulink_general/sldemo_househeatExample")

Create a SimulationInput object for this model.

mdl = "sldemo_househeat";
simIn = Simulink.SimulationInput(mdl);

Change the set point for the thermostat to 300 by modifying the Value parameter for the Set Point block.

simIn = setBlockParameter(simIn,"sldemo_househeat/Set Point",...
	"Value","300");

Simulate the model.

out = sim(simIn);

Simulate Model with Current Parameter Settings

Simulate the model vdp in its present state, whether the model is not loaded yet or is loaded with unsaved changes.

simOut = sim("vdp");

Simulate Model with Options Specified in Structure

Simulate the model vdp using model configuration parameter values specified in a structure.

Create the structure paramStruct. Configure the model to log states using the variable name xoutNew.

paramStruct.SaveState      = 'on';
paramStruct.StateSaveName  = 'xoutNew';

Add more fields to the structure to configure the model to log outputs using the variable name youtNew.

paramStruct.SaveOutput     = 'on';
paramStruct.OutputSaveName = 'youtNew';

Simulate the model using the options specified in the structure.

simOut = sim('vdp',paramStruct)

simOut = 
  Simulink.SimulationOutput:

                xoutNew: [64x2 double] 
                youtNew: [64x2 double] 

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

Simulate Model Using Simulink.Configset Object

Open the model vdp and get the Simulink.ConfigSet object for the active configuration.

mdl = "vdp";
open_system(mdl)
cs = getActiveConfigSet(mdl);

Create a copy of the Simulink.ConfigSet object. Then, use the set_param function to modify parameter values in the configuration set. Configure the parameters in the ConfigSet object to:

• Use an absolute tolerance of 1e-5

• Log states using the variable name xoutNew

• Log outputs using the variable name youtNew

csNew = copy(cs);
set_param(csNew,"AbsTol","1e-5",...
         "SaveState","on","StateSaveName","xoutNew",...
         "SaveOutput","on","OutputSaveName","youtNew")

Simulate the model using the modified Simulink.ConfigSet object.

simOut = sim(mdl,csNew)

simOut = 
  Simulink.SimulationOutput:

                xoutNew: [65x2 double] 
                youtNew: [65x2 double] 

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

Input Arguments

simIn — Simulation configuration

Simulink.SimulationInput object

Simulation configuration, specified as a Simulink.SimulationInput object. The properties of the SimulationInput object specify options and parameter values to use in the simulation, including:

• The model to simulate

• Source variables or files for external input data

• Block parameter values to use for the simulation

• Model configuration parameter values to use for the simulation

The values defined in the properties of the SimulationInput object are applied to the model for the simulation and reverted at the end of simulation.

modelName — Model to simulate

string | character vector

Model to simulate, specified as a string or a character vector.

Example: simOut = sim("vdp") simulates the model named vdp using the parameter values currently configured in the model.

Data Types: char | string

paramStruct — Model configuration to simulate

structure

Model configuration to simulate, specified as a structure. The fields of the structure are the names of model configuration parameters. The value for each field indicates the parameter value to use in simulation. For example, to simulate a model from a start time of 5 to a stop time of 10, create this structure:

paramStruct.StartTime = "5";
paramStruct.StopTime = "10";

Data Types: struct

configSet — Model configuration to simulate

Simulink.Configset object

Model configuration to simulate, specified as a Simulink.ConfigSet object.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: simOut = sim(simIn,"UseFastRestart","on") runs a set of simulations configured using an array of Simulink.SimulationInput objects with fast restart enabled.

Example: simOut = sim(modelName,"Solver","ode15s","StopTime","30") configures a simulation of the model specified by modelName to use the ode15s solver with a stop time of 30.

The sim function supports different name-value arguments depending on whether you specify the first input as a Simulink.SimulationInput object or as the name of the model to simulate. In addition to the arguments listed on this page, you can specify values for model configuration parameters using inputs to the sim function.

• When the first input argument is a Simulink.SimulationInput object, configure model parameter values for the simulation on the input object using the setModelParameter function.

• When the first input argument is the model name, specify any model configuration parameter as a name-value argument.

Simulink.SimulationInput Object Syntax

UseFastRestart — Option to enable fast restart

'off' (default) | 'on'

Option to enable fast restart, specified as 'off' or 'on'. Fast restart reduces the time required to run a set of simulations by skipping the compilation and termination phases when appropriate. Consider using fast restart when you run multiple simulations of the same model.

For more information, see How Fast Restart Improves Iterative Simulations.

This argument is supported only when you specify the first input argument for the sim function as a Simulink.SimulationInput object.

Example: sim(simIn,"UseFastRestart","on")

Data Types: char | string

StopOnError — Option to stop process that started simulation when error occurs

'off' | 'on'

Option to stop process that started simulation when error occurs, specified as 'off' or 'on'.

• 'off' — When an error occurs in a simulation, that simulation stops and the process that started the simulation continues. For example, when you run a set of simulations using an array of Simulink.SimulationInput objects, if the first simulation encounters an error, that simulation stops and subsequent simulations still run.

• 'on' — When an error occurs in a simulation, that simulation and the process that started the simulation both stop. For example, when you run a set of simulations using an array of Simulink.SimulationInput objects, if the first simulation encounters an error, that simulation stops and subsequent simulations do not run.

This argument is supported only when you specify the first input argument for the sim function as a Simulink.SimulationInput object.

Example: sim(simIn,"StopOnError","on")

Tips

• When you specify the name of the model as the first input argument for the sim function, configure this behavior using the CaptureErrors name-value argument.

• When an error does not stop the process that started a simulation, error message information is captured in the Simulink.SimulationOutput object and the Simulink.SimulationMetadata object.

  • To view the message, use the ErrorMessage property of the SimulationOutput object.

  • For more information about the error, use the ExecutionInfo property of the Simulink.SimulationMetadata object. The ErrorDiagnostic field includes information about the error, including the simulation phase where the error occurred.

Data Types: char | string

ShowProgress — Option to indicate simulation progress

'off' | 'on'

Option to indicate simulation progress, specified as 'off' or 'on'.

• 'off' — Simulations run without displaying progress messages.

• 'on' — Progress updates are displayed as simulations progress.

  This option is useful when you run multiple simulations using an array of Simulink.SimulationInput objects.

  This argument is supported only when you specify the first input argument for the sim function as a Simulink.SimulationInput object.

Example: sim(simIn,"ShowProgress","on")

ShowSimulationManager — Option to open Simulation Manager

'off' (default) | 'on'

Option to open Simulation Manager, specified as 'off' or 'on'. Use the Simulation Manager to monitor the progress of simulations you run. Consider using the Simulation Manager when you run multiple simulations using an array of Simulink.SimulationInput objects.

This argument is supported only when you specify the first input argument for the sim function as a Simulink.SimulationInput object.

Example: sim(simIn,"ShowSimulationManager","on")

Model Name Syntax

CaptureErrors — Option to continue process that started simulation if error occurs

'off' (default) | 'on'

Option to continue process that started simulation if error occurs, specified as 'off' or 'on'. By default, when you run a simulation using the sim function and specify the name of the model as the first input:

• Errors are reported in the MATLAB^® Command Window.

• Both the simulation and the process that invoked the simulation stop when the error occurs.

• The error message is not captured in the Simulink.SimulationOutput object or Simulink.SimulationMetadata object.

When you specify CaptureErrors as 'on', errors are reported only in the simulation outputs. The execution of the simulation with the error stops, but if the simulation was invoked by another process, that process continues. For example, when you run multiple simulations in a loop, if you specify CaptureErrors as 'on', subsequent simulations continue to run following a simulation with an error.

This argument is supported only when you specify the first input argument for the sim function as the name of the model to simulate.

Example: sim("myModel","CaptureErrors","on")

Tips

• This option is not supported for software-in-the-loop (SIL) and processor-in-the-loop (PIL) simulations.

• When you specify one or more Simulink.SimulationInput objects as input to the sim function, configure this behavior using the StopOnError name-value argument.

• When you specify CaptureErrors as 'on', error message information is captured in the Simulink.SimulationOutput object and the Simulink.SimulationMetadata object.

  • To view the message, use the ErrorMessage property of the SimulationOutput object.

  • For more information about the error, use the ExecutionInfo property of the Simulink.SimulationMetadata object. The ErrorDiagnostic field includes information about the error, including the simulation phase where the error occurred.

Data Types: char | string

Debug — Option to start simulation in debug mode

'off' (default) | 'on'

Option to start simulation in debug mode, specified as 'off' or 'on'.

This argument is supported only when you specify the first input argument for the sim function as the name of the model to simulate.

Example: sim("modelName","Debug","on")

Data Types: char | string

RapidAcceleratorUpToDateCheck — Option to disable rebuilding rapid accelerator target

'on' (default) | 'off'

Option to disable rebuilding rapid accelerator target, specified as 'on' or 'off'. When you specify this argument as 'on', changes that require rebuilding the rapid accelerator target are ignored. When you use this option, modify only options that do not require rebuilding the rapid accelerator target.

This argument is supported only when you specify the first input argument for the sim function as the name of the model to simulate.

Example: sim("modelName","RapidAcceleratorUpToDateCheck","off")

Tips

To specify this option for a simulation configured using a Simulink.SimulationInput object, use the setModelParameter function.

simIn = Simulink.SimulationInput("myModel");
simIn = setModelParameter(simIn,"RapidAcceleratorUpToDateCheck","off");

Data Types: char | string

TimeOut — Maximum simulation run time

positive scalar

Maximum simulation run time, specified as a positive scalar. Specify the time, in seconds, to allow the simulation to run. If the simulation runs for longer than the value you specify, the software issues a warning and stops the simulation. For example, if you specify TimeOut as 30, the software stops the simulation and issues a warning if computing simulation results takes more than 30 seconds.

The TimeOut parameter specifies a limit on the amount of clock time for a simulation to run. To specify the maximum time value to simulate, use the Stop time parameter.

This argument is supported only when you specify the first input argument for the sim function as the name of the model to simulate.

Example: sim("modelName","TimeOut",60) configures a simulation to run for a maximum duration of 60 seconds.

Tips

To specify this option for a simulation configured using a Simulink.SimulationInput object, use the setModelParameter function.

simIn = Simulink.SimulationInput("modelName");
simIn = setModelParameter(simIn,"TimeOut",60);

Trace — Option to display summary of parameters before simulation

'siminfo'

Option to display summary of parameters before simulation, specified as 'siminfo'.

This argument is supported only when you specify the first input argument for the sim function as the name of the model to simulate.

Example: sim("modelName","Trace","siminfo")

Data Types: char | string

Output Arguments

simOut — Simulation outputs

Simulink.SimulationOutput object | array of Simulink.SimulationOutput objects | vector

Simulation outputs, returned as a Simulink.SimulationOutput object, an array of Simulink.SimulationOutput objects, or a vector. The Simulink.SimulationOutput object contains all data logged from simulation as well as metadata about the simulation, including timing information and diagnostics.

When you specify only the model name as an input argument and the model you simulate has the Single simulation output parameter disabled, the output from the sim function is a vector of simulation times. For the sim function to return results in a consistent format for any syntax, save the model with the Single simulation output parameter enabled.

Tips

• To ensure the sim function returns results in the same format regardless of which input arguments you specify, save your model with the Single simulation output parameter enabled. With this option enabled, simulation results are returned as a Simulink.SimulationOutput that contains all logged data as well as simulation metadata, including timing information and diagnostics. Analyzing results from multiple simulations is easier when all simulation data and metadata is stored in a single object.

• To get a list of model configuration parameters, use the getActiveConfigSet function and the get_param function. For example, to see the configuration parameters for the model vdp, enter these commands in the MATLAB Command Window.

  configSet = getActiveConfigSet("vdp");
  configSetNames = get_param(configSet,"ObjectParameters")

  The return from the get_param function lists the model configuration parameters such as StopTime, SaveTime, SaveState, SaveOutput, and SignalLogging.

• When you simulate a model hierarchy, model configuration parameters you specify as input arguments to the sim function apply to the top model.

• When you run a simulation using the sim function, the simulation runs until an error occurs or the simulation reaches the specified stop time. To programmatically run an interactive simulation that you can pause and continue programmatically, use the set_param function with the SimulationCommand input argument. For more information, see Run Simulations Programmatically.

• When you simulate a model with infinite stop time, stop the simulation from the MATLAB Command Window by pressing Ctrl+C. The simulation stops, and simulation results are not saved in the MATLAB workspace.

• Configure logging for time, states, and outputs using the Configuration Parameters dialog box. On the Modeling tab, under Setup, click Model Settings. Then, in the Configuration Parameters dialog box, select Data Import/Export.

• To log signals throughout a model, use signal logging or logging blocks such as the To Workspace block or the Record, XY Graph block. For more information about signal logging, see Save Signal Data Using Signal Logging.

Version History

Introduced before R2006a

R2009b: Returning multiple output arguments not recommended

Starting in R2009b, the sim function provides enhanced compatibility with parallel computing, including an option to return simulation results as a single simulation object, which simplifies data and variable management. The single simulation output syntax is recommended. Syntaxes that return more than one output argument are not recommended.

To configure a model to always return results as a single output object, use the Single simulation output parameter.

To simulate a model programmatically in R2009a and earlier, use this syntax.

[T,X,Y1,Y2,Yn] = sim('model',Timespan,Options,UT);

Only the model input argument is required. When you do not specify other input arguments, the simulation uses the current configuration parameter values for the model. When you specify additional arguments, those arguments override the current values for the model. When you specify an argument as [], the simulation uses the current value in the model for that argument.

The tables describe the input and output arguments and provide information about how to update your code to use syntaxes recommended for R2009b and later.

Input Argument Descriptions and Replacements

Input Argument	Description	Replacement
model	Name of model to simulate, specified as a character vector.	No change. Starting in R2017a, you can specify the model to simulate using a Simulink.SimulationInput object.
Timespan	Simulation start and stop times, specified as a scalar or a vector. TFinal — Specifies the stop time for the simulation, which starts from zero. [TStart TFinal] — Specifies the start time and the stop time for the simulation. [TStart OutputTimes TFinal] — Specifies start and stop times for the simulation along with output times for which to calculate a value. When you do not specify output times, the simulation engine determines the times for which to calculate values. Specifying output times ensures that the simulation computes a value for each time you specify.	Configure these options by specifying model configuration parameters as name-value arguments: Stop time — Specify the stop time for the simulation. Start time — Specify the start time for the simulation. Output times — Specify output times for which to calculate a value. Starting in R2017a, you can configure these options using a Simulink.SimulationInput object.
Options	One or more simulation parameters, specified as a structure.	Specify model configuration parameters using name-value arguments. Starting in R2017a, you can configure simulation options using a Simulink.SimulationInput object.
UT	External input data for root-level input ports.	Specify input data for root-level input ports using the Input parameter. Specify the parameter as a name-value argument. Starting in R2017a, you can specify external inputs using a Simulink.SimulationInput object.

Output Argument Descriptions and Replacements

Output Argument	Description	Replacement
T	Simulation times, returned as a vector.	Access time, states, and output data through the Simulink.SimulationOutput object. When you log time, states, and outputs, the SimulationOutput object contains the logged data, which you can access as a property using a dot and the variable name for the logged data. For example, if the SimulationOutput object is returned as simOut, and you save time data to the variable tout: tout = simOut.tout; Use the model configuration parameters to specify data to log and the variables names for the logged data. Time States Output
X	Logged states, returned as an array or a structure.
Y1,Y2,...,YN	Logged outputs, returned as one or more vectors.

R2009b: SrcWorkspace argument not recommended

Starting in R2009b, the SrcWorkspace name-value argument is not recommended. Specifying this argument can lead to transparency violations for parallel simulations. Instead of using values defined in a workspace, specify values for simulation as input arguments to the sim function.

• Before R2017a, specify parameter values for simulation using a structure that contains fields with names that match the parameter names and values that indicate the value to use for the parameter.

• Starting in R2017a, configure model parameter, block parameter, and variable values using a Simulink.SimulationInput object.