coder.loop.Control Class

R2026b

Namespace: coder.loop

Loop optimizations in generated code

Since R2023a

Description

Use instances of the coder.loop.Control class to optimize MATLAB^® for-loops in the generated code. See Optimize Loops in Generated Code.

Creation

Description

loopSchedule = coder.loop.Control creates a loop control object with an empty transformSchedule property.

Use the methods of the coder.loop.Control class to add loop optimization directives to the loop control object. Provide the loop index name as input to each method.

Properties

transformSchedule — Loop optimization directive

coder.loop.Control object

Loop optimization directive, specified as a coder.loop.Control object. The coder.loop.Control object contains its own transformSchedule property, which is either empty or a coder.loop.Control object. Each method call adds a new loop optimization directive to the top-level schedule object. The call stores later directives recursively in the transformSchedule property. This forms a nested, chained sequence of directives. The code generator applies the directives in the order in which the user code calls the methods.

Methods

Public Methods

apply	loopSchedule.apply applies the loop directives in the loop control object to the for-loop that immediately follows the apply call.
interchange	loopSchedule = loopSchedule.interchange("loopA_ID","loopB_ID") adds an interchange directive to the loop control object for the loops with index names loopA_ID and loopB_ID. See coder.loop.interchange.
parallelize	loopSchedule = loopSchedule.parallelize("loopID") adds a parallelize directive to the loop control object with index name loopID. See coder.loop.parallelize.
reverse	loopSchedule = loopSchedule.reverse("loopID") adds a reverse directive to the loop control object for the loop with index name loopID. See coder.loop.reverse.
tile	loopSchedule = loopSchedule.tile("loopID","tileSize","newTileID") adds a tile directive to the loop control object for the loop with index name loopID. See coder.loop.tile.
unrollAndJam	loopSchedule = loopSchedule.unrollAndJam("loopID","unrollFactor") adds an unroll and jam directive to the loop control object for the loop with index name loopID. See coder.loop.unrollAndJam.
vectorize	loopSchedule = loopSchedule.vectorize("loopID") adds a vectorize directive to the loop control object for the loop with index name loopID. See coder.loop.vectorize.

Examples

Apply Parallelize and Vectorize Directives to for-Loops

Use the coder.loop.Control object to apply the parallelize and vectorize directives to for-loops in the generated code.

Examine the function combineDirectives. This function creates a coder.loop.Control object. It uses the parallelize and vectorize methods to parallelize the outer loop and vectorize the inner loop of the nested for-loops.

function out = combineDirectives %#codegen
A = rand(512,512);
B = rand(512,512);
C = rand(512,512);
out = zeros(512,512);

loopObj = coder.loop.Control;
loopObj = loopObj.parallelize("j");
loopObj = loopObj.vectorize("i");

loopObj.apply;
for j = 1:512
    for i = 1:512
       out(i,j) = A(i,j)*B(i,j)+C(i,j);
    end
end
end

Generate a C static library for this function.

codegen -config:lib -report combineDirectives

Open the code generation report and inspect the generated code. The code generator uses OpenMP to distribute outer loop iterations across multiple threads. Inside each thread, SIMD instructions vectorize the inner loop body to operate on multiple elements per iteration.

void combineDirectives(double out[262144])
{
  static double A[262144];
  static double B[262144];
  static double C[262144];
  __m128d r;
  __m128d r1;
  int b_i;
  int i;
  int j;
  if (!isInitialized_combineDirectives) {
    combineDirectives_initialize();
  }
  b_rand(A);
  b_rand(B);
  b_rand(C);
#pragma omp parallel for num_threads(omp_get_max_threads()) private(i, b_i, r, \
                                                                        r1)

  for (j = 0; j < 512; j++) {
    for (i = 0; i <= 510; i += 2) {
      b_i = i + (j << 9);
      r = _mm_loadu_pd(&A[b_i]);
      r1 = _mm_loadu_pd(&B[b_i]);
      r = _mm_mul_pd(r, r1);
      r1 = _mm_loadu_pd(&C[b_i]);
      r = _mm_add_pd(r, r1);
      _mm_storeu_pd(&out[b_i], r);
    }
  }
}

Tips

• Use a coder.loop.Control object to combine multiple loop optimization directives in a specific order. See Optimize Loops in Generated Code.

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