NumericTypeScope

Determine fixed-point data type

collapse all in page

Syntax

H = NumericTypeScope
show(H)
step(H, data)
release(H)
reset(H)

Description

The NumericTypeScope is an object that provides information about the dynamic range of your data. The scope provides a visual representation of the dynamic range of your data in the form of a log2 histogram. In this histogram, the bit weights appear along the X-axis, and the percentage of occurrences along the Y-axis. Each bin of the histogram corresponds to a bit in the binary word. For example, 20 corresponds to the first integer bit in the binary word, 2-1 corresponds to the first fractional bit in the binary word.

The scope suggests a data type in the form of a numerictype object that satisfies the specified criteria. See the section on Bit Allocation in Dialog Panels.

H = NumericTypeScope returns a NumericTypeScope object that you can use to view the dynamic range of data in MATLAB®. To view the NumericTypeScope window after creating H, use the show method.

show(H) opens the NumericTypeScope object H and brings it into view. Closing the scope window does not delete the object from your workspace. If the scope object still exists in your workspace, you can open it and bring it back into view using the show method.

step(H, data) processes your data and allows you to visualize the dynamic range. The object H retains previously collected information about the variable between each call to step.

release(H) releases system resources (such as memory, file handles or hardware connections) and allows all properties and input characteristics to be changed.

reset(H) clears all stored information from the NumericTypeScope object H. Resetting the object clears the information displayed in the scope window.

Identifying Values Outside Range and Below Precision

The NumericTypeScope can also help you identify any values that are outside range or below precision based on the current data type. To prepare the NumericTypeScope to identify them, provide an input variable that is a fi object and verify that one of the following conditions is true:

  • The DataTypeMode of the fi object is set to Scaled doubles: binary point scaling.

  • The DataTypeOverride property of the Fixed-Point Designer™ fipref object is set to ScaledDoubles.

When the information is available, the scope indicates values that are outside range, below precision, and in range of the data type by color-coding the histogram bars as follows:

  • Blue — Histogram bin contains values that are in range of the current data type.

  • Red — Histogram bin contains values that are outside range in the current data type.

  • Yellow — Histogram bin contains values that are below precision in the current data type.

For an example of the scope color coding, see the figures in Vertical Units.

See also Legend in Dialog Panels.

See the Examples section to learn more about using the NumericTypeScope to select data types.

Dialog Boxes and Toolbar

The NumericTypeScope Window

The NumericTypeScope opens with the default toolbars displayed at the top of the window and the dialog panels to the right.

Configuration Dialog Box

The NumericTypeScope configuration allows you to control the behavior and appearance of the scope window.

To open the Configuration dialog box, select File > Configuration, or, with the scope as your active window, press the N key.

The Configuration Dialog box contains a series of panes each containing a table of configuration options. See the reference section for each pane for instructions on setting the options on each one. This dialog box has one pane, the Core pane, with only one option, for General UI settings for the scope user interface.

To save configuration settings for future use, select File > Configuration > Save as. The configuration settings you save become the default configuration settings for the NumericTypeScope object.

Caution

Before saving your own set of configuration settings in the matlab/toolbox/fixedpoint/fixedpoint folder, save a backup copy of the default configuration settings in another location. If you do not save a backup copy of the default configuration settings, you cannot restore these settings at a later time.

To save your configuration settings for future use, save them in the matlab/toolbox/fixedpoint/fixedpoint folder with the file name NumericTypeScopeComponent.cfg. You can re-save your configuration settings at anytime, but remember to do so in the specified folder using the specified file name.

Core Pane

The Core pane in the Configuration dialog box controls the general settings of the scope.

Click General UI and then click Options to open the Core:General UI Options dialog box.

  • Display the full source path in the title bar—Select this check box to display the file name and variable name in the scope title bar. If the scope is not from a file, or if you clear this check box, the scope displays only the variable name in the title bar.

  • Open message log—Control when the Message Log window opens. The Message log window helps you debug issues with the scope. Choose to open the Message Log window for any of these conditions:

    • for any new messages

    • for warn/fail messages

    • only for fail messages

    • manually

    The option defaults to for warn/fail messages.

    You can open the Message Log at any time by selecting Help > Message Log or by pressing Ctrl+M. The Message Log dialog box provides a system level record of loaded configuration settings and registered extensions. The Message Log displays summaries and details of each message, and you can filter the display of messages by Type and Category.

    • Type—Select the type of messages to display in the Message Log. You can select All, Info, Warn, or Fail. Type defaults to All.

    • Category—Select the category of messages to display in the Message Log. You can select All, Configuration, or Extension. The scope uses Configuration messages to indicate when new configuration files are loaded, and Extension messages to indicate when components are registered. Category defaults to All.

Dialog Panels

Bit Allocation

The scope Bit Allocation dialog panel, as shown in the following figure, offers you several options for specifying data type criteria.

You can use this panel to specify a known word length and the desired maximum occurrences outside range. You can also use the panel to specify the desired number of occurrences outside range and the smallest value to be represented by the suggested data type. For streaming data, the suggested numerictype object adjusts over time in order to continue to satisfy the specified criteria.

The scope also allows you to interact with the histogram plot. When you select Graphical control on the Bit Allocation dialog panel, you enable cursors on either side of the binary point. You can interact with these cursors and observe the effect of the suggested numerictype on the input data. For example, you can see the number of values that are outside range, below precision, or both. You can also view representable minimum and maximum values of the data type.

Legend

The scope Legend panel informs you which colors the scope uses to indicate values. These colors represent values that are outside range, in range, or below precision when displayed in the scope.

Resulting Type

The Resulting Type panel describes the fixed-point data type as defined by scope settings. By manipulating the visual display (via the Bit Allocation panel or with the cursors) you can change the value of the data type.

The Data Details section displays the percentage of values that fall outside range or below precision with the numerictype object located at the top of this panel. SQNR (Signal Quantization Noise Ratio) varies depending on the signal. If the parameter has no value, then there is not enough data to calculate the SQNR. When scope information or the numerictype changes, the SQNR resets.

Type Details section provides details about the fixed-point data type.

Input Data

The Input Data panel provides statistical information about the values currently displayed in the NumericScopeType object.

Vertical Units

Use the Vertical Units selection to display values that are outside range or below precision as a percentage or as an actual count. For example, the following image shows the values that are outside range or below precision as a percentage of the total values.

This next example shows the values that are outside range or below precision as an actual count.

Bring All NumericType Scope Windows Forward

The NumericScopeType GUI offers a View > Bring All NumericType Scopes Forward menu option to help you manage your NumericTypeScope windows. Selecting this option or pressing Ctrl+F brings all NumericTypeScope windows into view. If a NumericTypeScope window is not currently open, this menu option opens the window and brings it into view.

Toolbar (Mac Only)

Activate the Toolbar by selecting View > Toolbar. When this tool is active, you can dock or undock the scope from the GUI.

The toolbar feature is for the Mac only. Selecting Toolbar on Windows® and UNIX® versions displays only an empty toolbar. The docking icon always appears in the GUI in the upper-right corner for these versions.

Methods

release

Use this method to release system resources (such as memory, file handles or hardware connections) and allow all properties and input characteristics to be changed.

Example:

>>release(H)

reset

Use this method to clear the information stored in the object H. Doing so allows you to reuse H to process data from a different variable.

Example:

>>reset(H)

show

Use this method to open the scope window and bring it into view.

Example:

>>show(H)

step

Use this method to process your data and visualize the dynamic range in the scope window.

Example:

>>step(H, data)

Examples

collapse all

Open Script

Set the fi object DataTypeOverride to Scaled Doubles, and then view its dynamic range.

fp = fipref;
initialDTOSetting = fp.DataTypeOverride;
fp.DataTypeOverride = 'ScaledDoubles';
a = fi(magic(10),1,8,2);
b = fi([a; 2.^(-5:4)],1,8,3);
h = NumericTypeScope;
step(h,b);
fp.DataTypeOverride = initialDTOSetting;

The log2 histogram display shows that the values appear both outside range and below precision in the variable. In this case, b has a data type of numerictype(1,8,3). The numerictype(1,8,3) data type provides 5 integer bits (including the signed bit), and 3 fractional bits. Thus, this data type can represent only values between -2^4 and 2^4- 2^-3 (from -16 to 15.8750). Given the range and precision of this data type, values greater than 2^4 fall outside the range and values less than 2^-3 fall below the precision of the data type. When you examine the NumericTypeScope display, you can see that values requiring bits 5, 6, and 7 are outside range and values requiring fractional bits 4 and 5 are below precision. Given this information, you can prevent values that are outside range and below precision by changing the data type of the variable b to numerictype(0,13,5).

Open Script

View the dynamic range, and determine an appropriate numeric type for a fi object with a DataTypeMode of Scaled double: binary point scaling.

Create a numerictype object with a DataTypeMode of Scaled double: binary point scaling. You can then use that numerictype object to construct your fi objects. Because you set the DataTypeMode to Scaled double: binary point scaling, the NumericTypeScope can now identify overflows in your data.

T = numerictype;
T.DataTypeMode = 'Scaled double: binary point scaling';
T.WordLength = 8;
T.FractionLength = 6;
a = fi(sin(0:100)*3.5, T);
b = fi(cos(0:100)*1.75,T);
acc = fi(0,T);
h = NumericTypeScope;
for i = 1:length(a)
    acc(:) = a(i)*0.7+b(i);
    step(h,acc)
end

This dynamic range analysis shows that you can represent the entire range of data in the accumulator with 5 bits; two to the left of the binary point (integer bits) and three to the right of it (fractional bits). You can verify that this data type is able to represent all the values by changing the WordLength and FractionLength properties of the numerictype object T. Then, use T to redefine the accumulator.

To view the dynamic range analysis based on this new data type, reset the NumericTypeScope object h, and rerun the loop.

T.WordLength = 5;
T.FractionLength = 2;
acc = fi(0,T);
release(h)
reset(h)
for i = 1:length(a)
    acc(:) = a(i)*0.7 + b(i);
    step(h,acc)
end

See Also

|

Introduced in R2010a

Fixed-Point Designer Documentation

Support