fimath Object Properties

Math, Rounding, and Overflow Properties

You can always write to the following properties of `fimath` objects:

PropertyDescriptionValid Values
`CastBeforeSum`

Whether both operands are cast to the sum data type before addition

• `0` (default) — do not cast before sum

• `1` — cast before sum

Note

This property is hidden when the `SumMode` is set to `FullPrecision`.

`MaxProductWordLength`

Maximum allowable word length for the product data type

• `65535` (default)

• Any positive integer

`MaxSumWordLength`

Maximum allowable word length for the sum data type

• `65535` (default)

• Any positive integer

`OverflowAction`

Action to take on overflow

• `Saturate` (default) — Saturate to maximum or minimum value of the fixed-point range on overflow.

• `Wrap` — Wrap on overflow. This mode is also known as two's complement overflow.

`ProductBias`

Bias of the product data type

• `0` (default)

• Any floating-point number

`ProductFixedExponent`

Fixed exponent of the product data type

• `-30` (default)

• Any positive or negative integer

Note

The `ProductFractionLength` is the negative of the `ProductFixedExponent`. Changing one property changes the other.

`ProductFractionLength`

Fraction length, in bits, of the product data type

• `30` (default)

• Any positive or negative integer

Note

The `ProductFractionLength` is the negative of the `ProductFixedExponent`. Changing one property changes the other.

`ProductMode`

Defines how the product data type is determined

• `FullPrecision` (default) — The full precision of the result is kept.

• `KeepLSB`— Keep least significant bits. Specify the product word length, while the fraction length is set to maintain the least significant bits of the product.

• `KeepMSB` — Keep most significant bits. Specify the product word length, while the fraction length is set to maintain the most significant bits of the product.

• `SpecifyPrecision`— specify the word and fraction lengths or slope and bias of the product.

`ProductSlope`

Slope of the product data type

• `9.3132e-010` (default)

• Any floating-point number

Note

`$ProductSlope=ProductSlopeAdjustmentFactor×{2}^{ProductFixedExponent}$`

Changing one of these properties affects the others.

`ProductSlopeAdjustmentFactor`

Slope adjustment factor of the product data type

• `1` (default)

• Any floating-point number greater than or equal to 1 and less than 2

Note

`$ProductSlope=ProductSlopeAdjustmentFactor×{2}^{ProductFixedExponent}$`

Changing one of these properties affects the others.

`ProductWordLength`

Word length, in bits, of the product data type

• `32` (default)

• Any positive integer

`RoundingMethod`

Rounding method

• `Nearest` (default) — Round toward nearest. Ties round toward positive infinity.

• `Ceiling` — Round toward positive infinity.

• `Convergent` — Round toward nearest. Ties round to the nearest even stored integer (least biased).

• `Zero` — Round toward zero.

• `Floor` — Round toward negative infinity.

• `Round` — Round toward nearest. Ties round toward negative infinity for negative numbers, and toward positive infinity for positive numbers.

`SumBias`

Bias of the sum data type

• `0` (default)

• Any floating-point number

`SumFixedExponent`

Fixed exponent of the sum data type

• `-30` (default)

• Any positive or negative integer

Note

The `SumFractionLength` is the negative of the `SumFixedExponent`. Changing one property changes the other.

`SumFractionLength`

Fraction length, in bits, of the sum data type

• `30` (default)

• Any positive or negative integer

Note

The `SumFractionLength` is the negative of the `SumFixedExponent`. Changing one property changes the other.

`SumMode`

Defines how the sum data type is determined

• `FullPrecision` (default) — The full precision of the result is kept.

• `KeepLSB` — Keep least significant bits. Specify the sum data type word length, while the fraction length is set to maintain the least significant bits of the sum.

• `KeepMSB` — Keep most significant bits. Specify the sum data type word length, while the fraction length is set to maintain the most significant bits of the sum and no more fractional bits than necessary

• `SpecifyPrecision` — Specify the word and fraction lengths or the slope and bias of the sum data type.

`SumSlope`

Slope of the sum data type

• `9.3132e-010` (default)

• Any floating-point number

Note

`$SumSlope\text{=}SumSlopeAdjustmentFactor×{2}^{SumFixedExponent}$`

Changing one of these properties affects the others.

`SumSlopeAdjustmentFactor`

Slope adjustment factor of the sum data type

• `1` (default)

• Any floating-point number greater than or equal to 1 and less than 2

Note

`$SumSlope\text{=}SumSlopeAdjustmentFactor×{2}^{SumFixedExponent}$`

Changing one of these properties affects the others.

`SumWordLength`

Word length, in bits, of the sum data type

• `32` (default)

• Any positive integer

For details about these properties, refer to the Set fi Object Properties. To learn how to specify properties for `fimath` objects in Fixed-Point Designer™ software, refer to Setting fimath Object Properties.

How Properties are Related

Sum data type properties

The slope of the sum of two `fi` objects is related to the `SumSlopeAdjustmentFactor` and `SumFixedExponent` properties by

`$SumSlope\text{=}SumSlopeAdjustmentFactor×{2}^{SumFixedExponent}$`

If any of these properties are updated, the others are modified accordingly.

In a `FullPrecision` sum, the resulting word length is represented by

where

and

`${F}_{s}=\mathrm{max}\left({F}_{a},{F}_{b}\right)$`

When the `SumMode` is set to `KeepLSB`, the resulting word length and fraction length is determined by

When the `SumMode` is set to `KeepMSB`, the resulting word length and fraction length is determined by

where

When the `SumMode` is set to `SpecifyPrecision`, you specify both the word and fraction length or slope and bias of the sum data type with the `SumWordLength` and `SumFractionLength`, or `SumSlope` and `SumBias` properties respectively.

Product data type properties

The slope of the product of two `fi` objects is related to the `ProductSlopeAdjustmentFactor` and `ProductFixedExponent` properties by

`$ProductSlope=ProductSlopeAdjustmentFactor×{2}^{ProductFixedExponent}$`

If any of these properties are updated, the others are modified accordingly.

In a `FullPrecision` multiply, the resulting word length and fraction length are represented by

`$\begin{array}{l}{W}_{p}={W}_{a}+{W}_{b}\\ {F}_{p}={F}_{a}+{F}_{b}\end{array}$`

When the `ProductMode` is `KeepLSB` the word length and fraction length are determined by

When the `ProductMode` is `KeepMSB` the word length and fraction length are

where

When the `ProductMode` is set to `SpecifyPrecision`, you specify both the word and fraction length or slope and bias of the product data type with the `ProductWordLength` and `ProductFractionLength`, or `ProductSlope` and `ProductBias` properties respectively.

For more information about how certain functions use the `fimath` properties, see

Setting fimath Object Properties

Setting fimath Properties at Object Creation

You can set properties of `fimath` objects at the time of object creation by including properties after the arguments of the `fimath` constructor function.

For example, to set the overflow action to `Saturate` and the rounding method to `Convergent`,

`F = fimath('OverflowAction','Saturate','RoundingMethod','Convergent')`
```F = RoundingMethod: Convergent OverflowAction: Saturate ProductMode: FullPrecision SumMode: FullPrecision```

In addition to creating a `fimath` object at the command line, you can also set `fimath` properties using the Insert fimath Constructor dialog box. For an example of this approach, see Building fimath Object Constructors in a GUI.

Using Direct Property Referencing with fimath

You can reference directly into a property for setting or retrieving `fimath` object property values using MATLAB® structure-like referencing. You do so by using a period to index into a property by name.

For example, to get the `RoundingMethod` of `F`,

`F.RoundingMethod`
```ans = 'Convergent'```

To set the `OverflowAction` of `F`,

`F.OverflowAction = 'Wrap'`
```F = RoundingMethod: Convergent OverflowAction: Wrap ProductMode: FullPrecision SumMode: FullPrecision```