setModelParameter

Set model parameter values for simulation using SimulationInput or Simulation object

Syntax

s = setModelParameter(s,Name=Value)

Description

s = setModelParameter(s,Name=Value) sets the model parameter named Name to the value Value on the Simulink.SimulationInput or Simulation object s.

• When s is a SimulationInput object, you can specify only a single value for each parameter to use for the entire simulation.

• When s is a Simulation object, you can specify a single value for each parameter to use at the start of the simulation and specify new values for tunable parameters during simulation.

You can use the setModelParameter function to specify a value for any model parameter on a SimulationInput or Simulation object. The parameter values you specify override the values saved in the model for simulations you run using the SimulationInput or Simulation object during simulation and are reverted when the simulation completes. You can use a SimulationInput or Simulation object to override any number of parameter values.

Examples

Configure Model Parameter Value for Simulation

Configure model parameter values for a simulation using a SimulationInput object.

Open the model.

mdl = "sldemo_househeat";
openExample("simulink_general/sldemo_househeatExample",...
             SupportingFile=mdl)

Create a SimulationInput object for the model.

simin = Simulink.SimulationInput(mdl);

Specify a simulation timeout of 5 seconds, and then specify the start and stop time for the simulation.

simin = setModelParameter(simin,Timeout=5);
simin = setModelParameter(simin,StartTime="1",StopTime="4");

Simulate the model.

out = sim(simin);

Input Arguments

s — Simulation specification or simulation in which to set model parameter

Simulink.SimulationInput object | Simulation object

Simulation specification or simulation in which to set model parameter, specified as a Simulink.SimulationInput object or a Simulation object.

A SimulationInput object represents a simulation specification that includes the initial state, external inputs, model parameter values, block parameter values, and variable values to use in the simulation. When you specify the first input argument as a SimulationInput object:

• For each model parameter, you can specify only a single value to use for the entire simulation.

• You must specify the SimulationInput object as a return argument.

The Simulation object represents a simulation and provides an interface for controlling and interacting with the simulation. When you specify the first input argument as a Simulation object:

• For each model parameter, you can specify the initial value to use in the simulation.

• You can modify the values of tunable model parameters during simulation.

• Specifying the Simulation object as a return argument is optional.

Example: simin = setModelParameter(simin,FixedStep="0.1") specifies a fixed step size of 0.1 seconds in the simulation configuration stored on the SimulationInput object simin.

Example: sm = setModelParameter(sm,FixedStep="0.1") changes the value of the fixed step size to 0.1 in the simulation represented by the Simulation object sm.

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: simin = setModelParameter(simin,TimeOut="100") configures a SimulationInput object with a simulation timeout of 100 seconds.

Configuration Parameter Name — Model configuration parameter

configuration parameter value

Model configuration parameter, specified as a name-value argument that consists of the programmatic name of the configuration parameter and the configuration parameter value. For example, to specify a value for the Stop time parameter, use the programmatic parameter name StopTime as the name in the name-value argument and specify the simulation stop time as the value. This command sets the simulation stop time to 100 seconds on the SimulationInput object named simin.

simin = setModelParameter(simin,StopTime="100");

You can use the setModelParameter function to specify the value for any model configuration parameter on a SimulationInput object or a Simulation 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 a model named vdp, enter these commands in the MATLAB^® Command Window.

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

The get_param function returns a list of all the model configuration parameters, such as StopTime, SaveTime, SaveState, SaveOutput, and SignalLogging.

Example: simin = setModelParameter(simin,FixedStep="0.1") specifies a fixed step size of 0.1 seconds in the simulation configuration stored on the SimulationInput object simin.

Example: sm = setModelParameter(sm,FixedStep="0.1") changes the value of the fixed step size to 0.1 in the simulation represented by the Simulation object sm.

FastRestart — Option to enable fast restart for individual, iterative simulations

"off" (default) | "on"

Since R2024a

Option to enable fast restart for individual, iterative simulations, specified as "on" or "off".

• "on" — Enables fast restart for simulation. Fast restart saves time in iterative simulation workflows by skipping compilation and termination after compiling the model for the first simulation you run after enabling fast restart.

  When you run a simulation that enables fast restart using a Simulation object or a scalar SimulationInput object, if the model is not already initialized in fast restart, the software compiles the model before running the simulation. At the end of the simulation, the model remains initialized in fast restart.

• "off" — Disables fast restart for simulation.

This parameter affects only individual simulations run using:

• The sim function with a scalar SimulationInput object

• A Simulation object

When you run multiple simulations by specifying an array of SimulationInput objects as an input to functions such as sim, parsim, and batchsim, enable fast restart by specifying the UseFastRestart name-value argument for the sim, parsim, or batchsim function.

By default, fast restart is disabled. For more information, see How Fast Restart Improves Iterative Simulations.

Example: simin = setModelParameter(simin,FastRestart="on") configures the SimulationInput object simin to enable fast restart for a simulation you run by specifying the scalar SimulationInput object as an input argument to the sim function.

Example: sm = setModelParameter(sm,FastRestart="on") configures the simulation represented by the Simulation object sm to enable fast restart.

Data Types: char | string

CaptureErrors — Option to capture simulation errors in simulation output

"off" (default) | "on"

Since R2024a

Option to capture simulation errors in simulation output, specified as "off" or "on". This parameter affects only individual simulations run using:

• The sim function with a scalar SimulationInput object

• A Simulation object

When you run multiple simulations by specifying an array of SimulationInput objects as an input to functions such as sim, parsim, and batchsim, the CaptureErrors parameter is always enabled.

Behavior	CaptureErrors="off" (default)	CaptureErrors="on"
Issuing exceptions for simulation errors	The software issues exceptions for simulation errors. The exception stops both the simulation in which the error occurred and the function or script that invoked the simulation, if applicable.	The software does not issue exceptions for simulation errors. The simulation error stops the simulation. However, if a script or another function invoked the simulation, the simulation error does not interrupt the function or script execution.
Error reporting	Errors that occur during simulation are reported in the MATLAB Command Window.	Information about the simulation errors, including the message and the simulation phase in which the error occurred, is captured in the simulation output.
Simulation results	Issuing an exception stops the simulation immediately. The sim function does not return simulation results.	The sim function returns simulation results and metadata up to the simulation time at which the error occurred.

Example: simin = setModelParameter(simin,CaptureErrors="on") configures a single simulation run using the scalar SimulationInput object simin to capture simulation errors in the simulation output.

Example: sm = setModelParameter(sm,CaptureErrors="on") the simulation represented by the Simulation object sm to capture simulation errors in the simulation output.

Tips

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

• When you configure an individual simulation to capture simulation errors and when you run multiple simulations by specifying an array of SimulationInput objects, you can view information about the error and the simulation in the simulation results.

  • 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 in which the error occurred.

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.

Example: simin = setModelParameter(simin,RapidAcceleratorUpToDateCheck="off") configures a SimulationInput object to disable rebuilding the rapid accelerator target.

Example: sm = setModelParameter(sm,RapidAcceleratorUpToDateCheck="off") disables the rapid accelerator up-to-date check in the simulation represented by the Simulation object sm.

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.

Example: simin = setModelParameter(simin,TimeOut=60) sets a maximum run time of 60 seconds in the simulation configuration stored on the SimulationInput object simin.

Example: sm = setModelParameter(sm,TimeOut=60) sets a maximum run time of 60 seconds in the simulation represented by the Simulation object sm.

Data Types: char | string

Output Arguments

s — Simulation specification or simulation with model parameter added or modified

Simulink.SimulationInput object | Simulation object

Simulation specification or simulation with model parameter added or modified, returned as a Simulink.SimulationInput object or a Simulation object.

When you use the setModelParameter function to specify the value of a model parameter on a SimulationInput object, you must specify the SimulationInput object as the return argument.

When you use the setModelParameter function to specify the value of a model parameter on a Simulation object, assigning the return argument is optional.

Tips

• Use the getModelParameter function to get the value of a parameter specified on a SimulationInput object or a Simulation object.

  paramval = getModelParameter(s,"ParamName");

• Use the removeModelParameter function to remove a model parameter from a SimulationInput object or a Simulation object.

  s = removeModelParameter(s,"ParamName");

Version History

Introduced in R2017a

R2024a: Tune model parameters during scripted simulations using the Simulation object

The Simulation object represents a simulation and provides an interface to control simulation execution and tune model parameter, block parameter, and variable values during simulation. You can use the setModelParameter function to specify model parameter values to use during simulation and to modify values of tunable model parameters during simulation.

R2024a: Enable fast restart for individual, iterative simulations

You can use the setModelParameter function to enable the FastRestart parameter on a SimlationInput object or a Simulation object. Fast restart saves time in iterative simulation workflows by skipping compilation and termination after compiling the model for the first simulation you run after enabling fast restart.

The FastRestart parameter applies only for individual simulations you run one at a time using the Simulation object or the sim function. To use fast restart when you run multiple simulations using an array of SimulationInput objects and the sim, parsim, or batchsim functions, specify the UseFastRestart name-value argument for the sim, parsim, or batchsim function.

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

R2024a: Consistent error handling for sim function with scalar SimulationInput object

In prior releases, the sim function overwrote the CaptureErrors parameter for a single simulation if you specified one or more name-value arguments in addition to the scalar SimulationInput object, including the StopOnError name-value argument. Now, the sim function has consistent default behavior and options, summarized in the table.

SimulationInput Dimensions	CaptureErrors	StopOnError	Behavior Change
scalar	"off" by default. To enable this parameter, specify the parameter on the SimulationInput object using the setModelParameter function.	This name-value argument has no effect when you run a single simulation.	Some calls to the sim function in scripts or functions from previous releases might not return a Simulink.SimulationOutput object when the same calls had returned the simulation output in previous releases. To restore the prior behavior, specify the CaptureErrors parameter as "on".
vector, matrix, array	Always "on".	"off" by default. Specify this name-value argument as "on" to skip subsequent simulations if a simulation error occurs.	No change.