This example shows how to propose fixed-point data types based on static ranges that you specify. The advantage of proposing data types based on derived ranges is that you do not have to provide test files that exercise your algorithm over its full operating range. Running such test files often takes a very long time so you can save time by deriving ranges instead.
|On this page…|
To complete this example, you must install the following products:
C compiler (for most platforms, a default C compiler is supplied with MATLAB) For a list of supported compilers, see Supported Compilers
You can use mex -setup to change the default compiler. See Changing Default Compiler.
Create a New Folder and Copy Relevant Files
Create a local working folder, for example, c:\coder\dti.
Change to the docroot\toolbox\coder\examples folder. At the MATLAB command line, enter:
cd(fullfile(docroot, 'toolbox', 'coder', 'examples'))
Copy the dti.m and dti_test.m files to your local working folder.
It is best practice to create a separate test script to do all the pre- and post-processing such as loading inputs, setting up input values, calling the function under test, and outputting test results. For more information, see Create a Test File.
|Function code||dti.m||Entry-point MATLAB function|
|Test file||dti_test.m||MATLAB script that tests dti.m|
Check Code Generation Readiness
In the current working folder, right-click the dti.m function. From the context menu, select Check Code Generation Readiness.
The code generation readiness tool screens the code for features and functions that are not supported for code generation. The tool reports that the dti.m function is already suitable for code generation.
If your entry-point function is not suitable for code generation, the tool provides a report that lists the source files that contain unsupported features and functions. The report also provides an indication of how much work you must do to make the MATLAB code ready for code generation. Before proposing data types, you must fix these issues. For more information, see Detect and Debug Code Generation Errors.
Create and set up a MATLAB Coder Project
Navigate to the work folder that contains the file for this example.
On the MATLAB Apps tab, select MATLAB Coder and then, in the MATLAB Coder Project dialog box, set Name to dti.prj.
Alternatively, at the MATLAB command line, enter
coder -new dti.prj
By default, the project opens in the MATLAB workspace.
On the project Overview tab, click the Add files link. Browse to the file dti.m and then click OK to add the file to the project.
Define Input Types
On the project Overview tab, click the Autodefine types link.
In the Autodefine Input Types dialog box, add dti_test as a test file and then click Run.
The test file runs and displays the outputs of the filter for each of the input signals.
MATLAB Coder determines the input types from the test file and then displays them.
In the Autodefine Input Types dialog box, click Use These Types.
MATLAB Coder sets the type of x to double(1x1).
On the project Overview tab Fixed-Point Conversion pane, select Convert to fixed-point at build time.
The project indicates that you must first define the fixed-point data types.
In the Fixed-Point Conversion pane, click Define and validate fixed-point types.
The Fixed-Point Conversion window opens and the tool generates an instrumented MEX function for your entry-point MATLAB function. After generating the MEX function, the tool displays compiled information — type, size, and complexity — for variables in your code. For more information, see View and Modify Variable Information.
If the MEX function generation fails, the tool provides error message links to help you navigate to the code that caused the build issues. If your code contains functions that are not supported for fixed-point conversion, the tool displays these on the Function Replacements tab. For more information, see Running a Simulation.
In the Fixed-Point Conversion window, on the Variables tab, for input u_in, select Static Min and set it to -1. Then set Static Max to 1.
To compute derived range information, at a minimum you must specify static minimum and maximum values or proposed data types for all input variables.
Click the Compute Derived Ranges button.
Range analysis computes the derived ranges and displays them in the Variables tab. Using these derived ranges, the analysis proposes fixed-point types for each variable based on the default type proposal settings, and displays them in the Proposed Type column. The Validate Types option is now enabled.
In the dti function, the clip_status output has a minimum value of -2 and a maximum of 2.
% Compute Output if (u_state > limit_upper) y = limit_upper; clip_status = -2; elseif (u_state >= limit_upper) y = limit_upper; clip_status = -1; elseif (u_state < limit_lower) y = limit_lower; clip_status = 2; elseif (u_state <= limit_lower) y = limit_lower; clip_status = 1; else y = u_state; clip_status = 0; end
When you derive ranges, the Fixed-Point Conversion tool analyses the function and computes these minimum and maximum values for clip_status.
The tool provides a Quick derived range analysis option and the option to specify a timeout in case the analysis takes a very long time. For more information, see Computing Derived Ranges
To validate the build using the proposed types, click Validate Types.
The software validates the proposed types, displays a Validation succeeded message, and enables the Test Numerics option. The project indicates that you have validated the fixed-point data types.
If the errors or warnings occur during validation, they are displayed on the Type Validation Output tab. For more information, see Validating Types.
Run the test file to test the fixed-point MATLAB code. Click Test Numerics and select Log inputs and outputs for comparison plots, and then click the Test Numerics button.
The tool runs the test file that you used to define input types to test the fixed-point MATLAB code. Optionally, you can add test files and select to run more than one test file to test numerics. The software runs both a floating-point and a fixed-point simulation and then calculates the errors for the output variables y and clip_status. Because you selected to log inputs and outputs for comparison plots, the tool generates an additional plot for each scalar output.
Plots are displayed for the:
Floating-point input and output signals.
Fixed-point input and output signals.
Outputs y and clip_status showing the difference between the floating-point and the fixed-point runs.
The maximum difference between the floating-point and fixed-point runs for y is less than 5%. For the purpose of this example, this margin of error is acceptable, so you are ready to generate fixed-point C code.
If the difference is not acceptable, modify the fixed-point data types or your original algorithm. For more information, see Testing Numerics.
Generate Fixed-Point C Code
In the MATLAB Coder project, select the Build tab.
On this tab, set the Output type to C/C++ Static library.
The default output file name is dti.
Click Build to generate a library using the default project settings.
MATLAB Coder builds the project and generates a C static library and supporting files in the default subfolder, codegen/lib/dti_FixPt.
To view the generated code, click View report.
The code generation report opens and displays the generated code for dti_FixPt.c. In the generated C code, variables are assigned fixed-point data types.