abs

Absolute value of fi object

Syntax

y = abs(a)

y = abs(a,T)

y = abs(a,F)

y = abs(a,T,F)

Description

y = abs(a) returns the absolute value of fi object a with the same numerictype object as a. Intermediate quantities are calculated using the fimath associated with a. The output fi object, y, has the same local fimath as a.

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

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

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

Examples

Absolute Value of Most Negative Representable Value

This example shows the difference between the absolute value results for the most negative value representable by a signed data type when the 'OverflowAction' property is set to 'Saturate' or 'Wrap'.

Calculate the absolute value when the 'OverflowAction' is set to the default value 'Saturate'.

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

a = 

  -128

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

y = 

  127.9961

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

abs returns 127.9961, which is a result of saturation to the maximum positive value.

Calculate the absolute value when the 'OverflowAction' is set to 'Wrap'.

a.OverflowAction = 'Wrap'
y = abs(a)

a = 

  -128

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

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

y = 

  -128

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

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

abs returns 128, which is a result of wrapping back to the most negative value.

Difference Between Absolute Values for Real and Complex fi Inputs

This 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 the 'OverflowAction' property is set to 'Wrap'.

Define a complex fi object.

re = fi(-1,1,16,15);
im = fi(0,1,16,15);
a = complex(re,im)

a = 

  -1.0000 + 0.0000i

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

a is complex, but numerically equal to the real part, re.

Calculate the absolute value of the complex fi object.

y = abs(a,re.numerictype,fimath('OverflowAction','Wrap'))

y = 

    1.0000

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

Calculate the absolute value of the real fi object.

y = abs(re,re.numerictype,fimath('OverflowAction','Wrap'))

y = 

    -1

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

Specify numerictype and fimath Inputs to Control the Result of abs for Real Inputs

This example shows how to specify numerictype and fimath objects as optional arguments to control the result of the abs function for real inputs. When you specify a fimath object as an argument, that fimath object is used to compute intermediate quantities, and the resulting fi object has no local fimath.

a = fi(-1,1,6,5,'OverflowAction','Wrap');
y = abs(a)

y = 

    -1

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

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

The returned output is identical to the input. This may be undesirable because the absolute value is expected to be positive.

F = fimath('OverflowAction','Saturate');
y = abs(a,F)

y = 

    0.9688

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

The returned fi object is saturated to a value of 0.9688 and has the same numerictype object as the input.

Because the output of abs is always expected to be positive, an unsigned numerictype may be specified for the output.

T = numerictype(a.numerictype, 'Signed', false);
y = abs(a,T,F)

y = 

     1

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 6
        FractionLength: 5

Specifying an unsigned numerictype enables better precision.

Specify numerictype and fimath Inputs to Control the Result of abs for Complex Inputs

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

Specify a numerictype input and calculate the absolute value of a.

a = fi(-1-i,1,16,15,'OverflowAction','Wrap');
T = numerictype(a.numerictype,'Signed',false);
y = abs(a,T)

y = 

    1.4142

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 16
        FractionLength: 15

        RoundingMethod: Nearest
        OverflowAction: Wrap
           ProductMode: FullPrecision
               SumMode: FullPrecision

A fi object is returned with a value of 1.4142 and the specified unsigned numerictype. The fimath used for intermediate calculation and the fimath of the output are the same as that of the input.

Now specify a fimath object different from that of a.

F = fimath('OverflowAction','Saturate','SumMode',...
        'KeepLSB','SumWordLength',a.WordLength,...
        'ProductMode','specifyprecision',...
        'ProductWordLength',a.WordLength,...
        'ProductFractionLength',a.FractionLength);
y = abs(a,T,F)

y = 

    1.4142

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Unsigned
            WordLength: 16
        FractionLength: 15

The specified fimath object is used for intermediate calculation. The fimath associated with the output is the default fimath.

Input Arguments

a — Input fi array

scalar | vector | matrix | multidimensional array

Input fi array, specified as a scalar, vector, matrix, or multidimensional array.

abs only supports fi objects with trivial [Slope Bias] scaling, that is, when the bias is 0 and the fractional slope is 1.

abs uses a different algorithm for real and complex inputs. For more information, see Absolute Value.

Data Types: fi
Complex Number Support: Yes

T — numerictype of the output

numerictype object

numerictype of the output fi object y, specified as a numerictype object. For more information, see Data Type Propagation Rules.

Example: T = numerictype(0,24,12,'DataType','Fixed')

F — Fixed-point math settings to use

fimath object

Fixed-point math settings to use for the calculation of absolute value, specified as a fimath object.

Example: F = fimath('OverflowAction','Saturate','RoundingMethod','Convergent')

Algorithms

Absolute Value

The absolute value of a real number is the corresponding nonnegative value that disregards the sign.

For a real input, a, the absolute value, y, is:

y = a if a >= 0

(1)

y = -a if a < 0

(2)

abs(-0) returns 0.

Note

When the fi 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 'OverflowAction' property is set to 'Saturate'. If 'OverflowAction' is 'Wrap', the absolute value of the most negative value has no effect.

For a complex input, a, the absolute value, y, is related to its real and imaginary parts as follows:

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

(3)

The abs function computes the absolute value of a complex input, a, as follows:

1. Calculate the real and imaginary parts of a.

   re = real(a)

   (4)

   im = imag(a)

   (5)

2. 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 associated with a if F is not specified as an argument.

3. If the input is signed, cast the squares of re and im to unsigned types.

4. 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 associated with a if F is not specified as an argument.

5. Compute the square root of the sum computed in Step 4 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 associated with a otherwise.

Note

Step 3 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 'OverflowAction' property is set to 'Wrap' then an error will occur when taking the square root in Step 5.

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 y
fi Fixed	fi Fixed	Data type of numerictype object T
fi ScaledDouble	fi Fixed	ScaledDouble with properties of numerictype object T
fi double	fi Fixed	fi double
fi single	fi Fixed	fi single
Any fi data type	fi double	fi double
Any fi data type	fi single	fi single

Note

When the Signedness of the input numerictype object T is Auto, the abs function always returns an Unsigned fi object.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

HDL Code Generation

Generate Verilog and VHDL code for FPGA and ASIC designs using HDL Coder™.

Double and complex data types are not supported.