Work with programming loops

Most of the time, you do not need to create an explicit loop. This is because Bifrost nodes auto-loop when the inputs are arrays, as described in Work with arrays. However, when you do need to create a loop, you can add a looping compound to the graph.

There are three types of looping compounds:

• An iterate loop processes multiple elements in sequence. It can pass intermediate values, such as an accumulated sum, forward to the next iteration using state ports.
• A for_each loop processes multiple elements in parallel. Because of auto-looping, you only need to use a for-each loop for particular situations, such as when you want to use the iteration counter in the loop computation.
• A do_while loop repeats a sub-graph until a condition is met. Note that the sub-graph is always executed once even when the condition is false.

Special port types on looping compounds

Ports on looping compounds can have special behaviors. Right-click on a port on the input or output node inside the compound to turn these behaviors on or off.

Iteration counters

Iteration counters are available for all loops. They let you use the index of the current iteration in your calculations inside the compound.

When you add a looping compound to a graph, there is a default iteration counter named current_index. You can create additional iteration counters of type long. Each counter is incremented independently every iteration.

Iteration indices start at 0 by default. You can initialize them to non-zero values by connecting the port on the outside of the compound, or by setting a value in the Parameter Editor. However, initializing them to non-zero values has no effect on the number of times that the loop is executed.

Iteration limits

Iteration limits are available for all loops. They limit the number of times that the loop is executed.

When you add a looping compound to a graph, there is a default iteration limit named max_iterations. You can create additional iteration limits of type long.

The actual number of times the loop is performed is the lowest value among all of:

• the values of any iteration-limit ports.
• the sizes of any array inputs connected to iteration-target ports.

Iteration targets

Iteration targets are available for for_each and iterate loops. These ports appear as an array on the outside of a compound, but as a single value on the inside. The compound evaluates once for every element of the array.

Note that the number of iterations may be lower if a smaller array is connected to a different iteration target, or if an iteration limit has a smaller value.

State ports

State ports are available for iterate and do_while loops. They are pairs of input and output ports that are matched so the output value is used as the input for the next iteration of the loop (but not the next execution of the compound). Use state ports when you need to use a result from the previous iteration of a loop, for example, to accumulate a value while the loop runs.

When you create a state port, you must specify its matching port.

Any input value or connection is treated as the initial value for the first iteration.

Looping condition

A single looping condition port is available in do_while loops. The loop always executes at least once, and the value connected to the looping condition determines whether the loop executes again.