Main Content

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.

WorkflowChanges Model Data TypesEase of UseAmount of Control Over Data Types Applied to ModelRequires Knowledge of System Behavior TolerancesCommand-Line Workflow
Optimized Fixed-Point ConversionYesOne stepLowYesfxpopt
Iterative Fixed-Point ConversionYesMultiple iterationsHighRecommendedDataTypeWorkflow.Converter
Range CollectionNoOne stepN/ARecommendedDataTypeWorkflow.Converter

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 wordlengths 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.

Screen shot of Fixed-Point Tool.

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

expand all

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 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 comaptibility with the conversion process. For more about preparation checks, see Use the Fixed-Point Tool to Prepare a System for Conversion.

Next, expand the Settings button arrow to configure the settings to use for data type optimization. For this example, use the default settings.

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. These purpose 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 Settings 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 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.

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.

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 optimized 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 comaptibility 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 wish 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.

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 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:

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.

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.

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.

For more information, see Specify Behavioral Constraints and Tolerance Computation.

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.

Data typing options available in the Settings menu depend on the workflow chosen.

Optimized Fixed-Point Conversion Workflow Options

OptionDescription
Allowable Wordlengths

[2:128] (default)

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 Allowable Wordlengths and word lengths compatible with hardware constraints specified in the Hardware Implementation pane of your model.

Max Iterations

50 (default)

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)

600 (default)

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)

10 (default)

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 (%)

0 (default)

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.

  • Bit Width Sum (default) — Minimize total bit width sum.

  • Operator Count — Minimize estimated count of operators in generated C code.

    This option may result in a lower program memory size for C code generated from Simulink models. The 'OperatorCount' objective function is not suitable for FPGA or ASIC targets.

Note

To use Operator Count as the objective function during optimization, the model must be ready for code generation. For more information about determining code generation readiness, see Check Model and Configuration for Code Generation (Embedded Coder).

Perform Neighborhood Search

on (default)

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

off (default)

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 no enable this option, the iterations run in serial.

Iterative Fixed-Point Conversion Workflow Options

OptionDescription
Propose

Whether to propose fraction lengths or word lengths for objects in the system under design.

  • Fraction Length (default) — The Fixed-Point Tool uses range information and the specified Default word length value to propose best-precision fraction lengths for the objects in your model.

  • Word Length — The Fixed-Point Tool uses range information and the specified Default fraction length value to propose word lengths for the objects in your model.

Propose signedness

Yes (default)

Whether to use the collected range information to propose signedness.

Safety margin for simulation min/max (%)

2 (default)

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

Yes (default)

Whether to generate data type proposals for objects that currently specify a double, single, or half-precision data type.

Convert inherited types

Yes (default)

Whether to generate data type proposals for results that currently specify an inherited data type.

Default word length

16 (default)

Default word length to use for data type proposals, specified as a scalar integer. This setting is enabled only when the Propose setting is set to Fraction Length.

Default fraction length

4 (default)

Default fraction length to use for data type proposals, specified as a scalar integer. This setting is enabled only when the Propose setting is set to Word Length.

Range Collection Workflow Options

OptionDescription
Verify using

Data type override settings to use for embedded simulation.

  • Specified data types — Use data types specified on the model

  • Scaled double precision — Override data types with scaled doubles.

Limitations

Tips

Introduced before R2006a