# Documentation

## Propose Fraction Lengths

### Propose Fraction Lengths

1. On the Fixed-Point Tool Automatic data typing for selected system pane, select Propose fraction lengths for specified word lengths. If you cannot see this option, click Configure to display more options.

2. On the same pane:

• For simulation min/max information only, clear Derived min/max.

• For derived min/max information only, clear Simulation min/max.

3. If you have safety margins to apply, set Safety margin for design and derived min/max (%) and Safety margin for design and derived min/max (%), as applicable.

4. Click the Propose fraction lengths button, .

 Note:   When the Fixed-Point Tool proposes data types, it does not alter your model.

### About the Feedback Controller Example Model

#### Opening the Feedback Controller Model

To open the Simulink® feedback design model for this tutorial, at the MATLAB® command line, type `fxpdemo_feedback`.

The Simulink model of the feedback design consists of the following blocks and subsystems:

• Reference

This Signal Generator block generates a continuous-time reference signal. It is configured to output a square wave.

• Sum

This Sum block subtracts the plant output from the reference signal.

• ZOH

The Zero-Order Hold block samples and holds the continuous signal. This block is configured so that it quantizes the signal in time by 0.01 seconds.

• Analog to Digital Interface

The analog to digital (A/D) interface consists of a Data Type Conversion block that converts a `double` to a fixed-point data type. It represents any hardware that digitizes the amplitude of the analog input signal. In the real world, its characteristics are fixed.

• Controller

The digital controller is a subsystem that represents the software running on the hardware target. Refer to Digital Controller Realization.

The digital to analog (D/A) interface consists of a Data Type Conversion block that converts a fixed-point data type into a `double`. It represents any hardware that converts a digitized signal into an analog signal. In the real world, its characteristics are fixed.

• Analog Plant

The analog plant is described by a transfer function, and is controlled by the digital controller. In the real world, its characteristics are fixed.

• Scope

The model includes a Scope block that displays the plant output signal.

#### Simulation Setup

To set up this kind of fixed-point feedback controller simulation:

1. Identify all design components.

In the real world, there are design components with fixed characteristics (the hardware) and design components with characteristics that you can change (the software). In this feedback design, the main hardware components are the A/D hardware, the D/A hardware, and the analog plant. The main software component is the digital controller.

2. Develop a theoretical model of the plant and controller.

For the feedback design in this tutorial, the plant is characterized by a transfer function.

The digital controller model in this tutorial is described by a z-domain transfer function and is implemented using a direct-form realization.

3. Evaluate the behavior of the plant and controller.

You evaluate the behavior of the plant and the controller with a Bode plot. This evaluation is idealized, because all numbers, operations, and states are double-precision.

4. Simulate the system.

You simulate the feedback controller design using Simulink and Fixed-Point Designer™ software. In a simulation environment, you can treat all components (software and hardware) as though their characteristics are not fixed.

#### Idealized Feedback Design

Open loop (controller and plant) and plant-only Bode plots for the "Scaling a Fixed-Point Control Design" model are shown in the following figure. The open loop Bode plot results from a digital controller described in the idealized world of continuous time, double-precision coefficients, storage of states, and math operations.

The Bode plots were created using workspace variables produced by a script named `preload_feedback.m`.

#### Digital Controller Realization

In this simulation, the digital controller is implemented using the fixed-point direct form realization shown in the following diagram. The hardware target is a 16-bit processor. Variables and coefficients are generally represented using 16 bits, especially if these quantities are stored in ROM or global RAM. Use of 32-bit numbers is limited to temporary variables that exist briefly in CPU registers or in a stack.

The realization consists of these blocks:

• Up Cast

Up Cast is a Data Type Conversion block that connects the A/D hardware with the digital controller. It pads the output word size of the A/D hardware with trailing zeros to a 16-bit number (the base data type).

• Numerator Terms and Denominator Terms

Each of these Discrete FIR Filter blocks represents a weighted sum carried out in the CPU target. The word size and precision in the calculations reflect those of the accumulator. Numerator Terms multiplies and accumulates the most recent inputs with the FIR numerator coefficients. Denominator Terms multiples and accumulates the most recent delayed outputs with the FIR denominator coefficients. The coefficients are stored in ROM using the base data type. The most recent inputs are stored in global RAM using the base data type.

• Combine Terms

Combine Terms is a Sum block that represents the accumulator in the CPU. Its word size and precision are twice that of the RAM (double bits).

• Down Cast

Down Cast is a Data Type Conversion block that represents taking the number from the CPU and storing it in RAM. The word size and precision are reduced to half that of the accumulator when converted back to the base data type.

• Prev Out

Prev Out is a Unit Delay block that delays the feedback signal in memory by one sample period. The signals are stored in global RAM using the base data type.

Direct Form Realization.  The controller directly implements this equation:

$y\left(k\right)=\sum _{i=0}^{N}{b}_{i}u\left(k-1\right)-\sum _{i=1}^{N}{a}_{i}y\left(k-1\right),$

• u(k – 1) represents the input from the previous time step.

• y(k) represents the current output, and y(k – 1) represents the output from the previous time step.

• bi represents the FIR numerator coefficients.

• ai represents the FIR denominator coefficients.

The first summation in y(k) represents multiplication and accumulation of the most recent inputs and numerator coefficients in the accumulator. The second summation in y(k) represents multiplication and accumulation of the most recent outputs and denominator coefficients in the accumulator. Because the FIR coefficients, inputs, and outputs are all represented by 16-bit numbers (the base data type), any multiplication involving these numbers produces a 32-bit output (the accumulator data type).

### Propose Fraction Lengths Using Simulation Range Data

This example shows you how to use the Fixed-Point Tool to refine the scaling of fixed-point data types associated with a feedback controller model (see About the Feedback Controller Example Model). Although the tool enables multiple workflows for converting a digital controller described in ideal double-precision numbers to one realized in fixed-point numbers, this example uses the following approach:

• Initial Guess at Scaling. Run an initial "proof of concept" simulation using a reasonable guess at the fixed-point word size and scaling. This task illustrates how difficult it is to guess the best scaling.

• Data Type Override. Perform a global override of the fixed-point data types using double-precision numbers. The Simulink software logs the simulation results to the MATLAB workspace, and the Fixed-Point Tool displays them.

• Automatic Data Typing. Perform the automatic data typing procedure, which uses the double-precision simulation results to propose fixed-point scaling for appropriately configured blocks. The Fixed-Point Tool allows you to accept and apply the scaling proposals selectively. Afterward, you determine the quality of the results by examining the input and output of the model's analog plant.

#### Initial Guess at Scaling

Initial guesses for the scaling of each block are already specified in each block mask in the model. This task illustrates the difficulty of guessing the best scaling.

1. Open both the `fxpdemo_feedback``fxpdemo_feedback` model and the Fixed-Point Tool.

2. On the Fixed-Point Tool Model settings pane, click the Model-wide no override and full instrumentation button to set:

• Data type override to ```Use local settings```. This option enables each of the model's subsystems to use its locally specified data type settings.

• Fixed-point instrumentation mode to ```Minimums, maximums and overflows```.

• The run name to `NoOverride`.

3. In the Fixed-Point Tool, click the Simulate button .

The Simulink software simulates the `fxpdemo_feedback` model. Afterward, on its Contents pane, the Fixed-Point Tool displays the simulation results for each block that logged fixed-point data. By default, it displays the Simulation View of these results. You can customize this view by clicking Show Details. For more information about the standard views provided by the Fixed-Point Tool, see Customizing the Contents Pane View in the `fxptdlg` function reference. For more information about customizing views, see Control Model Explorer Contents Using Views.

The tool stores the results in the `NoOverride` run, denoted by the NoOverride label in the Run column. The Fixed-Point tool highlights the `Up Cast` block to indicate that there is an issue with this result. The OvfSat column for this result shows that the block saturated 23 times, which indicates a poor guess for its scaling.

 Tip   In the main toolbar, use the Show option to view only blocks that have Overflows.
4. On the Contents pane of the Fixed-Point Tool, select the Transfer Fcn block named ```Analog Plant``` and then click the Inspect Signal button .

The Fixed-Point Tool plots the signal associated with the plant output.

The preceding plot of the plant output signal reflects the initial guess at scaling. The Bode plot design sought to produce a well-behaved linear response for the closed-loop system. Clearly, the response is nonlinear. Significant quantization effects cause the nonlinear features. An important part of fixed-point design is finding a scaling that reduces quantization effects to acceptable levels.

 Tip   Use the Fixed-Point Tool plotting tools to plot simulation results associated with logged signal data. To view a list of all logged signals, in the main toolbar, use the `Show` option and select `Signal logging results`.

#### Data Type Override

Data type override mode enables you to perform a global override of the fixed-point data types with double-precision data types, thereby avoiding quantization effects. When performing automatic scaling to propose higher fidelity fixed-point scaling, the Fixed-Point Tool uses these simulation results.

1. On the Fixed-Point Tool Model settings pane, click the Model-wide double override and full instrumentation button to set:

• Data type override to `Double`

• Data type override applies to to ```All numeric types```

• Fixed-point instrumentation mode to ```Minimums, maximums and overflows```

• The run name (on the Data collection pane Run name field) to `DoubleOverride`

2. In the Fixed-Point Tool, click the Simulate button .

The Simulink software simulates the `fxpdemo_feedback` model in data type override mode and stores the results as the `DoubleOverride` run. Afterward, on its Contents pane, the Fixed-Point Tool displays the DoubleOverride run results along with those of the NoOverride run that you generated previously (see Initial Guess at Scaling). The compiled data type (CompiledDT) column for the `DoubleOverride` run shows that the model's blocks used a `double` data type during simulation.

3. On the Contents pane of the Fixed-Point Tool, select the Transfer Fcn block named ```Analog Plant``` in the `NoOverride` run, and then click the Compare Signals button .

The Fixed-Point Tool plots both the `DoubleOverride` and `NoOverride` versions of the signal associated with the plant output (upper axes), and plots the difference between the active and reference versions of that signal (lower axes). Compare the ideal (`double` data type) plant output signal with its fixed-point version.

 Tip   From the Simulation Data Inspector menu bar, use the zoom tools to zoom in on an area.

#### Automatic Data Typing

Using the automatic data typing procedure, you can easily maximize the precision of the output data type while spanning the full simulation range.

Because no design min/max information is supplied, the simulation min/max data that was collected during the simulation run is used for proposing data types. The Safety margin for simulation min/max (%) parameter value multiplies the "raw" simulation values. Setting this parameter to a value greater than 1 decreases the likelihood that an overflow will occur when fixed-point data types are being used. For more information about how the Fixed-Point Tool calculates data type proposals, see Proposing Data Types.

Because of the nonlinear effects of quantization, a fixed-point simulation produces results that are different from an idealized, doubles-based simulation. Signals in a fixed-point simulation can cover a larger or smaller range than in a doubles-based simulation. If the range increases enough, overflows or saturations could occur. A safety margin decreases this likelihood, but it might also decrease the precision of the simulation.

 Note:   When the maximum and minimum simulation values cover the full, intended operating range of your design, the Fixed-Point Tool yields meaningful automatic data typing results.

Perform automatic data typing for the `Controller` block. This block is a subsystem that represents software running on the target, and it requires optimization.

1. On the Model Hierarchy pane of the Fixed-Point Tool, select the `Controller` subsystem. On the Automatic data typing for selected system pane, click the Configure link. Select Simulation min/max for Propose using information from design min/max and, then specify the Safety margin for simulation min/max parameter as `20`. Click Apply.

2. In the Fixed-Point Tool:

1. Click the Propose fraction lengths button .

2. In the Propose Data Types dialog box, select DoubleOverride, and then click OK.

The Fixed-Point Tool analyzes the scaling of all fixed-point blocks whose:

• Lock output data type setting against changes by the fixed-point tools parameter is not selected.

• Output data type parameter specifies a generalized fixed-point number.

• Data types are not inherited types.

The Fixed-Point Tool uses the minimum and maximum values stored in the `DoubleOverride` run to propose each block's data types such that the precision is maximized while the full range of simulation values is spanned. The tool displays the proposed data types on its Contents pane. Now, it displays the Automatic Data Typing with Simulation Min/Max View to provide information, such as ProposedDT, ProposedMin, ProposedMax, which are relevant at this stage of the fixed-point conversion.

 Tip   In the main toolbar, use the Show option to view the groups that must share data types. For more information, see `fxptdlg` in the Simulink Reference.

3. Review the scaling that the Fixed-Point Tool proposes. You can choose to accept the scaling proposal for each block. On the Contents pane, select the corresponding Accept check box. By default, the Fixed-Point Tool accepts all scaling proposals that differ from the current scaling. For this example, ensure that the Accept check box associated with the `DoubleOverride` run is selected for each of the Controller subsystem's blocks.

4. In the Fixed-Point Tool, click the Apply accepted fraction lengths button .

The Fixed-Point Tool applies the scaling proposals that you accepted in the previous step to the `Controller` subsystem's blocks.

5. On the Model Hierarchy pane of the Fixed-Point Tool, select the `fxpdemo_feedback` system.

1. On the Model settings pane, click the Model-wide no override and full instrumentation button to use the locally specified data type settings.

2. On the Data collection pane, set Run name to `FixedPoint` so that the Fixed-Point Tool stores the results with a new run name and does not overwrite the results for the initial fixed-point set up. Storing the results in different runs allows you to compare the initial system behavior with the behavior of the autoscaled model.

6. In the Fixed-Point Tool, click Simulate.

The Simulink software simulates the `fxpdemo_feedback` model using the new scaling that you applied. Afterward, in its Contents pane, the Fixed-Point Tool displays information about blocks that logged fixed-point data. The compiled data type (CompiledDT) column for the `FixedPoint` run shows that the Controller subsystem's blocks used fixed-point data types with the new scaling.

7. On the Model Hierarchy pane of the Fixed-Point Tool, select the `fxpdemo_feedback` system.

1. On the Contents pane, select the Transfer Fcn block named `Analog Plant` for the `FixedPoint` run, and then click the Compare Signals button .

2. In the Compare Runs Selector dialog box, select `DoubleOverride`, and then click OK.

The Fixed-Point Tool plots the fixed-point and double override versions of the plant output signal, as well as their difference.

 Tip   Optionally, you can zoom in to view the steady-state region with greater detail. From the Tools menu of the figure window, select Zoom In and then drag the pointer to draw a box around the area that you want to view more closely.

The plant output signal represented by the fixed-point run achieves a steady state, but a small limit cycle is present because of poor A/D design.