coder.loop.unrollAndJam

R2026b

Unroll and jam for-loops in generated code

Since R2023a

Syntax

coder.loop.unrollAndJam(loopID,unrollFactor)

Description

coder.loop.unrollAndJam(loopID,unrollFactor) prompts the code generator to unroll the loop identified by loopID by a factor of unrollFactor and combine the resulting inner loop computations across iterations into a single, larger inner loop body in the generated code.

Use this directive for perfectly nested loops, where all computation occurs in the innermost loop and the code contains no statements between loop levels. This directive is most effective for small, compute-dense loop bodies and helps remove loop overhead and improve data reuse. It can be less beneficial for large or complex loops. The loop size must be perfectly divisible by the unrollFactor argument. For more information about loop optimizations, see Optimize Loops in Generated Code.

Examples

Unroll and Jam for-Loop in Generated Code

Examine the function loopUnrollAndJam, which uses a local function to compute i^2+j^2 for each element of a matrix. The function uses the coder.loop.unrollAndJam directive to unroll and combine the computations inside the for-loop.

function out = loopUnrollAndJam %#codegen
out = zeros(10);

coder.loop.unrollAndJam("i",5);
for i = 1:10
    for j = 1:10
        out(i,j) = out(i,j) + local(i,j);
    end
end
end

function y = local(x,z)
y = x^2 + z^2;
end

Generate a C static library for this function.

codegen -config:lib -report loopUnrollAndJam

Open the code generation report and inspect the generated code for the function. The code generator unrolls the outer loop and merges the operations from each unrolled iteration into a single inner loop.

for (i = 0; i <= 5; i += 5) {
    for (j = 0; j < 10; j++) {
      int b_out_tmp;
      int out_tmp;
      out_tmp = i + 10 * j;
      b_out_tmp = (j + 1) * (j + 1);
      out[out_tmp] += (double)((i + 1) * (i + 1) + b_out_tmp);
      out[out_tmp + 1] += (double)((i + 2) * (i + 2) + b_out_tmp);
      out[out_tmp + 2] += (double)((i + 3) * (i + 3) + b_out_tmp);
      out[out_tmp + 3] += (double)((i + 4) * (i + 4) + b_out_tmp);
      out[out_tmp + 4] += (double)((i + 5) * (i + 5) + b_out_tmp);
    }
  }

Input Arguments

loopID — Index name for for-loop to unroll and jam

string scalar | character vector

Index name for the for-loop to unroll and jam, specified as a string scalar or character vector.

unrollFactor — Factor by which to unroll loop

2 (default) | integer

Factor by which to unroll the loop in the generated code, specified as an integer.

Limitations

• Because of internal, low-level optimizations during code generation, the generated code can contain an imperfectly nested loop, even when the corresponding loop in the MATLAB^® code is perfectly nested. Under these circumstances, the code generator cannot apply the unrollAndJam directive.

Tips

• To view potential issues that the code generator encounters when applying the coder.loop.unrollAndJam directive, review the Code Insights section of the code generation report. See Code Generation Reports.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2023a