Single-Precision Conversion Best Practices

Use Integers for Index Variables

In MATLAB^® code that you want to convert to single precision, it is a best practice to use integers for index variables. However, if the code does not use integers for index variables, when possible single-precision conversion using codegen with -double2single tries to detect the index variables and select int32 types for them.

Limit Use of `assert` Statements

Do not use assert statements to define the properties of input arguments.
Do not use assert statements to test the type of a variable. For example, do not use
```
assert(isa(a, 'double'))
```

Initialize MATLAB Class Properties in Constructor

Do not initialize MATLAB class properties in the properties block. Instead, use the constructor to initialize the class properties.

Provide a Test File That Calls Your MATLAB Function

Separate your core algorithm from other code that you use to test and verify the results. Create a test file that calls your double-precision MATLAB algorithm. You can use the test file to:

Automatically define properties of the top-level function inputs.
Verify that the double-precision algorithm behaves as you expect. The double-precision behavior is the baseline against which you compare the behavior of the single-precision versions of your algorithm.
Compare the behavior of the single-precision version of your algorithm to the double-precision baseline.

For best results, the test file must exercise the algorithm over its full operating range.

Prepare Your Code for Code Generation

MATLAB code that you want to convert to single precision must comply with code generation requirements. See MATLAB Programming for Code Generation.

To help you identify unsupported functions or constructs in your MATLAB code, add the %#codegen pragma to the top of your MATLAB file. When you edit your code in the MATLAB editor, the MATLAB Code Analyzer flags functions and constructs that are not supported for code generation. See Check Code with the Code Analyzer. When you use the MATLAB Coder™ app, the app screens your code for code generation readiness. At the function line, you can use the Code Generation Readiness Tool. See Check Code by Using the Code Generation Readiness Tool.

Verify Double-Precision Code Before Single-Precision Conversion

Before you begin the single-precision conversion process, verify that you can successfully generate code from your double-precision MATLAB code. Generate and run a MEX version of your double-precision MATLAB code so that you can:

Detect and fix compilation issues.
Verify that the generated single-precision code behaves the same as the double-precision MATLAB code.

See Check for Issues in MATLAB Code Using MEX Functions.

Best Practices for Generation of Single-Precision C/C++ Code

When you generate single-precision C/C++ code by using the MATLAB Coder app or codegen with the -singleC option, follow these best practices:

Avoid Using the C89/C90 (ANSI) Language Standard

If you generate single precision C/C++ libraries or executables using the C89/C90 (ANSI) language standard, the code generator produces a warning if a function in this library uses double precision. To avoid this warning, use one of the other available language standards. See Warnings from Conversion to Single-Precision C/C++ Code.

Cast Large Double Constant to Integer

For a constant greater than 2^24, in your original double-precision MATLAB function, cast the constant to an integer type that is large enough for the constant value. For example:

a = int32(2^24 + 1);

Generate and Run Single-Precision MEX Before Generating Single-Precision C/C++ Code

Before you generate single-precision C code, generate and run a single-precision MEX version of your MATLAB code. When you follow this practice, you can detect and fix compiler issues. You can verify that the single-precision MEX function has the same functionality as the MATLAB code.

If you use codegen with -singleC:

Generate the single-precision MEX.
Call coder.runTest to run your test file, replacing calls to the double-precision MATLAB code with calls to the single-precision MEX code.

If you use the MATLAB Coder app, perform the Check for Run-Time Issues step with single-precision conversion enabled.

Best Practices for Generation of Single-Precision MATLAB Code

When you use codegen with the -double2single option to generate single-precision MATLAB code, follow these best practices:

Use the `-args` Option to Specify Input Properties

When you generate single-precision MATLAB code, if you specify a test file, you do not have to specify argument properties with the -args option. In this case, the code generator runs the test file to determine the properties of the input types. However, running the test file can slow the code generation. It is a best practice to determine the input properties one time with coder.getArgTypes. Then, pass the properties to the -args option. For example:

types = coder.getArgTypes('myfun_test', 'myfun');
scfg = coder.config('single');
codegen -double2single scfg -args types myfun -report

When you repeat the code generation in the same MATLAB session, this practice saves you time.

Test Numerics and Log I/O Data

When you use the codegen function with the -double2single option to generate single-precision MATLAB code, enable numerics testing and I/O data logging for comparison plots. To use numerics testing, you must provide a test file that calls your MATLAB function. To enable numerics testing and I/O data logging, create a coder.SingleConfig object. Set the TestBenchName, TestNumerics, and LogIOForComparisonPlotting properties. For example:

scfg = coder.config('single');
scfg.TestBenchName = 'mytest';
scfg.TestNumerics = true;
scfg.LogIOForComparisonPlotting = true;