Main Content

step

Advance simulation represented by Simulation object by specified amount

Since R2024a

collapse all in page

    Syntax

    finalstep = step(s)
    finalstep = step(s,NumberOfSteps=numsteps)
    finalstep = step(s,PauseTime=pausetime)

    Description

    finalstep = step(s) advances the simulation represented by the Simulation object s by one major time step and returns a logical value that indicates whether the step was the last in the simulation. The step function always pauses at the top of the next time step after advancing the simulation if the simulation has not advanced through the last time step. The behavior after advancing through the last time step depends on the simulation context:

    • In normal and accelerator mode simulations, the step function pauses after advancing through the last step.

    • In rapid accelerator and deployed simulations, the simulation stops if the step function advances the simulation through the last step.

    You can advance a simulation using the step function when the simulation status is inactive, initialized, or paused. If the simulation is not initialized, the step function initializes the simulation before advancing through the first major time step.

    The MATLAB® command prompt is unavailable while the step function advances the simulation.

    example

    finalstep = step(s,NumberOfSteps=numsteps) advances the simulation represented by the Simulation object s by the number of major time steps specified by numsteps.

    finalstep = step(s,PauseTime=pausetime) advances the simulation represented by the Simulation object s and pauses after the simulation reaches the time specified by pausetime.

    example

    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.

    Input Arguments

    collapse all

    Simulation to advance, specified as a Simulation object.

    Number of major time steps to advance simulation, specified as a positive scalar finite integer. When you do not specify this argument, the step function advances the simulation through one major time step.

    Example: finalStep = step(sm,NumberOfSteps=5) advances the simulation represented by the Simulation object sm by five major time steps.

    Time through which to advance simulation, specified in seconds as a scalar number. If the simulation has a major time step that exactly matches the value you specify, the simulation pauses at the top of the time step for the specified simulation time, before computing output values. If the simulation does not have a major time step that exactly matches the value you specify, the simulation pauses at the top of the first major time step after the simulation advances through the specified time.

    Example: finalStep = step(sm,PauseTime=5) advances the simulation represented by the Simulation object sm through a simulation time of five seconds. The simulation pauses at the top of the major time step that occurs at or after 5 seconds.

    Output Arguments

    collapse all

    Whether the simulation has advanced through the final step, returned as logical true (1) or false (0).

    • true or 1 — The simulation has advanced through the final time step.

    • false or 0 — The simulation has not advanced through the final time step.

    Version History

    Introduced in R2024a

    See Also

    Objects

    Functions

    Topics