setModelParameter

R2026b

Set model parameter values for simulation using Simulink.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 Simulink.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 Simulink.SimulationInput or Simulation object. The parameter values you specify override the values saved in the model for simulations you run using the Simulink.SimulationInput or Simulation object during simulation and are reverted when the simulation completes. You can use a Simulink.SimulationInput or Simulation object to override any number of parameter values.

example

Examples

collapse all

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

Open the model.

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

Create a Simulink.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.

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.

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

Simulation Specification

A Simulink.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 Simulink.SimulationInput object:

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

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

Simulation

A 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.

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.

Example: simin = setModelParameter(simin,Timeout="100") configures a Simulink.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 Simulink.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 Simulink.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 Simulink.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 simulations, specified as "on" or "off". 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.

  • "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.

    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. To terminate the simulation, disable fast restart. For more information, see Script Iterative or Batch Simulations Using Fast Restart.

  • "off" — The simulation disables the FastRestart parameter in the model and runs without using fast restart. The model compiles for each simulation.

    If the model is already initialized in fast restart, the sim function terminates the previous simulation before compiling the model.

This parameter affects only individual simulations run using:

  • The sim function with a scalar Simulink.SimulationInput object

  • A Simulation object

By default, fast restart is disabled in models, and simulations you run using the sim function do not enable fast restart. If you do not specify this argument, the sim function uses the value of the parameter in the model.

When you run multiple simulations by specifying an array of Simulink.SimulationInput objects as an input to functions such as sim, parsim, and batchsim, enable fast restart by specifying the UseFastRestart name-value argument. For more information, see Script Iterative or Batch Simulations Using Fast Restart.

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

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

Data Types: char | string

Simulation mode, specified as "normal", "accelerator", or "rapid-accelerator". If you do not specify this argument, the simulation uses the simulation mode specified in the model.

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 simulation target to use for simulation. The simulation target provides minimal support for interacting with the model during simulation. Modifying the model between rapid accelerator simulations can require rebuilding the simulation target.

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 simulation target.

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 Simulink.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 simulation target, 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 simulation target 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 Simulink.SimulationInput object

  • A Simulation object

When you run multiple simulations by specifying an array of Simulink.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 script or function that invoked the simulation, if applicable.

The software does not issue exceptions for simulation errors.

If a script or another function invoked the simulation, the error stops the simulation but does not stop the execution of the script or function.

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 Simulink.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.

  • View information about captured errors in the simulation output and metadata.

    • The sim function captures the error in the ErrorMessage property of the Simulink.SimulationOutput object.

      msg = out.ErrorMessage;

    • To view the error message in the Diagnostic Viewer, use the sldiagviewer.reportSimulationMetadataDiagnostics function.

      sldiagviewer.reportSimulationMetadataDiagnostics(out)

    • The Simulink.SimulationMetadata object returned by the simulation contains additional information about the error, such as the simulation phase in which the error occurred. The error information is stored in the ErrorDiagnostic field of the ExecutionInfo property.

      e = out.SimulationMetadata.ExecutionInfo.ErrorDiagnostic;

Data Types: char | string

Option to disable rebuilding rapid accelerator target, specified as "on" or "off".

  • "on" — Before each simulation, the software checks whether any changes to the model require rebuilding the rapid accelerator target. If a change requires rebuilding the rapid accelerator target, the software rebuilds the target before running the simulation.

  • "off" — The software does not check whether changes to the model require rebuilding the rapid accelerator target and always runs the simulation without rebuilding the target. Changes to the model that require rebuilding the rapid accelerator target are ignored and are not reflected in the simulation.

Example: simin = setModelParameter(simin,RapidAcceleratorUpToDateCheck="off") configures a Simulink.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 Simulink.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 Simulink.SimulationInput object, you must specify the Simulink.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 Simulink.SimulationInput object or a Simulation object.

    paramval = getModelParameter(s,"ParamName");

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

    s = removeModelParameter(s,"ParamName");

Version History

Introduced in R2017a

expand all

See Also

Objects

Functions

Topics