We parallelize a three-dimensional Jacobi stencil over a regular Cartesian grid using tf::IndexRang and tf::Taskflow::for_each_by_index. This example demonstrates how multidimensional index ranges map naturally onto volumetric parallel workloads in scientific computing.
A stencil computation updates each interior cell of a 3D grid by combining the values of its six face-adjacent neighbors. The 7-point Jacobi stencil used here computes one iteration of the Laplacian smoother:
The computation reads from an input volume u and writes to a separate output volume v so that reads and writes do not interfere. Only interior cells are updated; the one-cell boundary layer is treated as a fixed Dirichlet condition and is never written. The sequential baseline is a straightforward triple loop:
Each interior cell is independent of every other interior cell within the same sweep, so all updates can be executed in parallel.
We represent the interior iteration space as a tf::IndexRange<int, 3> covering indices [1, Nx-1) x [1, Ny-1) x [1, Nz-1) and dispatch it with tf::Taskflow::for_each_by_index. The executor partitions the flat index space into axis-aligned sub-boxes and schedules them across available workers. Within each sub-box the kernel executes the same triple loop as the sequential version:
A single stencil sweep is rarely sufficient in practice. Iterating for a fixed number of steps requires swapping the input and output buffers after each sweep and re-running the same taskflow. Because tf::Taskflow::for_each_by_index captures u and v by reference, swapping the pointers before each run is sufficient:
The loop-based approach runs the taskflow from the host and re-enters the executor once per sweep. An alternative is to encode the iteration control entirely inside the task graph using a condition task, so the executor drives the full multi-sweep computation in a single run call.
The graph has two nodes: a parallel stencil task and a condition task that swaps the buffers and decides whether to loop back or stop:
The condition task returns 0 to jump back to stencil for the next sweep, or 1 to fall through and let the graph terminate. The back-edge from check to stencil forms the loop; Taskflow's scheduler re-activates stencil each time the condition returns 0 and the executor drives the entire multi-sweep computation in a single run call without re-entering from the host.
u, v, and iter can be plain (non-atomic) variables. The stencil task is fully complete before the condition task runs, so the swap and the counter increment are always sequenced correctly.There are a few important design points worth noting for this example, which also apply generally to parallel stencil algorithms:
u and writing to v prevents read-write races between workers. A single-buffer update would require a reduction or synchronization point between every pair of updated cells, which eliminates the parallelism.tf::IndexRange<int, 3> is defined over [1, N-1) in each dimension, not [0, N). This means the boundary halo is never written inside the parallel kernel, so there is no need for conditional boundary checks inside the inner loop. The boundary conditions are enforced implicitly by never touching those cells.tf::IndexRange<int,3>, Taskflow partitions the flat index space into axis-aligned sub-boxes rather than arbitrary flat ranges. Each sub-box delivered to the kernel is a geometrically contiguous region of the grid, which preserves spatial locality and benefits from cache reuse across the innermost dimension. 
1.12.0