Main Content

simulation

Control simulation execution and tune variable, block parameter, and model parameter values

Since R2024a

expand all in page

    Description

    The Simulation object represents a simulation of a model and provides an interface to control the simulation. The Simulation object supports all simulation modes, including rapid accelerator, and deployment with Simulink® Compiler™. Simulation execution does not block the MATLAB® command prompt except when you advance the simulation by calling the step function.

    You can use a Simulation object to:

    • Initialize, start, and stop simulations.

    • Pause and step through simulations.

    • Tune variable, block parameter, and model parameter values before and during simulations.

    • Build custom apps to interact with simulations by using App Designer.

    For more information about building apps to interact with simulations, see Create App for Simulink Model.

    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.

    • Modifications that are never saved when you save a model, such as breakpoints and port value labels, do not apply to simulations run using the Simulation object.

    By controlling simulation execution programmatically, you can integrate the systems and algorithms implemented in Simulink models into MATLAB scripts. For example, if you step to a point in the middle of a simulation, you can use MATLAB code to analyze the simulation results up to that point to determine whether to modify parameter values, the new value for a parameter, or how far to advance the simulation before analyzing the results again.

    Creation

    Syntax

    s = simulation(mdlname)
    s = simulation(simin)

    Description

    s = simulation(mdlname) creates the Simulation object s for the model mdlname.

    example

    s = simulation(simin) creates the Simulation object s and sets property values according to the corresponding property values of the Simulink.SimulationInput object simin.

    Properties of the Simulink.SimulationInput object that do not have a corresponding property on the Simulation object are not applied to the Simulation object. For example, the Simulation object does not support or have property values for any of the callback functions you can specify on a SimulationInput object, including the callback functions, such as the external inputs callback function, that are available with Simulink Compiler.

    Input Arguments

    expand all

    Model name, specified as a string or a character vector.

    Data Types: char | string

    Simulation inputs and configuration, specified as a Simulink.SimulationInput object.

    Properties

    expand all

    Model Information

    This property is read-only.

    Name of model to simulate, returned as a string or a character vector.

    Option to load model automatically as needed, specified as logical true (1) or false (0).

    • true or 1 — The Simulation object automatically loads the model upon creation if the model is not already open or loaded. When you call a function that requires the model, such as the start or initialize function, the Simulation object checks that the model is loaded and loads the model if needed.

    • false or 0 — The Simulation object does not automatically load the model. If the model is not open or loaded when you perform an action that requires the model, such as starting or initializing the simulation, the software issues an error.

    Simulation Status and Results

    This property is read-only.

    Current simulation time, returned as a scalar number.

    Data Types: double

    This property is read-only.

    Simulation status, returned as a string that indicates the status of the simulation that corresponds to the Simulation object.

    • "inactive" — Simulation is not active and not initialized.

    • "initializing" — Simulation is initializing.

    • "initialized" — Simulation is initialized.

    • "paused" — Simulation is paused.

    • "running" — Simulation is actively running.

    • "stopping" — Simulation is stopping.

    • "terminating" — Simulation is terminating.

    • "restarting" — Simulation initialized in fast restart is restarting.

    Data Types: string

    This property is read-only.

    Simulation results, returned as a Simulink.SimulationOutput object. You can access the property value while the simulation status is paused or inactive.

    Simulation Configuration

    Initial state or operating point for simulation, specified using one of these options:

    By default, the property value is an empty Simulink.op.ModelOperatingPoint object. When you create the Simulation object using a Simulink.SimulationInput object, the property value matches the value of the InitialState property of the SimulationInput object.

    To specify the value of the InitialState property for a Simulation object, use the setInitialState function. The initial state specified in the InitialState property overrides the value saved in the model during simulation and is reverted when the simulation completes.

    When you do not specify an initial state for the InitialState property, the simulation uses the initial state saved in the model.

    External input data to load using top-level input ports, specified in a format supported by the Input parameter, such as a Simulink.SimulationData.Dataset object.

    By default, the property value is an empty double array ([]). When you create the Simulation object using a SimulationInput object, the property value matches the value of the ExternalInput property of the SimulationInput object.

    To specify the value of the ExternalInput property for a Simulation object, use the setExternalInput function.

    The external input data specified in the ExternalInput property overrides the input data parameter values saved in the model during simulation. The model is updated to load the specified external input data for the simulation, and the modifications revert when the simulation completes.

    When you do not specify external input data for the ExternalInput property, the simulation uses the value of the Input parameter saved in the model.

    Model parameter values specified for simulation, returned as an array of Simulink.Simulation.ModelParameter objects. To specify a model parameter value for a Simulation object or to tune a model parameter value during simulation, use the setModelParameter function. The setModelParameter function creates a ModelParameter object for each parameter you specify and adds the object to the array in the ModelParameters property.

    By default, the property value is an empty array of ModelParameter objects.

    When you create the Simulation object using a SimulationInput object, the property value specifies the same model parameters and values as the ModelParameters property of the Simulation object.

    The model parameter values specified in the ModelParameters property override the parameter values saved in the model during simulation and revert when the simulation completes.

    Block parameter values specified for simulation, returned as an array of Simulink.Simulation.BlockParameter objects. To specify the value of a block parameter for a Simulation object or to tune a block parameter value during simulation, use the setBlockParameter function. The setBlockParameter function creates a BlockParameter object for each block parameter you specify and adds the object to the array in the BlockParameters property.

    By default, the property value is an empty array of BlockParameter objects.

    When you create the Simulation object using a SimulationInput object, the property value specifies the same block parameters and values as the BlockParameters property of the SimulationInput object.

    The block parameter values specified in the BlockParameters property override the block parameter values saved in the model during simulation and revert when the simulation completes.

    Variable values specified for simulation, returned as an array of Simulink.Simulation.Variable objects. To specify the value of a variable for a Simulation object or to tune a variable value during simulation, use the setVariable function. The setVariable function creates a Variable object for each variable you specify and adds the object to the array in the Variables property.

    By default, the property value is an empty array of Variable objects.

    When you create the Simulation object from a SimulationInput object, the property value specifies the same variable values as the Variables property of the SimulationInput object.

    You can specify values for variables that the model accesses from the base workspace, a data dictionary, or the model workspace. The variable values you specify override the value of the variable saved in the base workspace, data dictionary, or model workspace during simulation and revert when the simulation completes.

    App Designer

    These properties support tuning variables and visualizing logged signal data in custom apps built using App Designer. For more information, see bind.

    This property is read-only.

    Run-to-run and run-time tunable variables, returned as a simulink.sim.Variables object. When you build an app in App Designer that interacts with a simulation, the TunableVariables property provides access to the variables you can tune using components in the app.

    The Variables object stores information about all variables used in the model or simulation that you can modify between simulations or during simulation. Whether a given variable is run-to-run or run-time tunable depends on the simulation configuration. Variable tunability depends on:

    • The simulation mode

    • Whether the simulation uses fast restart

    • Whether the simulation disables the rapid accelerator up-to-date check

    • Whether the simulation is deployed using Simulink Compiler

    To see the list of tunable variables for a Variables object, use the keys function.

    keys(s.TunableVariables)

    To tune a variable value, use the setVariable function.

    This property is read-only.

    Signals logged in model, returned as a Signals object.

    When you build an App Designer app that interacts with a simulation, use the LoggedSignals property to access logged data you can visualize in the app.

    Object Functions

    expand all

    initializeInitialize simulation represented by Simulation object
    startStart simulation represented by Simulation object
    stepAdvance simulation represented by Simulation object by specified amount
    pausePause active simulation represented by Simulation object
    resumeContinue paused simulation represented by Simulation object
    stopStop simulation represented by Simulation object
    terminateTerminate simulation represented by Simulation object

    expand all

    setExternalInputSpecify external input data for top-level input ports using SimulationInput or Simulation object
    setInitialStateSpecify initial state for simulation using SimulationInput or Simulation object
    setVariableSet variable values for simulation using SimulationInput or Simulation object
    setModelParameterSet model parameter values for simulation using SimulationInput or Simulation object
    setBlockParameterSet block parameter values for simulation using SimulationInput or Simulation object

    expand all

    setVariableSet variable values for simulation using SimulationInput or Simulation object
    setModelParameterSet model parameter values for simulation using SimulationInput or Simulation object
    setBlockParameterSet block parameter values for simulation using SimulationInput or Simulation object

    Examples

    collapse all

    Open Live Script

    Open the model vdp.

    mdl = "vdp";
open_system(mdl)

    The model vdp.

    Create a Simulation object to represent a simulation of the model.

    sm = simulation(mdl);

    The model vdp is small and simple and simulates very fast. Configure the simulation to run at a slower pace relative to real or wall clock time so the simulation runs long enough for you to interact with it. This code configures the simulation to run at a rate of approximately two simulation seconds per one second of real time.

    sm = setModelParameter(sm,EnablePacing="on");
sm = setModelParameter(sm,PacingRate="2");

    Configure the simulation to run to a stop time of 40 seconds.

    sm = setModelParameter(sm,StopTime="40");

    Check the simulation status by using the Status property. Before you start or initialize the simulation, the simulation status is inactive.

    sm.Status
    ans = 
"inactive"

    You can initialize the simulation without starting it. Initializing the simulation compiles the model and sets up resources, such as memory, for running the simulation. After you initialize the simulation, the simulation status is initialized. The Simulink® Editor locks to prevent modifications to the model or simulation by anything other than the Simulation object that controls the simulation.

    initialize(sm)
sm.Status
    ans = 
"initialized"

    Start the simulation and check the simulation status. Once the simulation starts, the status is running.

    start(sm)
sm.Status
    ans = 
"running"

    Because simulation execution does not block the MATLAB® command prompt, this example uses the MATLAB® pause function to mimic an interactive workflow. This pause command pauses the execution of the script to allow the simulation to run for five seconds.

    pause(5) % pause script execution

    Pause the simulation using the pause function for the Simulation object and check the simulation status. While paused, the simulation status is paused.

    pause(sm) % pause simulation
sm.Status
    ans = 
"paused"

    The plot in the Scope block updates during the simulation. Logged data also streams to the Simulation Data Inspector.

    The plot in the Scope block shows the values computed for the signals named x1 and x2 in the first 10 seconds of the simulation. The status bar in the Scope window indicates that the simulation is paused at a simulation time of approximately 10 seconds.

    Check the simulation time. While the script was paused for five seconds, the simulation advanced to a simulation time of approximately 10 seconds. The Time property value is not exactly 10 because:

    • The pacing rate of two simulation seconds per second of wall clock time is approximate.

    • The variable-step solver determines the major time hits in the simulation.

    sm.Time
    ans = 
10.0521

    Use the pause function to pause a running simulation on demand. To pause the simulation at or after a specific simulation time, use the step function with the PauseTime argument.

    For example, advance the simulation through a simulation time of 25 seconds.

    step(sm,PauseTime=25);

    Check the simulation time. The simulation pauses at the top of the first major time hit with a simulation time greater than or equal to the specified pause time.

    sm.Time
    ans = 
25.4339

    Because the simulation pauses at the top of the major time hit, output values are not available for the current simulation time. Check the time of the last value in the simulation outputs. 

    sm.SimulationOutput.yout{1}.Values.Time(end)
    ans = 
24.8081

    The status bar in the Scope window and the status bar in the Simulink® Editor both indicate the simulation time of the last output calculation.

    The plot in the Scope block shows the values computed for the signals named x1 and x2 through a simulation time of approximately 25 seconds.

    In the Simulink Editor, the asterisk next to the time indicates that the current simulation time is ahead of the time the status bar reports.

    The status bar shows that the simulation time T is 24.808 with an asterisk. Next to the simulation time, the progress bar shows the simulation progress and indicates that the simulation is currently paused.

    Advance the simulation through the current major time hit.

    step(sm);

    The output results are now available for the time hit.

    sm.SimulationOutput.yout{1}.Values.Time(end)
    ans = 
25.4339

    To continue the simulation, use the resume function.

    resume(sm)

    Because simulation execution does not block the MATLAB® command prompt, this example uses the MATLAB® pause function to mimic an interactive workflow. This pause command pauses the execution of the script to allow the simulation to run for five seconds.

    pause(5) % pause script execution

    To stop the simulation before the simulation completes, use the stop function. 

    out = stop(sm)
    out = 
  Simulink.SimulationOutput:
                   tout: [97x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

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

    Check the simulation status. Because the simulation did not enable fast restart, stopping the simulation also terminates the simulation. After stopping, the simulation status is inactive.

    sm.Status
    ans = 
"inactive"

    The stop function returns the Simulink.SimulationOutput object that contains the simulation results. You can also access the results from the SimulationOutput property of the Simulation object.

    outprop = sm.SimulationOutput
    outprop = 
  Simulink.SimulationOutput:
                   tout: [97x1 double] 
                   yout: [1x1 Simulink.SimulationData.Dataset] 

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

    When you run another simulation using the Simulation object sm, the results from the current simulation overwrite the SimulationOutput property.

    Version History

    Introduced in R2024a

    See Also

    Objects

    Functions

    Topics