Fixed-Point Tool
Convert a floating-point model to a fixed-point model
Description
The Fixed-Point Tool enables you to automatically convert a floating-point model to use fixed-point data types, optimize existing data types on a model, and analyze ranges and data types on your model using rich statistics and visualizations.
The Fixed-Point Tool provides three workflows depending on your needs:
Optimized Fixed-Point Conversion — Automatically convert your model to use optimized fixed-point data types.
Iterative Fixed-Point Conversion — Automatically propose fixed-point data types and manually select which data types to apply to your model.
Range Collection — Explore the numerical behavior of your model before or after data type conversion.
The table below provides a summary of the differences between these three workflows. These options are explained in more detail below.
Workflow | Changes Model Data Types | Ease of Use | Amount of Control Over Data Types Applied to Model | Requires Knowledge of System Behavior Tolerances | Command-Line Workflow |
---|---|---|---|---|---|
Optimized Fixed-Point Conversion | Yes | One step | Low | Yes | fxpopt |
Iterative Fixed-Point Conversion | Yes | Multiple iterations | High | Recommended | DataTypeWorkflow.Converter |
Range Collection | No | One step | N/A | Recommended | DataTypeWorkflow.Converter |
More
Optimized Fixed-Point Conversion Workflow
The Optimized Fixed-Point Conversion workflow in the Fixed-Point Tool provides a fully automated means of converting a Simulink® model to fixed point. If you know the desired behavior of your system and can specify acceptable tolerances on this behavior, you can use this workflow to find the optimal data types for your system. You can achieve better results if you additionally specify any known ranges or supply additional simulation inputs.
The tool allows you to specify allowable word lengths and will also take into account limitations of target hardware you specify. You can also specify a safety margin to increase the bounds of the ranges collected by a specified amount. Optimized data types stay within specified behavioral tolerances and minimize the cost of the design. If more than one feasible solution is found, you can apply and explore different solutions to your model to find one that fits your needs. You can explore the ranges and statistics collected in your baseline model using rich visualization to quickly spot sources of overflow and other numerical issues. You can compare the results of different fixed-point implementations in the Simulation Data Inspector.
After optimizing data types in the Fixed-Point Tool, you can export the
workflow to a MATLAB® script. This allows you to continue data type optimization using fxpopt
at
the command line, which has additional advanced options available for further customizing
the optimization process.
This workflow will automatically change the data types on your model at completion of the optimization process. If you complete the preparation step before starting optimization, you can automatically restore your model to its original state.
Iterative Fixed-Point Conversion Workflow
The Iterative Fixed-Point Conversion workflow in the Fixed-Point Tool is an interactive automatic means of specifying fixed-point data types in a Simulink model. The tool collects ranges for model objects, then proposes fixed-point data types that maximize precision and cover the range. You can then review the data type proposals and apply them selectively to objects in your model.
The tool allows you to propose word lengths or fraction lengths, giving you the option to have a fixed-precision design, and will also take into account limitations of target hardware you specify. You can also specify a safety margin to increase the bounds of the ranges collected by a specified amount. Rich visualizations allow you to explore the ranges of objects in your model and quickly spot sources of overflow and other numerical issues, both before and after converting your model to fixed point. If the proposed data types do not meet your needs, you can continue iterating through this process. You can compare the results of different fixed-point implementations in the Simulation Data Inspector.
This workflow gives you full control over which proposed data types are applied to your model, if any. If you complete the preparation step of conversion, you can automatically restore your model to its original state.
This workflow does not require you to specify the desired behavior of your system, however it is recommended that you specify any known ranges, simulation inputs, and signal tolerances in order to achieve more accurate data type proposals and be able to evaluate whether proposed data types meet the specified requirements of the design.
Range Collection Workflow
The Range Collection workflow in the Fixed-Point Tool is an analysis and troubleshooting tool, and does not change your model. This workflow provides independent access to the range collection step found in the data type conversion workflows.
You can choose to specify additional simulation inputs and tolerances on logged signals in your model. The tool will individually collect ranges for all simulation inputs specified, and also merge the results for a combined view. If you want to explore the ideal floating-point behavior of your system, you can choose to collect ranges with data type override enabled.
Rich visualizations allow you to explore the ranges of objects in your model and quickly spot sources of overflow, underflow, and other numerical issues, before or after conversion to fixed point. Signals that do not meet the specified tolerances are highlighted in the results. You can compare the results of simulation runs using the Simulation Data Inspector.
Open the Fixed-Point Tool
Simulink Toolstrip: On the Apps tab, under Code Generation, click the app icon.
MATLAB command prompt: Enter
fxptdlg
('system_name')
, where'system_name'
is the name of the model or system you want to convert, specified as a string.
Examples
Optimized Fixed-Point Conversion in the Fixed-Point Tool
This example shows how to use the Optimized Fixed-Point Conversion workflow in the Fixed-Point Tool. The model used in this example is a simple FIR filter modeled using floating-point data types. In this example, you specify known behavioral constraints for the output of the filter and optimize the fixed-point data types in the Embedded Efficient Filter
subsystem.
Open the mSimpleFIR
model.
open_system('mSimpleFIR');
Inspect the Embedded Efficient Filter
subsystem.
open_system('mSimpleFIR/Embedded Efficient Filter');
Known design minimum and maximum values are specified explicitly on blocks in the model, including on the inputs and outputs of the Embedded Efficient Filter
subsystem.
Open the Fixed-Point Tool. On the Simulink® Apps tab, under Code Generation, click the app icon.
To start the optimized fixed-point conversion workflow, select Optimized Fixed-Point Conversion.
Select the subsystem that you want to analyze. Under System Under Design (SUD), select the Embedded Efficient Filter
subsystem.
Choose the range collection method to use. Under Range Collection Mode, select Simulation with derived ranges. During the range analysis step of optimization, the tool will combine ranges from simulation minimum and maximum values, design minimum and maximum values specified explicitly on blocks in the model, and derived minimum and maximum values that are computed through a static analysis that derives ranges for objects in the model.
Specify Simulation Inputs. For this example, use the default model inputs for simulation.
Specify signal tolerances for logged signals. Set the Absolute Tolerance and Relative Tolerance of the output_signal:1
to 0.01
.
To prepare the model for fixed-point conversion, click Prepare. The Fixed-Point Tool creates a backup version of the model and checks the model for compatibility with the conversion process. For more about preparation checks, see Use the Fixed-Point Tool to Prepare a System for Conversion.
Next, expand the Optimization Options button arrow to configure the options to use for data type optimization. For this example, use the default.
To optimize data types in the model, click Optimize Data Types.
During the optimization process, the software analyzes ranges of objects in your system under design. Optimization will take into account all specified behavioral constraints, including design minimum and maximum values and signal tolerances, to apply heterogeneous data types to your system while minimizing the objective function. For this example, the objective function is set to the default Bit Width Sum
, which instructs the optimization to minimize the sum of word lengths in the system under design.
During the optimization process, the software makes changes to several settings and model configuration parameters. The purposes of these changes include suppressing diagnostics, enabling logging with the Simulation Data Inspector, reducing the memory consumed by the result, ensuring validity of the model, accelerating the optimization process, and turning off data type override. For more information, see Model Configuration Changes Made During Data Type Optimization. You can restore these diagnostics after the optimization is complete.
Details about the optimization process are printed to the Optimization Details pane in the Fixed-Point Tool. You can pause or stop the optimization solver before the optimization search is complete by clicking Stop.
When the optimization is complete, the Fixed-Point Tool displays a table that contains all of the solutions found during the optimization process. Solution 1 in the table corresponds to the best solution found.
Solutions are ordered in the table based on the Cost, which is defined by the objective function specified in the Optimization Options menu. Feasible solutions that meet the defined behavioral constraints are marked with a pass status in the solutions table. Solutions that do not meet the behavioral constraints are marked with a fail status. This example uses tolerances on the output of the filter subsystem to define the desired behavior of the system. For more information about defining other types of behavioral constraints, see Specify Behavioral Constraints.
During the optimization process, the tool collects ranges and statistics for objects in your model. To explore these ranges, in the Workflow Browser pane, select BaselineRun
.
The Results spreadsheet displays a summary of the statistics collected during the range collection phase of optimization, including simulation minimum and simulation maximum values. You can click any result to view additional details in the Result Details pane. The Visualization of Simulation Data pane displays a summary of histograms of the bits used by each object in your model.
You can customize the information displayed in the Results spreadsheet, or use the Explore tab to sort and filter these results based on additional criteria. For more information, see Control Views in the Fixed-Point Tool.
The best solution found during optimization, Solution 1, is automatically applied to the model. To compare this optimized solution to the baseline run, click Compare. In the Embedded Efficient Filter
subsystem, you can see the applied optimized fixed-point data types. When you click Compare for a model that has logged signals, the tool opens the Simulation Data Inspector. In the Simulation Data Inspector, select output_signal
as the signal to compare. The plot of the plant output signal for Solution 1 is within the specified tolerance band.
You can continue exploring other solutions by selecting a solution from the solutions table and clicking Apply and Compare.
After optimizing data types in the Fixed-Point Tool, you can choose to export the optimization workflow steps to a MATLAB® script. This allows you to save the current optimization workflow steps and continue data type optimization using fxpopt
at the command line.
Click Export Script to export a script named fxpOptimizationOptions
to the current working directory.
After the conversion process, if you want to restore your model to its state at the start of the conversion process, click Restore Original Model. Any changes made to your model after the preparation stage of conversion are removed.
Iterative Fixed-Point Conversion in the Fixed-Point Tool
This example shows how to use the Iterative Fixed-Point Conversion workflow in the Fixed-Point Tool. The model used in this example is a simple FIR filter modeled using initial guesses for fixed-point data types. In this example, you specify known behavioral constraints for the output of the filter and improve the fixed-point data types in the Embedded Efficient Filter
subsystem.
Open the mSimpleFIR_fxp
model.
open_system('mSimpleFIR_fxp');
Inspect the Embedded Efficient Filter
subsystem.
open_system('mSimpleFIR_fxp/Embedded Efficient Filter');
Known design minimum and maximum values are specified explicitly on blocks in the model, including on the inputs and outputs of the Embedded Efficient Filter
subsystem.
Open the Fixed-Point Tool. On the Simulink® Apps tab, under Code Generation, click the app icon.
To start the iterative fixed-point conversion workflow, select Iterative Fixed-Point Conversion.
Select the subsystem that you want to analyze. Under System Under Design (SUD), select the Embedded Efficient Filter
subsystem.
Choose the range collection method to use. Under Range Collection Mode, select Simulation with derived ranges. During the range analysis step of optimization, the tool will combine ranges from simulation minimum and maximum values, design minimum and maximum values specified explicitly on blocks in the model, and derived minimum and maximum values that are computed through a static analysis that derived ranges for objects in the model.
Specify Simulation Inputs. For this example, use the default model inputs for simulation.
Specify signal tolerances for logged signals. Set the Absolute Tolerance and Relative Tolerance of the output_signal:1
to 0.01
.
To prepare the model for fixed-point conversion, click Prepare. The Fixed-Point Tool creates a backup version of the model and checks the model for compatibility with the conversion process. For more about preparation checks, see Use the Fixed-Point Tool to Prepare a System for Conversion.
Next, collect ranges. Expand the Collect Ranges button arrow and select Double precision. Click Collect Ranges to start the range collection run.
When you select Double precision as the range collection mode, the tool simulates the system under design with data type override enabled. Data type override performs a global override of the fixed-point data types in the model, thereby avoiding quantization effects. This enables you to establish an ideal floating-point baseline for the behavior of your model.
The results of range collection are stored in BaselineRun
. The Results spreadsheet displays a summary of the statistics collected during the range collection simulation, including the currently specified data types on the model (SpecifiedDT), simulation minimum, and simulation maximum values. The compiled data type (CompiledDT) column displays double for all objects in the Embedded Efficient Filter
subsystem, indicating that data type override was applied during the range collection simulation.
You can click on any result to view additional details in the Result Details pane. The Visualization of Simulation Data pane displays a summary of histograms of the bits used by each object in your model. The simulation data shows that several objects in the model have potential underflows.
You can customize the information displayed in the Results spreadsheet, or use the Explore tab to sort and filter these results based on additional criteria. For more information, see Control Views in the Fixed-Point Tool.
Next, expand the Settings button arrow to configure the settings to use for data type proposals. Set Propose to Word Length.
To propose data types based on the ranges collected and the data type proposal settings specified, click Propose Data Types. The tool uses all available range data to calculate data type proposals which can include design minimum or maximum values, simulation minimum or maximum values, and derived minimum or maximum values. Data types are proposed for all objects in the system under design whose Lock output data type setting against changes by the fixed-point tools parameter is cleared.
To write the proposed data types to the model, click Apply Data Types. The tool updates the SpecifiedDT column to show that the data types have been applied to the model.
Simulate the model using the applied fixed-point data types. Expand the Simulate with Embedded Types button arrow and select Specified data types. Then click Simulate with Embedded Types.
The Fixed-Point Tool simulates the model using the new fixed-point data types and logs minimum and maximum values and overflow data for all objects in the system under design. This information is stored in a new run named EmbeddedRun
. The icon next to EmbeddedRun
displays a pass status, indicating that all signals in the system under design meet the specified tolerances. The Visualization of Simulation Data pane updates to display the new EmbeddedRun
data.
To compare the ideal results stored in BaselineRun
with the newly applied fixed-point data types, select EmbeddedRun
from the Run to compare in SDI drop down menu. Then click Compare Results to open the Simulation Data Inspector.
In the Simulation Data Inspector, select output_signal
as the signal to compare.
The plot of the filter output signal for EmbeddedRun
is within the specified tolerance band.
If the behavior of the converted system does not meet your requirements or if you want to explore the effect of additional data type selections, you can propose new data types after applying new proposal settings. Continue iterating until you find settings for which the fixed-point behavior of the system is acceptable.
After the conversion process, if you want to restore your model to its state at the start of the conversion process, click Restore Original Model. Any changes made to your model after the preparation stage of conversion are removed.
Range Collection in the Fixed-Point Tool
This example shows how to use the Range Collection workflow in the Fixed-Point Tool. The model used in this example is a simple FIR filter modeled using fixed-point data types. In this example, you analyze the numerical behavior of the model to determine the source of overflow in the Embedded Efficient Filter
subsystem.
Open the mSimpleFIR_fxp_ovf
model.
open_system('mSimpleFIR_fxp_ovf');
Inspect the Embedded Efficient Filter
subsystem.
open_system('mSimpleFIR_fxp_ovf/Embedded Efficient Filter');
Known design minimum and maximum values are specified explicitly on blocks in the model, including on the inputs and outputs of the Embedded Efficient Filter
subsystem.
Open the Fixed-Point Tool. On the Simulink® Apps tab, under Code Generation, click the app icon.
To start the range collection workflow, select Range Collection.
Select the subsystem that you want to analyze. Under System Under Design (SUD), select the Embedded Efficient Filter
subsystem.
Choose the range collection method to use. Under Range Collection Mode, select Simulation with derived ranges. During range collection, the tool will combine ranges from simulation minimum and maximum values, design minimum and maximum values specified explicitly on blocks in the model, and derived minimum and maximum values that are computed through a static analysis that derived ranges for objects in the model.
Specify Simulation Inputs. For this example, use the default model inputs for simulation.
Specify signal tolerances for logged signals. Set the Absolute Tolerance and Relative Tolerance of the output_signal:1
to 0.01
.
Next, expand the Collect Ranges button arrow to configure the settings to use for range collection. Select Double precision to temporarily override data types in the model with doubles during the baseline range collection run. Click Collect Ranges.
The results of the range collection run are stored in BaselineRun
. The Results spreadsheet displays a summary of the statistics collected during the range collection, including the currently specified data types on the model (SpecifiedDT), simulation minimum, and simulation maximum values. The compiled data type (CompiledDT) column displays double for all objects in the Embedded Efficient Filter
subsystem, indicating that data type override was applied during the range collection simulation.
You can click on any result to view additional details in the Result Details pane. The Visualization of Simulation Data pane displays a summary of histograms of the bits used by each object in your model.
You can customize the information displayed in the Results spreadsheet, or use the Explore tab to sort and filter these results based on additional criteria. For more information, see Control Views in the Fixed-Point Tool.
Next, simulate the model using the fixed-point data types currently specified on the model. Expand the Settings button arrow and select Specified data types, then click Simulate with Embedded Types.
The Fixed-Point Tool stores the results of the simulation in EmbeddedRun
.
The icon next to EmbeddedRun
displays a fail status, indicating that one or more signals do not meet the specified tolerances. The results for the Product
block indicate that there is an issue with this result. The Result Details pane shows that the block overflowed 1670 times, indicating a poor choice of word length.
To compare the ideal results stored in BaselineRun
with the fixed-point results, select EmbeddedRun
from the Run to compare in SDI drop down menu. Then click Compare Results to open the Simulation Data Inspector. In the Simulation Data Inspector, select output_signal
as the signal to compare.
Related Examples
Parameters
System Under Design (SUD)
— System or subsystem to analyze or convert
current system (default)
System or subsystem to analyze or convert to fixed-point. You can select individual subsystems in your model one at a time to facilitate debugging by isolating the source of numerical issues, or you can choose the top-level model.
For more information on converting systems containing particular modeling constructs, see:
Range Collection Mode
— How the tool collects ranges for objects in your system
Simulation ranges (default) | Derived ranges | Simulation with derived ranges
How the tool collects ranges for objects in your system, specified as one of the following:
Simulation ranges — Collect ranges through simulation. To collect and merge the ranges of multiple simulation runs, specify Simulation Inputs. Data type proposals are as good as the test bench provided.
Derived ranges — Collect ranges through a static analysis that derives the ranges, also known as range analysis or derived range analysis. Ranges collected using this option are based only on design ranges specified on the model. This option typically delivers more conservative data type proposals. For more information, see How Range Analysis Works.
Simulation with derived ranges — Collect ranges through simulation and derived range analysis and combine the results. Proposed data types are based on the union of simulation and derived ranges. This option provides the most comprehensive range information.
For more information, see Choosing a Range Collection Method.
Simulation Inputs
— Inputs for simulations
Use default model inputs
(default) | Simulink.SimulationInput
object
Inputs for simulations, specified as a Simulink.SimulationInput
object.
If you choose the Range Collection Mode to be
Simulation ranges or Simulation with derived
ranges, you can choose to specify additional simulation inputs to improve
the accuracy of the collected ranges and data type proposals. During the range
collection simulation, the Fixed-Point Tool captures the minimum and
maximum values from each specified simulation scenario. If the
Simulink.SimulationInput
object that you select contains more than
one simulation scenario, the Fixed-Point Tool proposes data types based on
the merged ranges from all simulation scenarios.
A comprehensive set of input signals that exercise the full range of your design will result in more accurate data type proposals for your system. For an example, see Propose Data Types for Merged Simulation Ranges.
Signal Tolerances
— Tolerances for signals in your model that have signal logging enabled
absolute tolerance | relative tolerance | time tolerance
To determine if the numerical behavior of a new fixed-point implementation is acceptable, you can define tolerances for individual signals in your model that have logging enabled. You can specify any of the following types of tolerances:
Absolute Tolerance — Absolute value of the maximum acceptable difference between the original signal and the signal in the converted design.
Relative Tolerance — Maximum relative difference, specified as a percentage, between the original output and the output of the new design. For example, a value of
1e-2
indicates a maximum difference of one percent between the original values and the signal values of the converted design.Time Tolerance (seconds) — Time interval in which the maximum and minimum values define the upper and lower values to compare against.
In the Optimized Fixed-Point Conversion workflow, you must specify at least one behavioral constraint in order to optimize data types. Signal tolerances are one type of behavioral constraint that you can specify.
In the Iterative Fixed-Point Conversion workflow, signal tolerances are not required to propose data types, but are required for the tool to determine whether the embedded run is within tolerance.
In the Range Collection workflow, signal tolerances are not required to collect ranges, but are required for the tool to determine whether the ranges collected are within tolerance.
You can enter signal tolerances using any valid MATLAB expression that returns a finite, non-negative value. (since R2023a)
For more information, see Specify Behavioral Constraints and Tolerance Computation.
Collect Ranges
— Collect ranges
Use current settings
(default) | Double precision
| Single precision
| Scaled double precision
Collect ranges for objects in your model using:
Use current settings
— Use the current data type override set on the model.Double precision
— Override data types in the model with doubles.Single precision
— Override data types in the model with singles.Scaled double precision
— Override data types in the model with scaled doubles.
Ranges collected depend on the Range Collection Mode and any Simulation Inputs specified.
For more information, see Fixed-Point Instrumentation and Data Type Override and Use Custom Data Type Override Settings for Range Collection.
Settings
— Data typing options
Allowable Wordlengths
| Max Iterations
| Propose
| Propose signedness
| Verify using
| ...
Data typing options available in the Settings menu depend on the workflow chosen.
Optimized Fixed-Point Conversion Workflow Options
Option | Description |
---|---|
Allowable Wordlengths |
Word lengths
that can be used in your optimized system under design. The final result of
the optimization uses word lengths in the intersection of the
|
Max Iterations |
Maximum number of iterations to perform, specified as a scalar integer. The optimization process iterates through different solutions until it finds an ideal solution, reaches the maximum number of iterations, or reaches another stopping criteria. |
Max Time (sec) |
Maximum amount of time for the optimization to run, specified in seconds as a scalar number. The optimization runs until it reaches the time specified, an ideal solution, or another stopping criteria. |
Patience (iterations) |
Maximum number of iterations where no new best solution is found, specified as a scalar integer. The optimization continues as long as the algorithm continues to find new best solutions. |
Safety Margin (%) |
A safety margin, specified as a positive scalar value, indicating the percentage increase in the bounds of the collected range. The safety margin is applied to the union of all collected ranges. |
Objective Function | Objective function to use during the optimization search. The optimization algorithm seeks to minimize an objective function while meeting the specified behavioral constraints.
Note To use |
Perform Neighborhood Search |
Whether to perform a neighborhood search for the optimized solution. Disabling this option can increase the speed of the optimization process, but also increases the chances of finding a less ideal solution. |
Use Parallel |
Whether to run iterations of the optimization in parallel. Running the iterations in parallel requires a Parallel Computing Toolbox™ license. If you do not have a Parallel Computing Toolbox license, or if you do not enable this option, the iterations run in serial. |
Iterative Fixed-Point Conversion Workflow Options
Option | Description |
---|---|
Propose | Whether to propose fraction lengths or word lengths for objects in the system under design.
|
Propose signedness |
Whether to use the collected range information to propose signedness. |
Safety margin for simulation min/max
(%) |
Specify a safety margin to apply to collected simulation ranges. The Fixed-Point Tool will add the specified amount to the collected ranges and base proposals on this larger range. |
Convert double/single/half types |
Whether to generate data type proposals for objects that currently specify a double, single, or half-precision data type. |
Convert inherited types |
Whether to generate data type proposals for results that currently specify an inherited data type. |
Default word length |
Default word
length to use for data type proposals, specified as a scalar integer. This
setting is enabled only when the |
Default fraction length |
Default fraction
length to use for data type proposals, specified as a scalar integer. This
setting is enabled only when the |
Range Collection Workflow Options
Option | Description |
---|---|
Verify using | Data type override settings to use for embedded simulation.
|
Limitations
Some blocks do not support fixed-point data types and can result in an error during fixed-point conversion. See Blocks That Do Not Support Fixed-Point Data Types.
Some modeling constructs may cause data type propagation issues. See Models That Might Cause Data Type Propagation Errors.
If your model contains a MATLAB Function block, use only supported modeling constructs for successful conversion. See MATLAB Language Features Supported for Automated Fixed-Point Conversion.
Tips
For best practices and recommendations, see Best Practices for Fixed-Point Conversion Workflow.
To customize views in the Fixed-Point Tool, see Control Views in the Fixed-Point Tool.
For help troubleshooting the optimization workflow, see Data Type Optimization Not Successful.
Version History
Introduced before R2006a
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)