Underflow and Overflow Logging Using fipref

Logging Overflows and Underflows as Warnings

Overflows and underflows are logged as warnings for all assignment, plus, minus, and multiplication operations when the fipref LoggingMode property is set to on. For example, try the following:

Create a signed fi object that is a vector of values from 1 to 5, with 8-bit word length and 6-bit fraction length.
```
a = fi(1:5,1,8,6);
```
Define the fimath object associated with a, and indicate that you will specify the sum and product word and fraction lengths.
```
F = a.fimath;
F.SumMode = 'SpecifyPrecision';
F.ProductMode = 'SpecifyPrecision';
a.fimath = F;
```
Define the fipref object and turn on overflow and underflow logging.
```
P = fipref;
P.LoggingMode = 'on';
```

Suppress the numerictype and fimath displays.

P.NumericTypeDisplay = 'none';
P.FimathDisplay = 'none';

Specify the sum and product word and fraction lengths.

a.SumWordLength = 16;
a.SumFractionLength = 15;
a.ProductWordLength = 16;
a.ProductFractionLength = 15;

Warnings are displayed for overflows and underflows in assignment operations. For example, try:

a(1) = pi

Warning: 1 overflow(s) occurred in the fi assignment operation. 

a = 

    1.9844    1.9844    1.9844    1.9844    1.9844

a(1) = double(eps(a))/10

Warning: 1 underflow(s) occurred in the fi assignment operation. 

a = 

         0    1.9844    1.9844    1.9844    1.9844

Warnings are displayed for overflows and underflows in addition and subtraction operations. For example, try:

a+a

Warning: 12 overflow(s) occurred in the fi + operation. 
> In  +  (line 24) 

ans = 

         0    1.0000    1.0000    1.0000    1.0000

a-a

Warning: 8 overflow(s) occurred in the fi - operation. 
> In  -  (line 24) 

ans = 

     0     0     0     0     0

Warnings are displayed for overflows and underflows in multiplication operations. For example, try:

a.*a

Warning: 4 product overflow(s) occurred in the fi .* operation. 
> In  .*  (line 24) 

ans = 

         0    1.0000    1.0000    1.0000    1.0000

a*a'

Warning: 4 product overflow(s) occurred in the fi * operation. 
> In  *  (line 25) 
Warning: 3 sum overflow(s) occurred in the fi * operation. 
> In  *  (line 25) 

ans = 

    1.0000

The final example above is a complex multiplication that requires both multiplication and addition operations. The warnings inform you of overflows and underflows in both.

Because overflows and underflows are logged as warnings, you can use the dbstop MATLAB^® function with the syntax

dbstop if warning

to find the exact lines in a file that are causing overflows or underflows.

Use

dbstop if warning fi:underflow

to stop only on lines that cause an underflow. Use

dbstop if warning fi:overflow

to stop only on lines that cause an overflow.

Accessing Logged Information with Functions

When the fipref LoggingMode property is set to on, you can use the following functions to return logged information about assignment and creation operations to the MATLAB command line:

maxlog — Returns the maximum real-world value
minlog — Returns the minimum value
noverflows — Returns the number of overflows
nunderflows — Returns the number of underflows

LoggingMode must be set to on before you perform any operation in order to log information about it. To clear the log, use the function resetlog.

For example, consider the following. First turn logging on, then perform operations, and then finally get information about the operations:

fipref('LoggingMode','on');
x = fi([-1.5 eps 0.5], true, 16, 15);
x(1) = 3.0;

maxlog(x)

ans =

    1.0000

minlog(x)

ans =

    -1

noverflows(x)

ans =

     2

nunderflows(x)

ans =

     1

Next, reset the log and request the same information again. Note that the functions return empty [], because logging has been reset since the operations were run:

resetlog(x)

maxlog(x)

Warning: Logging is turned on in 'maxlog'. However, 
no values have been logged for this variable yet. 

ans =

     []

minlog(x)

Warning: Logging is turned on in 'minlog'. However, 
no values have been logged for this variable yet. 

ans =

     []

noverflows(x)

Warning: Logging is turned on in 'noverflows'. However, 
no values have been logged for this variable yet. 

ans =

     []

nunderflows(x)

Warning: Logging is turned on in 'nunderflows'. However, 
no values have been logged for this variable yet. 

ans =

     []