Apply Fixed-Point Data Types Using an Instrumented Mex Function

This example shows how to write a fixed-point version of your entry-point function using the data types proposed in Propose Fixed-Point Data Types Using an Instrumented Mex Function.

This capability is not compatible with automatic fixed-point conversion. If you select Convert to fixed point at build time, you cannot build instrumented MEX functions.

You will learn how to:

  • Use the proposed data types to create a fixed-point version of your entry-point function.

  • Update your test file to call the fixed-point entry-point function.

  • Verify that the fixed-point function is functionally equivalent to the original MATLAB® algorithm.

Prerequisites

To complete this example, you must install the following products:

  • MATLAB

  • MATLAB Coder™

  • Fixed-Point Designer™

  • 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

  1. Create a local working folder, for example, c:\coder\fun_with_matlab.

  2. Change to the docroot\toolbox\coder\examples folder. At the MATLAB command line, enter:

    cd(fullfile(docroot, 'toolbox', 'coder', 'examples')) 
  3. Copy the following files to your local working folder.

    TypeNameDescription
    Function codefun_with_matlab.mEntry-point MATLAB function
    Test filefun_with_matlab_test.mMATLAB script that tests fun_with_matlab.m
    Function codefun_with_fi.mEntry-point MATLAB function — fixed-point version of fun_with_matlab that uses data types proposed in Propose Fixed-Point Data Types Using an Instrumented Mex Function
    Test filefun_with_fi_test.mMATLAB script that runs both fun_with_matlab and fun_with_fi and compares the results

The fun_with_fi Function

The fun_with_fi is a fixed-point version of the fun_with_matlab function that uses the data types proposed in Propose Fixed-Point Data Types Using an Instrumented Mex Function.

VariableProposed SignednessProposed Word LengthProposed Fraction Length
ySigned1614
xSigned1614
zSigned1615
aUnsigned1618
bSigned1614
iUnsigned160

For example, in fun_with_matlab, variable y is defined as y = zeros(size(x));. In fun_with_fi, to specify that it is a signed fixed-point data type with a word length of 16 and a fraction length of 14:

y = fi(zeros(size(x)),1,16,14,'OverflowAction','Wrap','RoundingMethod','Floor');

For more information, see fi.

 Contents of fun_with_fi

Create and set up a MATLAB Coder Project

  1. Navigate to the work folder that contains the file for this tutorial.

  2. On the MATLAB Apps tab, select MATLAB Coder and then, in the MATLAB Coder Project dialog box, set Name to fun_with_fi_project.prj.

    Alternatively, at the MATLAB command line, enter

    coder -new fun_with_fi_project.prj

    By default, the project opens in the MATLAB workspace.

  3. On the project Overview tab, click the Add files link. Browse to the file fun_with_fi.m, and then click OK to add the file to the project.

Define Input Types

  1. On the project Overview tab, click the Autodefine types link.

  2. In the Autodefine Input Types dialog box, add fun_with_fi_test as a test file, and then click Run.

    The test file runs and plots the outputs of the filter. MATLAB Coder determines the input types from the test file and then displays them.

  3. In the Autodefine Input Types dialog box, click Use These Types to accept the autodefined input type.

    MATLAB Coder sets the type of x to double(1x256).

The fun_with_fi_test Script

The fun_with_fi_test script runs the original floating-point MATLAB algorithm, fun_with_matlab, then runs the fixed-point version of the algorithm, fun_with_fi. The script then plots the outputs for the floating-point and fixed-point algorithms and the difference in results.

 Contents of fun_with_fi_test

Run Simulation

  1. In the project, click the Build tab.

  2. On the Verification pane, verify that the test file is set to fun_with_fi_test. Clear Redirect entry-point calls to MEX function so that the test file calls the MATLAB versions of the original and fixed-point algorithms.

  3. On Verification pane, click Run.

    The fun_with_fi_test file runs. The test file runs the original MATLAB algorithm and the fixed-point version, and plots the difference in their outputs.

  4. Optionally, zoom in on each plot in turn to view the error (difference between the two versions of the algorithm). In this example, the errors are very small, on the order of 10-3. If the error is unacceptably large, refine the fixed-point data types.

Was this topic helpful?