# fimath

Set fixed-point math settings

## Syntax

``F = fimath``
``F = fimath(Name,Value)``

## Description

example

````F = fimath` creates a `fimath` object with the default `fimath` property settings.```

example

````F = fimath(Name,Value)` specifies the properties of a `fimath` object by using one or more name-value pair arguments. All properties not specified in the constructor use default values.```

## Examples

collapse all

This example shows how to create a `fimath` object with the default property settings.

`F = fimath`
```F = RoundingMethod: Nearest OverflowAction: Saturate ProductMode: FullPrecision SumMode: FullPrecision ```

Set the properties of a `fimath` object at the time of object creation by using name-value pairs. For example, 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 ```

## Input Arguments

collapse all

### Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

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

Whether both operands are cast to the sum data type before addition, specified as a numeric or logical `1` (`true`) or `0` (`false`).

Note

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

Example: `F = fimath('CastBeforeSum',true)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `logical`

Maximum allowable word length for the product data type, specified as a positive integer.

Example: `F = fimath('MaxProductWordLength',16)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Maximum allowable word length for the sum data type, specified as a positive integer.

Example: `F = fimath('MaxSumWordLength',16)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Action to take on overflow, specified as one of these values:

• `'Saturate'` – Saturate to the 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.

Example: `F = fimath('OverflowAction','Wrap')`

Data Types: `char`

Bias of the product data type, specified as a floating-point number.

Example: `F = fimath('ProductBias',1)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Fixed exponent of the product data type, specified as a nonzero integer.

Note

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

Example: `F = fimath('ProductFixedExponent',-20)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Fraction length, in bits, of the product data type, specified as a nonzero integer.

Note

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

Example: `F = fimath('ProductFractionLength',20)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

How the product data type is determined, specified as one of these values:

• `'FullPrecision'` – The full precision of the result is kept.

• `'KeepLSB'` – Keep the least significant bits. Specify the product word length. The fraction length is set to maintain the least significant bits of the product.

• `'KeepMSB'` – Keep the most significant bits. Specify the product word length. 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.

Example: `F = fimath('ProductMode','KeepLSB')`

Data Types: `char`

Slope of the product data type, specified as a finite, positive floating-point number.

Note

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

Changing one of these properties affects the others.

Example: `F = fimath('ProductSlope',9.3132e-10)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Slope adjustment factor of the product data type, specified as a 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.

Example: ```F = fimath('ProductSlopeAdjustmentFactor',1)```

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Word length, in bits, of the product data type, specified as a positive integer.

Example: `F = fimath('ProductWordLength',64)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Rounding method to use, specified as one of these values:

• `'Nearest'` – 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.

Example: ```F = fimath('RoundingMethod','Convergent')```

Data Types: `char`

Bias of the sum data type, specified as a floating-point number.

Example: `F = fimath('SumBias',0)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Fixed exponent of the sum data type, specified as a nonzero integer.

Note

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

Example: `F = fimath('SumFixedExponent',-20)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Fraction length, in bits, of the sum data type, specified as a nonzero integer.

Note

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

Example: `F = fimath('SumFractionLength',20)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

How the sum data type is determined, specified as one of these values:

• `'FullPrecision'` – The full precision of the result is kept.

• `'KeepLSB'` – Keep least significant bits. Specify the sum data type word length. 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. 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 slope and bias of the sum data type.

Example: `F = fimath('SumMode','KeepLSB')`

Data Types: `char`

Slope of the sum data type, specified as a floating-point number.

Note

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

Changing one of these properties affects the others.

Example: `F = fimath('SumSlope',9.3132e-10)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Slope adjustment factor of the sum data type, specified as a floating-point number greater than or equal to 1 and less than 2.

Note

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

Changing one of these properties affects the others.

Example: `F = fimath('SumSlopeAdjustmentFactor',1)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Word length, in bits, of the sum data type, specified as a positive integer.

Example: `F = fimath('SumWordLength',64)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

## Version History

Introduced before R2006a

expand all