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×2ProductFixedExponent

    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×2ProductFixedExponent

    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=SumSlopeAdjustmentFactor×2SumFixedExponent

    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=SumSlopeAdjustmentFactor×2SumFixedExponent

    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 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=SumSlopeAdjustmentFactor×2SumFixedExponent

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

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

Ws=integer length+Fs

where

integer length=max(WaFa,WbFb)+ceil(log2(NumberOfSummands))

and

Fs=max(Fa,Fb)

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

Ws=specified in the SumWordLength propertyFs=max(Fa,Fb)

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

Ws=specified in the SumWordLength propertyFs=Wsinteger length

where

integer length=max(WaFa,WbFb)+ceil(log2(NumberOfSummands))

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×2ProductFixedExponent

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

Wp=Wa+WbFp=Fa+Fb

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

Wp=specified in the ProductWordLength propertyFp=Fa+Fb

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

Wp=specified in the ProductWordLength propertyFp=Wpinteger length

where

integer length=(Wa+Wb)(FaFb)

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
Was this topic helpful?