fimath

Set fixed-point math settings

Description

The fimath object allows you to set properties that determine the rules for fixed-point arithmetic operations on fi objects.

Creation

Syntax

F = fimath

F = fimath(a)

F = fimath(PropertyName = Value)

Description

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

F = fimath(a) creates a fimath object with the fixed-point math properties of the fi object, a.

F = fimath(PropertyName = 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.

Properties

fimath properties determine the rules for performing fixed-point arithmetic operations on fi objects. fimath properties are, by transitivity, also properties of the fi object. You can set these properties for individual fi objects. fimath object properties are always writable.

Sum Data Type Properties

CastBeforeSum — Cast operands to sum data type before addition

1 (true) (default) | 0 (false)

Whether both operands are cast to the sum data type before addition, specified as a logical value:

• 1 or true - Cast before sum

• 0 or false - Do not cast before sum

This property always returns a logical value.

Note

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

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

MaxSumWordLength — Maximum allowable word length for the sum data type

65535 (default) | positive integer

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

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

SumBias — Bias of the sum data type

0 (default) | floating-point number

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

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

Data Types: single | double | half

SumFixedExponent — Fixed exponent of the sum data type

-30 (default) | integer

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

Note

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

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

SumFractionLength — Fraction length of the sum data type in bits

30 (default) | integer

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

Note

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

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

SumMode — How the sum data type is determined

FullPrecision (default) | KeepLSB | KeepMSB | SpecifyPrecision

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

• FullPrecision — Keep the full precision of the result.

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

Data Types: char

SumSlope — Slope of the sum data type

9.3132e-010 (default) | floating-point number

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

Note

$$SumSlope\text{=}SumSlopeAdjustmentFactor\times 2^{SumFixedExponent}$$

Changing one of these properties affects the others.

Data Types: single | double | half

SumSlopeAdjustmentFactor — Slope adjustment factor of the sum data type

1 (default) | floating-point number greater than or equal to 1 and less than 2

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\text{=}SumSlopeAdjustmentFactor\times 2^{SumFixedExponent}$$

Changing one of these properties affects the others.

Data Types: single | double | half

SumWordLength — Word length of the sum data type in bits

32 (default) | positive integer

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

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

Product Data Type Properties

MaxProductWordLength — Maximum allowable word length for the product data type

65535 (default) | positive integer

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

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

ProductBias — Bias of the product data type

0 (default) | floating-point number

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

Data Types: single | double | half

ProductFixedExponent — Fixed exponent of the product data type

-30 (default) | integer

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

Note

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

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

ProductFractionLength — Fraction length of the product data type in bits

30 (default) | integer

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

Note

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

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

ProductMode — How the product data type is determined

FullPrecision (default) | KeepLSB | KeepMSB | SpecifyPrecision

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

• FullPrecision — Keep the full precision of the result.

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

Data Types: char

ProductSlope — Slope of the product data type

9.3132e-010 (default) | floating-point number

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

Note

$$ProductSlope=ProductSlopeAdjustmentFactor\times 2^{ProductFixedExponent}$$

Changing one of these properties affects the others.

Data Types: single | double | half

ProductSlopeAdjustmentFactor — Slope adjustment factor of the product data type

1 (default) | floating-point number greater than or equal to 1 and less than 2

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\times 2^{ProductFixedExponent}$$

Changing one of these properties affects the others.

Data Types: single | double | half

ProductWordLength — Word length of the product data type in bits

32 (default) | positive integer

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

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

Rounding and Overflow Properties

OverflowAction — Action to take on overflow

Saturate (default) | Wrap

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

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

• Wrap — Wrap on overflow.

Data Types: char

RoundingMethod — Rounding method to use

Nearest (default) | Ceiling | Convergent | Zero | Floor | Round

Rounding method to use, specified as one of the following:

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

Data Types: char

Examples

Create a Default fimath Object

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 Properties of a fimath Object

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

Create a fimath Object from a fi Object

This example shows you how to create a fimath object from an existing fi object.

Create a fi object with default properties and no specified value.

a = fi

a = 

[]

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

Query the fimath properties of a.

a.fimath

ans = 
        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: FullPrecision

Create a fimath object with a as the input.

F = fimath(a)

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

F has the same fimath properties as a.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• Fixed-point signals coming in to a MATLAB^® Function block from Simulink^® are assigned a fimath object. You define this object in the MATLAB Function block dialog box in the Model Explorer.

• Use to create fimath objects in the generated code.

• If the ProductMode property of the fimath object is set to anything other than FullPrecision, the ProductWordLength and ProductFractionLength properties must be constant.

• If the SumMode property of the fimath object is set to anything other than FullPrecision, the SumWordLength and SumFractionLength properties must be constant.

HDL Code Generation
Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

Version History

Introduced before R2006a

R2021a: Inexact property names for fi, fimath, and numerictype objects not supported

In previous releases, inexact property names for fi, fimath, and numerictype objects would result in a warning. In R2021a, support for inexact property names was removed. Use exact property names instead.