setModelParameter

Set model parameter values for simulation using SimulationInput or Simulation object

collapse all in page

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.

example

Examples

collapse all

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

collapse all

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

collapse all

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.

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. When you simulate a model hierarchy, the configuration parameter values you specify apply to the top model.

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.

Tips

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.

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. By default, fast restart is disabled. For more information, see How Fast Restart Improves Iterative Simulations.

    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. For more information, see Script Iterative or Batch Simulations Using Fast Restart.

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

Simulation mode, specified as "normal", "accelerator", or "rapid-accelerator".

ValueDescription
"normal"

Run simulation using normal mode.

Normal mode simulations use the full model representation and provide the best support for interacting with the model during simulation.

Use normal mode for workflows that involve modifying the structure of your model between simulations. For best results, use normal mode for debugging simulations.

"accelerator"

Run simulation using accelerator mode.

Accelerator mode simulations generate an optimized representation of the model, called a simulation target, to use in simulation. The optimizations that improve the simulation performance can reduce the ability to interact with the model during simulation. Modifying the model between accelerator mode simulations can require regenerating the simulation target.

Use accelerator mode to speed up simulations in workflows that do not involve making structural changes to the model between simulations.

"rapid-accelerator"

Run simulation using rapid accelerator mode.

Rapid accelerator mode simulations generate a standalone executable to use for simulation. The standalone executable provides minimal support for interacting with the model during simulation. Modifying the model between rapid accelerator simulations can require rebuilding the standalone executable.

Use rapid accelerator mode for the fastest simulation execution when you modify the model between simulations only by tuning variable and parameter values. Tuning certain parameter values can require rebuilding the standalone executable.

For more information, see Choosing a Simulation Mode and Code Regeneration in Accelerated Models.

Example: simin = setModelParameter(simin,SimulationMode="rapid-accelerator") configures the simulation run using the SimulationInput object simin to use rapid accelerator mode.

Example: sm = setModelParameter(sm,SimulationMode="rapid-accelerator") configures the simulation represented by the Simulation object sm to simulate using rapid accelerator mode.

Tips

  • Visualization blocks update during simulation when you run simulations from a UI, such as the Simulink Editor, but do not update during simulation when you run rapid accelerator simulations programmatically.

  • To prevent rebuilding the standalone executable, you can disable the rapid accelerator up-to-date check by specifying the RapidAcceleratorUpToDateCheck parameter value as "off". With the up-to-date check disabled, changes you make that would require rebuilding the executable are ignored.

  • To simulate using rapid accelerator mode, you can specify "rapid" as a partial match for "rapid-accelerator". For more information about name-value arguments in MATLAB, see Validate Name-Value Arguments.

Data Types: char | string

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.

BehaviorCaptureErrors="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") configures 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

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

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

collapse all

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

expand all

See Also

Objects

Functions

Topics