fxpOptimizationOptions Class

Specify options for data type optimization

Description

The fxpOptimizationOptions object enables you to specify options and constraints to use during the data type optimization process using fxpopt.

Creation

options = fxpOptimizationOptions() creates an fxpOptimizationOptions object with default values.

options = fxpOptimizationOptions('PropertyName',PropertyValue) creates an fxpOptimizationOptions object with specified property name-value pairs.

Properties

MaxIterations — Maximum number of iterations to perform

50 (default) | nonnegative scalar integer

Maximum number of iterations to perform, specified as a nonnegative 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.

Example: options.MaxIterations = 75;

Example: options = fxpOptimizationOptions('MaxIterations',75);

Data Types: double

MaxTime — Maximum amount of time for the optimization to run (in seconds)

600 (default) | nonnegative scalar

Maximum amount of time for the optimization to run, in seconds, specified as a nonnegative scalar. The optimization runs until it reaches the time specified, finds an ideal solution, or reaches another stopping criteria.

Example: options.MaxTime = 1000;

Example: options = fxpOptimizationOptions('MaxTime',1000);

Data Types: double

Patience — Maximum number of iterations where no new best solution is found

10 (default) | scalar integer

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.

Example: options.Patience = 15;

Example: options = fxpOptimizationOptions('Patience',15);

Data Types: double

Verbosity — Level of information displayed at the command line during the optimization

'High' (default) | 'Moderate' | 'Silent'

The level of information displayed at the command line during the optimization process, specified as one of these values:

• 'High' — Information is displayed at the command line at each iteration of the optimization process, including whether a new best solution was found and the cost of the solution.

• 'Moderate' — Information is displayed at each major step of the optimization process, including when the process is in the preprocessing, modeling, and optimization phases.

• 'Silent' — Nothing is displayed at the command line until the optimization process is finished.

Example: options.Verbosity = 'Moderate';

Example: options = fxpOptimizationOptions('Verbosity','Moderate');

Data Types: char | string

AllowableWordLengths — Word lengths that can be used in your optimized system under design

[2:128] (default) | scalar integer | vector of integers

Specify the allowed word lengths that can be used in your optimized system under design. The optimization considers only word lengths which are in the intersection of the AllowableWordLengths and word lengths compatible with hardware constraints specified in the Hardware Implementation pane of your model.

This option works together with the PerformNeighborhoodSearch setting:

• When the AdvancedOptions property PerformNeighborhoodSearch is disabled, the optimization returns data types with homogeneous word lengths. The smallest value in AllowableWordLengths which meets the behavioral constraints set on the system under design will be used in the final optimized result.

• When the AdvancedOptions property PerformNeighborhoodSearch is enabled, the optimization returns data types with heterogeneous word lengths. The optimization first targets the search by finding homogeneous data types from the AllowableWordLengths which meet the behavioral constraints. Then a secondary search is performed around the neighborhood of this solution, allowing heterogeneous data types to be set on the system under design which minimize the cost of the system while meeting the specified behavioral constraints.

Tip

Use the MaxTime and Patience properties to control how long the optimization process runs.

Example: options.AllowableWordLengths = [8:11,16,32];

Data Types: double

ObjectiveFunction — Objective function to use during optimization search

'BitWidthSum' (default) | 'OperatorCount' | 'CustomCostFunction'

Objective function to use during optimization search, specified as one of these values:

• 'BitWidthSum' — Minimize total bit width sum.

• 'OperatorCount' — 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 'OperatorCount' 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).

• 'CustomCostFunction' — Customize the objective function by specifying cost functions for blocks in your design.

Example: options.ObjectiveFunction = 'OperatorCount';

Data Types: char | string

UseParallel — Whether to run iterations in parallel

0 (false) (default) | 1 (true)

Whether to run iterations of the optimization in parallel, specified as a logical 0 (false) or 1 (true). Running the iterations in parallel requires a Parallel Computing Toolbox™ license. If you do not have a Parallel Computing Toolbox license, or if you specify 0 (false), the iterations run in serial.

Example: options.UseParallel = 1;

Data Types: logical

AdvancedOptions — Additional options for optimization

AdvancedFxpOptimizationOptions object

Additional advanced options for optimization. AdvancedFxpOptimizationOptions is an object containing additional properties that can affect the optimization.

Property	Description
PerformNeighborhoodSearch	This property works together with the AllowableWordLengths property. The optimization first finds fixed-point data types with homogeneous word lengths from the AllowableWordLengths which meet the specified behavioral constraints, then performs a secondary search around the neighborhood of this solution while allowing heterogeneous word lengths for fixed-point data types in the optimized solution. 1 (default) — Perform a neighborhood search for the optimized solution. This option can result in a more optimized solution, but requires more simulations. 0 — Do not perform a neighborhood search. Selecting this option can increase the speed of the optimization process, but also increases the chances of finding a less ideal solution. Tip Use the MaxTime and Patience properties to control how long the optimization process runs.
EnforceLooseCoupling	Some Simulink blocks have a parameter that forces inputs to share a data type, or forces the output to share the same data type as the input. 1 (default) — Allow the optimizer to relax this restriction on all blocks in the system under design. Relaxing this restriction enables the optimizer to provide better fitting data types. 0 — Do not allow the optimizer to relax this restriction on blocks in the system under design.
UseDerivedRangeAnalysis	0 (default) — The optimizer does not consider ranges derived from design ranges in the model when assessing a solution. 1 — The optimizer considers both observed simulation ranges and ranges derived from design ranges in the model when assessing a solution. Depending on the model configuration, derived range analysis may take longer than simulation of the model.
SimulationScenarios	Define additional simulation scenarios to consider during optimization using a Simulink.SimulationInput object. For an example, see Optimize Data Types Using Multiple Simulation Scenarios.
SafetyMargin	Enter a safety margin, specified as a nonnegative scalar value. The safety margin increases the bounds of the collected range by the percentage specified. For example, if a signal has a range [-1,1], specifying the SafetyMargin as 100 would increase the range by 100 percent to [-2,2] during optimization. Adding a safety margin reduces the risk of overflow and prevents errors when signals exceed their specified range after fixed-point conversion. Adding a safety margin can reduce the precision of your simulation results. The safety margin is applied to all collected ranges, including simulation ranges, derived ranges, and design ranges.
DataTypeOverride	Override data types specified in the model when simulating during the range collection phase of optimization. 'Off' (default) — Do not override data types. 'Single' — Override data types with singles. 'Double' — Override data types with doubles. 'ScaledDouble' — Override data types with scaled doubles. See Scaled Doubles and Use Scaled Doubles to Avoid Precision Loss for more information.
HandleUnsupported	Some blocks are not supported for fixed-point conversion. Specify how the optimizer handles unsupported blocks. 'Isolate' (default) — Isolate unsupported blocks with Data Type Conversion blocks. Isolated blocks are ignored by the optimizer. 'Error' — Stop optimization and report an error when the system contains blocks that are not supported for fixed-point conversion. 'Warn' — Warn when the system contains blocks that are not supported for fixed-point conversion. Ignore unsupported blocks and continue optimization. This option allows you to manually replace unsupported constructs with other solutions, such as lookup tables, after optimization is complete. In R2024b: 'ReplaceLUT' — Automatically replace unsupported blocks with an optimized lookup table approximation. You must specify design minimum and maximum values upstream of the unsupported block. For more information, see Blocks That Do Not Support Fixed-Point Data Types.
InstrumentationContext	[model '/Subsystem'] — Restrict instrumentation for minimum, maximum, and overflow logging for the range collection step of optimization to a subsystem. The subsystem must be under the top-level model and contain the system under design.

Example: options.AdvancedOptions.PerformNeighborhoodSearch = 0;

Methods

Public Methods

Data Type and Tolerance Specification

addSpecification	Specify known data types in a system
addTolerance	Specify numeric tolerance for optimized system
showSpecifications	Show specifications for a system
showTolerances	Show tolerances specified for a system
clearTolerances	Remove tolerances from optimization options object

Objective Function Customization

setCustomCost

Set block-level cost functions to customize the optimization objective

Examples

Create an fxpOptimizationOptions Object

Create an fxpOptimizationObject with default property values.

options = fxpOptimizationOptions();

Edit the properties after creation using dot syntax.

options.Patience = 15;
options.AllowableWordLengths = [8,16,32];
options.AdvancedOptions.UseDerivedRangeAnalysis = true

options = 
  fxpOptimizationOptions with properties:

           MaxIterations: 50
                 MaxTime: 600
                Patience: 15
               Verbosity: High
    AllowableWordLengths: [8 16 32]
       ObjectiveFunction: BitWidthSum
             UseParallel: 0

   Advanced Options
         AdvancedOptions: [1×1 DataTypeOptimization.AdvancedFxpOptimizationOptions]

Create an fxpOptimizationOptions Object with Non-Default Settings

Use property name-value pairs to set properties at object creation.

options = fxpOptimizationOptions('Patience',15,'AllowableWordLengths',[8,16,32])

options = 
  fxpOptimizationOptions with properties:

           MaxIterations: 50
                 MaxTime: 600
                Patience: 15
               Verbosity: High
    AllowableWordLengths: [8 16 32]
       ObjectiveFunction: BitWidthSum
             UseParallel: 0

   Advanced Options
         AdvancedOptions: [1×1 DataTypeOptimization.AdvancedFxpOptimizationOptions]

Specify advanced options.

options.AdvancedOptions.UseDerivedRangeAnalysis = 1

options = 
  fxpOptimizationOptions with properties:

           MaxIterations: 50
                 MaxTime: 600
                Patience: 15
               Verbosity: High
    AllowableWordLengths: [8 16 32]
       ObjectiveFunction: BitWidthSum
             UseParallel: 0

   Advanced Options
         AdvancedOptions: [1×1 DataTypeOptimization.AdvancedFxpOptimizationOptions]

Import an fxpOptimizationOptions Object into Fixed-Point Tool

You can import an fxpOptimizationOptions object into the Fixed-Point Tool to perform data type optimization in the app. By importing an fxpOptimizationOptions object rather than specifying settings manually in the app, you can easily save and restore your settings.

Open the model.

model = 'ex_controllerHarness';
open_system(model);

To specify options for the optimization, such as the allowable word length and number of iterations, use the fxpOptimizationOptions object.

options = fxpOptimizationOptions('AllowableWordLengths',[2:32],...
    'MaxIterations',3e2,...
    'Patience',50);

Open the Fixed-Point Tool with the Controller subsystem selected.

fxptdlg('ex_controllerHarness/Controller')

In the Fixed-Point Tool, select New > Optimized Fixed-Point Conversion to start the data type optimization workflow.

In the Setup pane, under Advanced Options, select the optimization options object to import from the dropdown menu. Click Import.

Expand the Optimization Options menu in the toolstrip to confirm that the optimization options were applied.

Version History

Introduced in R2018a

R2026a: PerformSlopeBiasCancellation property of fxpOptimizationOptions will be removed

The PerformSlopeBiasCancellation property of fxpOptimizationOptions will be removed in a future release. After removal, the software will follow the current default behavior described below.

The fxpOptimizationOptions object allows you to specify additional advanced options for optimization using the AdvancedFxpOptimizationOptions object. This object has the property PerformSlopeBiasCancellation with settings:

• 0 (default) — Do not propagate slope-bias data types.

• 1 — Propagate slope-bias data types from outside the system under design. Slopes and biases are chosen to reduce the complexity of generated code.

R2026a: clearTolerances: Remove tolerances from fxpOptimizationOptions object

Use the clearTolerances method to remove individual tolerances or clear all tolerances from the fxpOptimizationOptions object.

R2024b: Automatically replace unsupported constructs with lookup table approximation

Using the fxpOptimizationOptions object, you can now specify to automatically replace unsupported constructs with a lookup table approximation.

options.AdvancedOptions.HandleUnsupported = "ReplaceLUT"

R2021b: Restrict instrumentation to a subsystem

You can now restrict instrumentation to a subsystem by using the InstrumentationContext property of the fxpOptimizationOptions object to specify the subsystem to use for instrumentation and range collection.

R2021b: Warn about unsupported constructs

You can now choose to display a warning message when fxpopt encounters blocks that are not supported for data type conversion, in addition to the existing options to isolate or error. To warn for unsupported constructs, set the HandleUnsupported property of the fxpOptimizationOptions object to 'Warn'.

R2021a: Override data types with scaled doubles

You can now override data types in a model with scaled doubles.