

# Iterations

Iterative algorithms occur in many domains of data analysis, such as _machine learning_ or _graph analysis_. Such algorithms are crucial in order to realize the promise of Big Data to extract meaningful information out of your data. With increasing interest to run these kinds of algorithms on very large data sets, there is a need to execute iterations in a massively parallel fashion.

Flink programs implement iterative algorithms by defining a **step function** and embedding it into a special iteration operator. There are two variants of this operator: **Iterate** and **Delta Iterate**. Both operators repeatedly invoke the step function on the current iteration state until a certain termination condition is reached.

Here, we provide background on both operator variants and outline their usage. The [programming guide](index.html) explains how to implement the operators in both Scala and Java. We also support both **vertex-centric and gather-sum-apply iterations** through Flink’s graph processing API, [Gelly](//ci.apache.org/projects/flink/flink-docs-release-1.7/dev/libs/gelly/index.html).

The following table provides an overview of both operators:

|  | Iterate | Delta Iterate |
| --- | --- | --- |
| **Iteration Input** | **Partial Solution** | **Workset** and **Solution Set** |
| **Step Function** | Arbitrary Data Flows |
| **State Update** | Next **partial solution** | 

*   Next workset
*   **Changes to solution set**

 |
| **Iteration Result** | Last partial solution | Solution set state after last iteration |
| **Termination** | 

*   **Maximum number of iterations** (default)
*   Custom aggregator convergence

 | 

*   **Maximum number of iterations or empty workset** (default)
*   Custom aggregator convergence

 |

## Iterate Operator

The **iterate operator** covers the _simple form of iterations_: in each iteration, the **step function** consumes the **entire input** (the _result of the previous iteration_, or the _initial data set_), and computes the **next version of the partial solution** (e.g. `map`, `reduce`, `join`, etc.).

![Iterate Operator](../img/iterations_iterate_operator.png)

1.  **Iteration Input**: Initial input for the _first iteration_ from a _data source_ or _previous operators_.
2.  **Step Function**: The step function will be executed in each iteration. It is an arbitrary data flow consisting of operators like `map`, `reduce`, `join`, etc. and depends on your specific task at hand.
3.  **Next Partial Solution**: In each iteration, the output of the step function will be fed back into the _next iteration_.
4.  **Iteration Result**: Output of the _last iteration_ is written to a _data sink_ or used as input to the _following operators_.

There are multiple options to specify **termination conditions** for an iteration:

*   **Maximum number of iterations**: Without any further conditions, the iteration will be executed this many times.
*   **Custom aggregator convergence**: Iterations allow to specify _custom aggregators_ and _convergence criteria_ like sum aggregate the number of emitted records (aggregator) and terminate if this number is zero (convergence criterion).

You can also think about the iterate operator in pseudo-code:



```
IterationState state = getInitialState();

while (!terminationCriterion()) {
	state = step(state);
}

setFinalState(state);
```



See the **[Programming Guide](index.html)** for details and code examples.

### Example: Incrementing Numbers

In the following example, we **iteratively increment a set numbers**:

![Iterate Operator Example](../img/iterations_iterate_operator_example.png)

1.  **Iteration Input**: The initial input is read from a data source and consists of five single-field records (integers `1` to `5`).
2.  **Step function**: The step function is a single `map` operator, which increments the integer field from `i` to `i+1`. It will be applied to every record of the input.
3.  **Next Partial Solution**: The output of the step function will be the output of the map operator, i.e. records with incremented integers.
4.  **Iteration Result**: After ten iterations, the initial numbers will have been incremented ten times, resulting in integers `11` to `15`.



```
// 1st           2nd                       10th
map(1) -> 2      map(2) -> 3      ...      map(10) -> 11
map(2) -> 3      map(3) -> 4      ...      map(11) -> 12
map(3) -> 4      map(4) -> 5      ...      map(12) -> 13
map(4) -> 5      map(5) -> 6      ...      map(13) -> 14
map(5) -> 6      map(6) -> 7      ...      map(14) -> 15
```



Note that **1**, **2**, and **4** can be arbitrary data flows.

## Delta Iterate Operator

The **delta iterate operator** covers the case of **incremental iterations**. Incremental iterations **selectively modify elements** of their **solution** and evolve the solution rather than fully recompute it.

Where applicable, this leads to **more efficient algorithms**, because not every element in the solution set changes in each iteration. This allows to **focus on the hot parts** of the solution and leave the **cold parts untouched**. Frequently, the majority of the solution cools down comparatively fast and the later iterations operate only on a small subset of the data.

![Delta Iterate Operator](../img/iterations_delta_iterate_operator.png)

1.  **Iteration Input**: The initial workset and solution set are read from _data sources_ or _previous operators_ as input to the first iteration.
2.  **Step Function**: The step function will be executed in each iteration. It is an arbitrary data flow consisting of operators like `map`, `reduce`, `join`, etc. and depends on your specific task at hand.
3.  **Next Workset/Update Solution Set**: The _next workset_ drives the iterative computation and will be fed back into the _next iteration_. Furthermore, the solution set will be updated and implicitly forwarded (it is not required to be rebuild). Both data sets can be updated by different operators of the step function.
4.  **Iteration Result**: After the _last iteration_, the _solution set_ is written to a _data sink_ or used as input to the _following operators_.

The default **termination condition** for delta iterations is specified by the **empty workset convergence criterion** and a **maximum number of iterations**. The iteration will terminate when a produced _next workset_ is empty or when the maximum number of iterations is reached. It is also possible to specify a **custom aggregator** and **convergence criterion**.

You can also think about the iterate operator in pseudo-code:



```
IterationState workset = getInitialState();
IterationState solution = getInitialSolution();

while (!terminationCriterion()) {
	(delta, workset) = step(workset, solution);

	solution.update(delta)
}

setFinalState(solution);
```



See the **[programming guide](index.html)** for details and code examples.

### Example: Propagate Minimum in Graph

In the following example, every vertex has an **ID** and a **coloring**. Each vertex will propagate its vertex ID to neighboring vertices. The **goal** is to _assign the minimum ID to every vertex in a subgraph_. If a received ID is smaller then the current one, it changes to the color of the vertex with the received ID. One application of this can be found in _community analysis_ or _connected components_ computation.

![Delta Iterate Operator Example](../img/iterations_delta_iterate_operator_example.png)

The **initial input** is set as **both workset and solution set.** In the above figure, the colors visualize the **evolution of the solution set**. With each iteration, the color of the minimum ID is spreading in the respective subgraph. At the same time, the amount of work (exchanged and compared vertex IDs) decreases with each iteration. This corresponds to the **decreasing size of the workset**, which goes from all seven vertices to zero after three iterations, at which time the iteration terminates. The **important observation** is that _the lower subgraph converges before the upper half_ does and the delta iteration is able to capture this with the workset abstraction.

In the upper subgraph **ID 1** (_orange_) is the **minimum ID**. In the **first iteration**, it will get propagated to vertex 2, which will subsequently change its color to orange. Vertices 3 and 4 will receive **ID 2** (in _yellow_) as their current minimum ID and change to yellow. Because the color of _vertex 1_ didn’t change in the first iteration, it can be skipped it in the next workset.

In the lower subgraph **ID 5** (_cyan_) is the **minimum ID**. All vertices of the lower subgraph will receive it in the first iteration. Again, we can skip the unchanged vertices (_vertex 5_) for the next workset.

In the **2nd iteration**, the workset size has already decreased from seven to five elements (vertices 2, 3, 4, 6, and 7). These are part of the iteration and further propagate their current minimum IDs. After this iteration, the lower subgraph has already converged (**cold part** of the graph), as it has no elements in the workset, whereas the upper half needs a further iteration (**hot part** of the graph) for the two remaining workset elements (vertices 3 and 4).

The iteration **terminates**, when the workset is empty after the **3rd iteration**.

[](#supersteps)

## Superstep Synchronization

We referred to each execution of the step function of an iteration operator as _a single iteration_. In parallel setups, **multiple instances of the step function are evaluated in parallel** on different partitions of the iteration state. In many settings, one evaluation of the step function on all parallel instances forms a so called **superstep**, which is also the granularity of synchronization. Therefore, _all_ parallel tasks of an iteration need to complete the superstep, before a next superstep will be initialized. **Termination criteria** will also be evaluated at superstep barriers.

![Supersteps](../img/iterations_supersteps.png)

