Documentation Center

  • Trial Software
  • Product Updates

Contents

Automated Fixed-Point Conversion

License Requirements

Fixed-point conversion requires the following licenses:

  • Fixed-Point Designer™

  • MATLAB® Coder™

Automated Fixed-Point Conversion Capabilities

You can convert floating-point MATLAB code to fixed-point code using the Fixed-Point Conversion tool in MATLAB Coder projects. You can choose to propose data types based on simulation range data, derived (also known as static) range data, or both.

You can manually enter static ranges. These manually-entered ranges take precedence over simulation ranges and the tool uses them when proposing data types. In addition, you can modify and lock the proposed type so that the tool cannot change it. For more information, see Locking Proposed Data Types.

Automated fixed-point conversion supports:

During fixed-point conversion, you can:

  • Verify that your test files cover the full intended operating range of your algorithm using code coverage results.

  • Propose fraction lengths based on default word lengths.

  • Propose word lengths based on default fraction lengths.

  • Optimize whole numbers.

  • Specify safety margins for simulation min/max data.

  • Validate that you can build your project with the proposed data types.

  • Test numerics by running the test file with the fixed-point types applied.

  • View a histogram of bits used by each variable.

  • Detect overflows.

Code Coverage

By default, the Fixed-Point Conversion tool shows code coverage results. Your test files should exercise the algorithm over its full operating range so that the simulation ranges are accurate. The quality of the proposed fixed-point data types depends on how well the test files cover the operating range of the algorithm with the accuracy that you want. Reviewing code coverage results helps you verify that your test file is exercising the algorithm adequately. If the code coverage is inadequate, modify the test file or add more test files to increase coverage. If you simulate multiple test files in one run, the tool displays cumulative coverage. However, if you specify multiple test files but run them one at a time, the tool displays the coverage of the file that ran last.

Code coverage is on by default. Turn it off only after you have verified that you have adequate test file coverage. Turning off code coverage might speed up simulation. To turn off code coverage, in the Fixed-Point Conversion tool:

  1. Click Run Simulation.

  2. Clear Show code coverage.

The tool covers basic MATLAB control constructs and shows statement coverage for basic blocks of code. The tool displays a color-coded coverage bar to the left of the code.

Coverage Bar ColorHow Often Code is Executed During Test File Simulation
Dark greenAlways
Light greenSometimes
OrangeOnce
RedNever

When you position your cursor over the coverage bar, the color highlighting extends over the code and the tool displays more information about how often the code is executed. For MATLAB constructs that affect control flow (if-elseif-else, switch-case, for-continue-break, return), it displays statement coverage as a percentage coverage for basic blocks inside these constructs.

To verify that your test file is testing your algorithm over the intended operating range, review the code coverage results and take action as described in the following table.

Coverage Bar ColorAction Required
Dark greenNone
Light greenReview percentage coverage and verify that it is reasonable based on your algorithm. If there are areas of code that you expect to be executed more frequently, modify your test file or add more test files to increase coverage.
OrangeThis is expected behavior for initialization code, for example, the initialization of persistent variables. For other cases, verify that this behavior is reasonable for your algorithm. If there are areas of code that you expect to be executed more frequently, modify your test file or add more test files to increase coverage.
RedIf the code that is not executed is an error condition, this is acceptable behavior. If the code should be executed, modify the test file or add another test file to extend coverage. If the code is written conservatively and has upper and lower boundary limits and you cannot modify the test file to reach this code, add static minimum and maximum values (see Computing Derived Ranges).

Proposing Data Types

The Fixed-Point Conversion tool proposes fixed-point data types based on computed ranges and the word length or fraction length setting. The computed ranges are based on simulation range data, derived range data, or both. If you run a simulation and compute derived ranges, the conversion tool merges the simulation and derived ranges.

    Note:   You cannot propose data types based on derived ranges for MATLAB classes.

You can manually enter static ranges. These manually-entered ranges take precedence over simulation ranges and the tool uses them when proposing data types. In addition, you can modify and lock the proposed type so that the tool cannot change it. For more information, see Locking Proposed Data Types.

Running a Simulation

When you open the Fixed-Point Conversion tool, the tool generates an instrumented MEX function for your entry-point MATLAB file. If the build completes without errors, the tool displays compiled information (type, size, complexity) for functions and variables in your code. To navigate to local functions, click the Functions tab. If build errors occur, the tool provides error messages that link to the line of code that caused the build issues. You must address these errors before running a simulation. Use the link to navigate to the offending line of code in the MATLAB editor and modify the code to fix the issue. If your code uses functions that are not supported for fixed-point conversion, the tool displays them on the Function Replacements tab. See Function Replacements.

Before running a simulation, specify the test file or files that you want to run. When you run a simulation, the tool runs the test file, calling the instrumented MEX function. If you modify the MATLAB design code, the tool automatically generates an updated MEX function before running a test file.

If the test file runs successfully, the simulation minimum and maximum values and the proposed types are displayed on the Variables tab. If you manually enter static ranges for a variable, the manually-entered ranges take precedence over the simulation ranges. If you manually modify the proposed types by typing or using the histogram, the data types are locked so that the tool cannot modify them.

If the test file fails, the errors are displayed on the Simulation Output tab.

Test files should exercise your algorithm over its full operating range. The quality of the proposed fixed-point data types depends on how well the test file covers the operating range of the algorithm with the desired accuracy. You can add test files and select to run more than one test file during the simulation. If you run multiple test files, the conversion tool merges the simulation results.

Optionally, you can select to log data for histograms. After running a simulation, you can view the histogram for each variable. For more information, see Histogram.

Computing Derived Ranges

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.

To compute derived ranges and propose data types based on these ranges, provide static minimum and maximum values or proposed data types for all input variables. To improve the analysis, enter as much static range information as possible for other variables. You can manually enter ranges or promote simulation ranges to use as static ranges. Manually-entered static ranges always take precedence over simulation ranges.

If you know what data type your hardware target uses, set the proposed data types to match this type. Manually-entered data types are locked so that the tool cannot modify them. The tool uses these data types to calculate the input minimum and maximum values and to derive ranges for other variables. For more information, see Locking Proposed Data Types.

When you select Compute Derived Ranges, the tool runs a derived range analysis to compute static ranges for variables in your MATLAB algorithm. When the analysis is complete, the static ranges are displayed on the Variables tab. If the run produces +/-Inf derived ranges, consider defining ranges for all persistent variables.

Optionally, you can select Quick derived range analysis. With this option, the conversion tool performs faster static analysis. The computed ranges might be larger than necessary. Select this option in cases where the static analysis takes more time than you can afford.

If the derived range analysis for your project is taking a long time, you can optionally set a timeout. The tool aborts the analysis when the timeout is reached.

Locking Proposed Data Types

You can lock proposed data types against changes by the Fixed-Point Conversion tool using one of the following methods:

  • Manually setting a proposed data type in the Fixed-Point Conversion tool.

  • Right-clicking a type proposed by the tool and selecting Lock computed value.

The tool displays locked data types in bold so that they are easy to identify. You can unlock a type using one of the following methods:

  • Manually overwriting it.

  • Right-clicking it and selecting Undo changes. This action unlocks only the selected type.

  • Right-clicking and selecting Undo changes for all variables. This action unlocks all locked proposed types.

Viewing Functions

You can view a list of functions in your project on the Navigation pane. This list also includes function specializations and class methods. When you select a function from the list, the MATLAB code for that function or class method is displayed in the Fixed-Point Conversion tool code window.

Viewing Variables

The Variables tab provides the following information for each variable in the function selected in the Navigation pane:

  • Type — The original data type of the variable in the MATLAB algorithm.

  • Sim Min and Sim Max — The minimum and maximum values assigned to the variable during simulation.

    You can edit the simulation minimum and maximum values. Edited fields are shown in bold. Editing these fields does not trigger static range analysis, but the tool uses the edited values in subsequent analyses. You can revert to the types proposed by the tool.

  • Static Min and Static Max — The static minimum and maximum values.

    To compute derived ranges and propose data types based on these ranges, provide static minimum and maximum values for all input variables. To improve the analysis, enter as much static range information as possible for other variables.

    When you compute derived ranges, the Fixed-Point Conversion tool runs a static analysis to compute static ranges for variables in your code. When the analysis is complete, the static ranges are displayed. You can edit the computed results. Edited fields are shown in bold. Editing these fields does not trigger static range analysis, but the tool uses the edited values in subsequent analyses. You can revert to the types proposed by the tool.

  • Whole Number — Whether all values assigned to the variable during simulation are integers.

    The Fixed-Point Conversion tool determines whether a variable is always a whole number. You can modify this field. Edited fields are shown in bold. Editing these fields does not trigger static range analysis, but the tool uses the edited values in subsequent analyses. You can revert to the types proposed by the tool.

  • The proposed fixed-point data type for the specified word (or fraction) length. Proposed data types use the numerictype notation. For example, numerictype(1,16,12) denotes a signed fixed-point type with a word length of 16 and a fraction length of 12. numerictype(0,16,12) denotes an unsigned fixed-point type with a word length of 16 and a fraction length of 12.

    Because the tool does not apply data types to expressions, it does not display proposed types for them. Instead, it displays their original data types.

You can also view and edit variable information in the code pane by placing your cursor over a variable name.

You can use Ctrl+F to search for variables in the MATLAB code and on the Variables tab. The tool highlights occurrences in the code and displays only the variable with the specified name on the Variables tab.

Viewing Information for MATLAB Classes

The tool displays:

  • Code for MATLAB classes and code coverage for class methods in the code window. Use the Function list in the Navigation bar to select which class or class method to view.

  • Information about MATLAB classes on the Variables tab.

Histogram

To log data for histograms, in the Fixed-Point Conversion window, click Run Simulation and select Log data for histogram, and then click the Run Simulation button.

After simulation, to view the histogram for a variable, on the Variables tab, click the Proposed Type field for that variable.

The histogram provides the range of the proposed data type and the percentage of simulation values that the proposed data type covers. The bit weights are displayed along the X-axis, and the percentage of occurrences along the Y-axis. Each bin in the histogram corresponds to a bit in the binary word. For example, this histogram displays the range for a variable of type numerictype(1,16,14).

You can view the effect of changing the proposed data types by:

  • Dragging the edges of the bounding box in the histogram window to change the proposed data type.

  • Selecting or clearing Signed.

To revert to the types proposed by the automatic conversion, in the histogram window, click .

Function Replacements

If your MATLAB code uses functions that do not have fixed-point support, the tool lists these functions on the Function Replacements tab. You can add and remove function replacements from this list. If you enter a function replacements for a function, the replacement function is used when you build the project. If you do not enter a replacement, the tool uses the type specified in the original MATLAB code for the function.

    Note:   Using this table, you can replace the names of the functions but you cannot replace argument patterns.

Validating Types

Selecting Validate Types validates the build using the proposed fixed-point data types. If the validation is successful, you are ready to test the numerical behavior of the fixed-point MATLAB algorithm.

If the errors or warnings occur during validation, they are displayed on the Type Validation Output tab. If errors or warning occur:

  • On the Variables tab, inspect the proposed types and manually modified types to verify that they are valid.

  • On the Function Replacements tab, verify that you have provided function replacements for unsupported functions.

Testing Numerics

After validating the proposed fixed-point data types, select Test Numerics to verify the behavior of the fixed-point MATLAB algorithm. By default, if you added a test file to define inputs or run a simulation, the tool uses this test file to test numerics. Optionally, you can add test files and select to run more than one test file. The tool compares the numerical behavior of the generated fixed-point MATLAB code with the original floating-point MATLAB code. If you select to log inputs and outputs for comparison plots, the tool generates an additional plot for each scalar output. This plot shows the floating-point and fixed-point results and the difference between them. For non-scalar outputs, only the error information is shown.

If the numerical results do not meet your desired accuracy after fixed-point simulation, modify fixed-point data type settings and repeat the type validation and numerical testing steps. You might have to iterate through these steps multiple times to achieve the desired results.

Detecting Overflows

When testing numerics, selecting Use scaled doubles to detect overflows enables overflow detection. When this option is selected, the conversion tool runs the simulation using scaled double versions of the proposed fixed-point types. Because scaled doubles store their data in double-precision floating-point, they carry out arithmetic in full range. They also retain their fixed-point settings, so they are able to report when a computation goes out of the range of the fixed-point type. For more information, see Scaled Doubles.

If the tool detects overflows, on its Overflow tab, it provides:

  • A list of variables and expressions that overflowed

  • Information on how much each variable overflowed

  • A link to the variables or expressions in the code window

If your original algorithm uses scaled doubles, the tool also provides overflow information for these expressions.

See Also

Detect Overflows Using the Fixed-Point Conversion Tool

Was this topic helpful?