Main Content

General Code Generation Workflow

The general code generation workflow for the Statistics and Machine Learning Toolbox™ functions that are not the object functions of machine learning models is the same as the workflow described in MATLAB® Coder™. For details, see Get Started with MATLAB Coder (MATLAB Coder). To learn how to generate code for the object functions of machine learning models, see Introduction to Code Generation.

This example briefly explains the general code generation workflow as summarized in this flow chart:

General code generation workflow. Step 1: Define an entry-point function. Step 2: Generate code. Step 3: Verify the generated code.

Define Entry-Point Function

An entry-point function, also known as the top-level or primary function, is a function you define for code generation. Because you cannot call any function at the top level using codegen (MATLAB Coder), you must define an entry-point function that calls code-generation-enabled functions, and generate C/C++ code for the entry-point function by using codegen. All functions within the entry-point function must support code generation.

Add the %#codegen compiler directive (or pragma) to the entry-point function after the function signature to indicate that you intend to generate code for the MATLAB algorithm. Adding this directive instructs the MATLAB Code Analyzer to help you diagnose and fix violations that would cause errors during code generation. See Check Code with the Code Analyzer (MATLAB Coder).

For example, to generate code that estimates the interquartile range of a data set using iqr, define this function.

function r = iqrCodeGen(x) %#codegen
%IQRCODEGEN Estimate interquartile range 
%   iqrCodeGen returns the interquartile range of the data x, 
%   a single- or double-precision vector.
r = iqr(x);
end
You can allow for optional input arguments by specifying varargin as an input argument. For details, see Code Generation for Variable Length Argument Lists (MATLAB Coder) and Specify Variable-Size Arguments for Code Generation.

Generate Code

Set Up Compiler

To generate C/C++ code, you must have access to a compiler that is configured properly. MATLAB Coder locates and uses a supported, installed compiler. To view and change the default C compiler, enter:

mex -setup
For more details, see Change Default Compiler.

Generate Code Using codegen

After setting up your compiler, generate code for the entry-point function by using codegen (MATLAB Coder) or the MATLAB Coder app. To learn how to generate code using the MATLAB Coder app, see Generate MEX Functions by Using the MATLAB Coder App (MATLAB Coder).

To generate code at the command line, use codegen (MATLAB Coder). Because C and C++ are statically typed languages, you must determine the properties of all variables in the entry-point function at compile time. Specify the data types and sizes of all inputs of the entry-point function when you call codegen by using the -args option.

  • To specify the data type and exact input array size, pass a MATLAB expression that represents the set of values with a certain data type and array size. For example, to specify that the generated code from iqrCodeGen.m must accept a double-precision numeric column vector with 100 elements, enter:

    testX = randn(100,1);
    codegen iqrCodeGen -args {testX} -report

    The -report flag generates a code generation report. See Code Generation Reports (MATLAB Coder).

  • To specify that at least one of the dimensions can have any length, use the -args option with coder.typeof (MATLAB Coder) as follows.

    -args {coder.typeof(example_value, size_vector, variable_dims)}
    The values of example_value, size_vector, and variable_dims specify the properties of the input array that the generated code can accept.

    • An input array has the same data type as the example values in example_value.

    • size_vector is the array size of an input array if the corresponding variable_dims value is false.

    • size_vector is the upper bound of the array size if the corresponding variable_dims value is true.

    • variable_dims specifies whether each dimension of the array has a variable size or a fixed size. A value of true (logical 1) means that the corresponding dimension has a variable size; a value of false (logical 0) means that the corresponding dimension has a fixed size.

    Specifying a variable-size input is convenient when you have data with an unknown number of observations at compile time. For example, to specify that the generated code from iqrCodeGen.m can accept a double-precision numeric column vector of any length, enter:

    testX = coder.typeof(0,[Inf,1],[1,0]);
    codegen iqrCodeGen -args {testX} -report

    0 for the example_value value implies that the data type is double because double is the default numeric data type of MATLAB. [Inf,1] for the size_vector value and [1,0] for the variable_dims value imply that the size of the first dimension is variable and unbounded, and the size of the second dimension is fixed to be 1.

    Note

    Specification of variable size inputs can affect performance. For details, see Control Memory Allocation for Variable-Size Arrays (MATLAB Coder).

  • To specify a character array, such as supported name-value pair arguments, specify the character array as a constant using coder.Constant (MATLAB Coder). For example, suppose that 'Name' is a valid name-value pair argument for iqrCodeGen.m, and the corresponding value value is numeric. Then enter:

    codegen iqrCodeGen -args {testX,coder.Constant('Name'),value} -report

For more details, see Generate C Code at the Command Line (MATLAB Coder) and Specify Properties of Entry-Point Function Inputs (MATLAB Coder).

Build Type

MATLAB Coder can generate code for these types:

  • MEX (MATLAB Executable) function

  • Standalone C/C++ code

  • Standalone C/C++ code compiled to a static library

  • Standalone C/C++ code compiled to a dynamically linked library

  • Standalone C/C++ code compiled to an executable

You can specify the build type using the -config option of codegen (MATLAB Coder). For more details on setting code generation options, see Configure Build Settings (MATLAB Coder).

By default, codegen generates a MEX function. A MEX function is a C/C++ program that is executable from MATLAB. You can use a MEX function to accelerate MATLAB algorithms and to test the generated code for functionality and run-time issues. For details, see MATLAB Algorithm Acceleration (MATLAB Coder) and Why Test MEX Functions in MATLAB? (MATLAB Coder).

Code Generation Report

You can use the -report flag to produce a code generation report. This report helps you debug code generation issues and view the generated C/C++ code. For details, see Code Generation Reports (MATLAB Coder).

Verify Generated Code

Test a MEX function to verify that the generated code provides the same functionality as the original MATLAB code. To perform this test, run the MEX function using the same inputs that you used to run the original MATLAB code, and then compare the results. Running the MEX function in MATLAB before generating standalone code also enables you to detect and fix run-time errors that are much harder to diagnose in the generated standalone code. For more details, see Why Test MEX Functions in MATLAB? (MATLAB Coder).

Pass some data to verify whether iqr, iqrCodeGen, and iqrCodeGen_mex return the same interquartile range.

testX = randn(100,1);
r = iqr(testX);
r_entrypoint = iqrCodeGen(testX);
r_mex = iqrCodeGen_mex(testX);

Compare the outputs by using isequal.

isequal(r,r_entrypoint,r_mex)

isequal returns logical 1 (true) if all the inputs are equal.

You can also verify the MEX function using a test file and coder.runTest (MATLAB Coder). For details, see Testing Code Generated from MATLAB Code (MATLAB Coder).

See Also

(MATLAB Coder)

Related Topics