# abs

Absolute value of `fi` object

## Syntax

``y = abs(a)``
``y = abs(a,T)``
``y = abs(a,F)``
``y = abs(a,T,F)``

## Description

example

````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`.```

example

````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.```

example

````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`.```

example

````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

collapse all

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.

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```

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.

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

collapse all

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

`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')```

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

collapse all

### 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.

## Version History

Introduced before R2006a