Fixed-Point Toolbox™

abs - Absolute value of `fi` object

Syntax

c = abs(a) c = abs(a,T) c = abs(a,F) c = abs(a,T,F)

Description

c = abs(a) returns the absolute value of fi object a with the same numerictype and fimath objects as a. Intermediate quantities are calculated using the fimath object of a.

c = abs(a,T) returns a fi object with a value equal to the absolute value of a, numerictype object T, and the same fimath object as a. Intermediate quantities are calculated using the fimath object of a. See Data Type Propagation Rules.

c = abs(a,F) returns a fi object with a value equal to the absolute value of a, fimath object F, and the same numerictype object as a. Intermediate quantities are calculated using fimath object F.

c = abs(a,T,F) returns a fi object with a value equal to the absolute value of a, numerictype object T, and fimath object F. Intermediate quantities are calculated using fimath object F. See Data Type Propagation Rules.

abs only supports fi objects with [Slope Bias] scaling when the bias is zero and the fractional slope is one. abs does not support complex fi objects of data type Boolean.

When the object a is real and has a signed data type, the absolute value of the most negative value is problematic since it is not representable. In this case, the absolute value saturates to the most positive value representable by the data type if the OverflowMode property is set to saturate. If OverflowMode is wrap, the absolute value of the most negative value has no effect.

Data Type Propagation Rules

For syntaxes for which you specify a numerictype object T, the abs function follows the data type propagation rules listed in the following table. In general, these rules can be summarized as "floating-point data types are propagated." This allows you to write code that can be used with both fixed-point and floating-point inputs.

Data Type of Input fi Object a	Data Type of numerictype object T	Data Type of Output c
`fiFixed`	`fiFixed`	Data type of `numerictype` object `T`
`fiScaledDouble`	`fiFixed`	`ScaledDouble` with properties of `numerictype` object `T`
`fidouble`	`fiFixed`	`fidouble`
`fisingle`	`fiFixed`	`fisingle`
Any `fi` data type	`fidouble`	`fidouble`
Any `fi` data type	`fisingle`	`fisingle`

Examples

Example 1

The following example shows the difference between the absolute value results for the most negative value representable by a signed data type when OverflowMode is saturate or wrap.

P = fipref('NumericTypeDisplay','full',...
           'FimathDisplay','full');
a = fi(-128) 

a =
 
  -128

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 8

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true


abs(a) 

ans =
 
  127.9961

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 8

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

a.OverflowMode = 'wrap' 

a =
 
  -128

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 8

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

abs(a) 

ans =
 
  -128

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 8

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

Example 2

The following example shows the difference between the absolute value results for complex and real fi inputs that have the most negative value representable by a signed data type when OverflowMode is wrap.

re = fi(-1,1,16,15)

re =
 
    -1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

im = fi(0,1,16,15)

im =
 
     0

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

a = complex(re,im)

a =
 
    -1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

abs(a,re.numerictype,fimath('overflowmode','wrap'))

ans =
 
    1.0000

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

abs(re,re.numerictype,fimath('overflowmode','wrap'))

ans =
 
    -1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

Example 3

The following example shows how to specify numerictype and fimath objects as optional arguments to control the result of the abs function for real inputs.

a = fi(-1,1,6,5,'overflowmode','wrap')

a =
 
    -1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 6
        FractionLength: 5

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

abs(a)

ans =
 
    -1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 6
        FractionLength: 5

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

f = fimath('overflowmode','saturate')

f =
 

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

abs(a,f)

ans =
 
    0.9688

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 6
        FractionLength: 5

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

t = numerictype(a.numerictype, 'signed', false)

t =
 

          DataTypeMode: Fixed-point: binary point scaling
                Signed: false
            WordLength: 6
        FractionLength: 5

abs(a,t,f)

ans =
 
     1

          DataTypeMode: Fixed-point: binary point scaling
                Signed: false
            WordLength: 6
        FractionLength: 5

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

Example 4

The following example shows how to specify numerictype and fimath objects as optional arguments to control the result of the abs function for complex inputs.

a = fi(-1-i,1,16,15,'overflowmode','wrap')

a =
 
  -1.0000 - 1.0000i

          DataTypeMode: Fixed-point: binary point scaling
                Signed: true
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

t = numerictype(a.numerictype,'signed',false)

t =
 

          DataTypeMode: Fixed-point: binary point scaling
                Signed: false
            WordLength: 16
        FractionLength: 15

abs(a,t)

ans =
 
    1.4142

          DataTypeMode: Fixed-point: binary point scaling
                Signed: false
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: wrap
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

f = fimath('overflowmode','saturate','summode',...
        'keepLSB','sumwordlength',a.wordlength,...
        'productmode','specifyprecision',...
        'productwordlength',a.wordlength,...
        'productfractionlength',a.fractionlength)

f =
 

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: SpecifyPrecision
     ProductWordLength: 16
 ProductFractionLength: 15
               SumMode: KeepLSB
         SumWordLength: 16
         CastBeforeSum: true

abs(a,t,f)

ans =
 
    1.4142

          DataTypeMode: Fixed-point: binary point scaling
                Signed: false
            WordLength: 16
        FractionLength: 15

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: SpecifyPrecision
     ProductWordLength: 16
 ProductFractionLength: 15
               SumMode: KeepLSB
         SumWordLength: 16
         CastBeforeSum: true

Algorithm

The absolute value y of a real input a is defined as follows:

y = a if a >= 0

y = -a if a < 0

The absolute value y of a complex input a is related to its real and imaginary parts as follows:

y = sqrt(real(a)*real(a) + imag(a)*imag(a))

The abs function computes the absolute value of complex inputs as follows:

Calculate the real and imaginary parts of a using the following equations:
re = real(a)
im = imag(a)
Compute the squares of re and im using one of the following objects:
- The fimath object F if F is specified as an argument.
- The fimath object of a if F is not specified as an argument.
Cast the squares of re and im to unsigned types if the input is signed.
Add the squares of re and im using one of the following objects:
- The fimath object F if F is specified as an argument.
- The fimath object of a if F is not specified as an argument.
Compute the square root of the sum computed in step four using the sqrt function with the following additional arguments:
- The numerictype object T if T is specified, or the numerictype object of a otherwise.
- The fimath object F if F is specified, or the fimath object of a otherwise.

Note Step three prevents the sum of the squares of the real and imaginary components from being negative. This is important because if either re or im has the maximum negative value and the OverflowMode property is set to wrap then an error will occur when taking the square root in step five.

Functions — Alphabetical List

add

abs - Absolute value of fi object