While Iterator (Simulink Reference)

Repeatedly execute the contents of a subsystem at the current time step while a condition is satisfied.

Library

Ports & Subsystems / While Iterator Subsystem

Description

The While Iterator block, when placed in a subsystem, repeatedly executes the contents of the subsystem at the current time step while a specified condition is true.

Note Placing a While Iterator block in a subsystem makes it an atomic subsystem if it is not already an atomic subsystem.

You can use this block to implement the block-diagram equivalent of a C program while or do-while loop. In particular, the block's While loop style parameter allows you to choose either of the following while loop modes:

do-while

In this mode, the While Iterator block has one input, the while condition input, whose source must reside in the subsystem. At each time step, the block runs all the blocks in the subsystem once and then checks whether the while condition input is true. If the input is true, the iterator block runs the blocks in the subsystem again. This process continues as long as the while condition input is true and the number of iterations is less than or equal to the iterator block's Maximum number of iterations parameter.

while

In this mode, the iterator block has two inputs: a while condition input and an initial condition (IC) input. The source of the initial condition signal must be external to the while subsystem. At the beginning of the time step, if the IC input is true, the iterator block executes the contents of the subsystem and then checks the while condition input. If the while condition input is true, the iterator executes the subsystem again. This process continues as long as the while condition input is true and the number of iterations is less than or equal to the iterator block's Maximum number of iterations parameter. If the IC input is false at the beginning of a time step, the iterator does not execute the contents of the subsystem during the time step.

Note Unless you are certain that the while condition will become false at some point in the simulation, you should specify a maximum number of iterations to avoid endless loops, which can be broken only by terminating MATLAB.

The While Iterator block can optionally output the current iteration number, starting at 1. The following example uses this capability to compute N, where N is the first N integers whose sum is less than 100.

This example is the diagrammatic equivalent to the following pseudocode.

max_sum = 100;
sum = 0;
iteration_number = 0;
cond = (max_sum > 0);
while (cond != 0) {
    iteration_number = iteration_number + 1;
    sum = sum + iteration_number;
    if (sum > max_sum OR iteration_number > max_iterations) 
        cond = 0;
}

Data Type Support

Acceptable data inputs for the condition ports are any type supported by Simulink, as well as any fixed-point type, that includes a 0 value. For a discussion on the data types supported by Simulink, refer to Data Types Supported by Simulink in the Using Simulink documentation.

The While Iterator block's optional output port can output any of the following data types: double, int32, int16, or int8.

Parameters and Dialog Box

Maximum number of iterations: The maximum number of iterations allowed. A value of -1 allows any number of iterations as long as the while condition input is true. Note that if you specify -1 and the while condition never becomes false, the simulation will run forever. In this case, the only way to stop the simulation is to terminate the MATLAB process. Therefore, you should not specify -1 as the value of this parameter unless you are certain that the while condition will become false at some point in the simulation.
While loop style: Specifies the type of while loop implemented by this block. See the preceding block description for more information.
States when starting: Set this field to reset if you want the iterator block to reset the states of the blocks in the while subsystem to their initial values at the beginning of each time step (i.e., before executing the first loop iteration in the current time step). To cause the states of blocks in the subsystem to persist across time steps, set this field to held (the default).
Show iteration number port: If you select this check box (the default), the While Iterator block outputs its iteration value. This value starts at 1 and is incremented by 1 for each succeeding iteration.
Output data type: If you select the Show iteration number port check box (the default), this field is enabled. Use it to set the data type of the iteration number output to int32, int16, int8, or double.

Characteristics

Direct Feedthrough
No

Sample Time
Inherited from driving block

Scalar Expansion
No

Dimensionalized
No

Zero Crossing
No

Direct Feedthrough	No
Sample Time	Inherited from driving block
Scalar Expansion	No
Dimensionalized	No
Zero Crossing	No

Weighted Sample Time Math While Iterator Subsystem