coder.const

Write a function AddShift that takes a scalar double input Shift and adds it to the elements of a constant vector that the function generates. The vector consists of the squares of the first 10 natural numbers.

function y = AddShift(Shift) %#codegen
y = (1:10).^2 + Shift;
end

Generate C source code for AddShift using the codegen command. To improve the readability of the generated code, disable generation of SIMD instructions for the purposes of this example.

cfg = coder.config("lib");
cfg.InstructionSetExtensions = "None";
cfg.GenCodeOnly = true;
codegen -config cfg AddShift -args 0 -launchreport

Open the code generation report and inspect he generated AddShift function. This function contains instructions for creating the constant vector elements:

void AddShift(double Shift, double y[10])
{
  int k;
  for (k = 0; k < 10; k++) {
    y[k] = (double)((k + 1) * (k + 1)) + Shift;
  }
}

In your MATLAB^® code, replace the expression:

(1:10).^2

with:

coder.const((1:10).^2)

The code generator now hard-codes the vector containing the squares of the first 10 natural numbers in the body of the generated function:

void AddShift(double Shift, double y[10])
{
  static const signed char iv[10] = {1, 4, 9, 16, 25, 36, 49, 64, 81, 100};
  int i;
  for (i = 0; i < 10; i++) {
    y[i] = Shift + (double)iv[i];
  }
}

Write a function getsine that takes an integer input index and returns the element referred to by index from a lookup table of sines. The function getsine creates the lookup table calling another function gettable that you will create in the next step.

function y = getsine(index) %#codegen
tbl = gettable(1024);
y = tbl(index);
end

Create the function gettable that returns the lookup table of sines.

function y = gettable(n)
y = zeros(1,n);
for i = 1:n
    y(i) = sin((i-1)/(2*pi*n));
end

Generate C source code for getsine. Specify the input to be a scalar of type int32.

codegen -config:lib -c getsine -args int32(0) -launchreport

Open the code generation report. Observe that the generated code contains instructions for creating the lookup table.

In your MATLAB code, replace the statement:

tbl = gettable(1024);

with:

tbl = coder.const(gettable(1024));

Generate code for getsine again. The array of sine values is now hardcoded in the generated code.

Write a function MultiplyConst that takes an input factor and multiplies every element of two constant vectors vec1 and vec2 with factor. The function generates vec1 and vec2 using another function EvalConsts that you will define in the next step.

function [y1,y2] = MultiplyConst(factor) %#codegen
[vec1,vec2] = EvalConsts(pi.*(1./2.^(1:10)),2);
y1 = vec1.*factor;
y2 = vec2.*factor;
end

Define the EvalConsts function in a separate file.

function [f1,f2] = EvalConsts(z,n)
f1 = z.^(2*n)/factorial(2*n);
f2 = z.^(2*n+1)/factorial(2*n+1);
end

Generate C source code for MultiplyConst using the codegen command.

codegen -config:lib -c -launchreport MultiplyConst -args 0

Open the code generation report. The code generator produces the code for creating the two constant vectors.

In your MATLAB code, replace the statement:

[vec1,vec2] = EvalConsts(pi.*(1./2.^(1:10)),2);

with:

[vec1,vec2] = coder.const(@EvalConsts,pi.*(1./2.^(1:10)),2);

Generate code again by calling the same codegen command. The generated function does not contain code for creating the vectors. Instead, the code generator calculates the constant vectors and includes the calculated vectors in the generated function.

For example, consider this function, which uses coder.extrinsic to force the code generator to execute a computationally expensive call to besselj extrinsically at code generation time. The function also uses coder.extrinsic to call readmatrix, which is not supported for code generation. During code generation, the code generator reads the file mytable.txt and calculates the Bessel function. The code generator includes zTable and jTable in the generated code as constants.

function out = forceConstFold(in) %#codegen
coder.extrinsic("besselj","readmatrix");
zTable = coder.const(readmatrix("mytable.txt"));
jTable = coder.const(besselj(3,zTable));
out = interp1(zTable,jTable,in);
end

Because the function uses coder.const to force the code generator to call both readmatrix and besselj at code generation time, both MEX generation and standalone code generation for this function succeed. In addition, because the extrinsic calls occur at code generation time, not run time, neither zTable nor jTable are an mxArray. However, because the code generator includes these variables in the generated code as constants, changes to the mytable.txt file after code generation are not reflected in the generated code.

Define a function returnConstantValue that returns a constant value of 10. However, this function also creates a text file myFile.txt that contains a message saying the function successfully returned the value 10.

function v = returnConstantValue
v = 10;
fileID = fopen('myFile.txt','w');
fprintf(fileID, 'Success: Returned %f\n', v);     
fclose(fileID);
end

Define an entry-point function testConstantFolding that calls returnConstantValue using coder.const.

function y = testConstantFolding
y = coder.const(returnConstantValue);
end

Generate C source code for the testConstantFolding function.

codegen -config:lib -c testConstantFolding -report

Open the code generation report and inspect the generated testConstantFolding C function.

double testConstantFolding(void)
{
  FILE *filestar;
  signed char fileid;
  boolean_T autoflush;
  if (!isInitialized_testConstantFolding) {
    testConstantFolding_initialize();
  }
  fileid = cfopen();
  filestar = fileManager(fileid, &autoflush);
  if (!(filestar == NULL)) {
    fprintf(filestar, "Success: Returned %f\n", 10.0);
    if (autoflush) {
      fflush(filestar);
    }
  }
  cfclose(fileid);
  return 10.0;
}

The generated function does return the constant value 10.0. However, even though the side-effect of returnConstantValue did not depend on run-time inputs, the code generator was unable to evaluate the call to returnConstantValue during code generation. Therefore, the generated code contains the instructions for creating the text file.

To force the code generator to evaluate the returnConstantValue call during code generation, declare this function as extrinsic in the body of the callee.

function y = testConstantFolding2
coder.extrinsic("returnConstantValue");
y = coder.const(returnConstantValue);
end

Generate C source code for the testConstantFolding2 function.

codegen -config:lib -c testConstantFolding2 -report

Because the code generator now evaluates the returnConstantValue call during code generation, the text file myFile.txt appears in your working directory.

Open the code generation report and inspect the generated testConstantFolding2 C function.

double testConstantFolding2(void)
{
  return 10.0;
}

The generated function only returns the value of the constant-folded expression. The instructions to carry out the side effects of the constant-folded expression do not appear in the generated code.