fimath Properties Usage for Fixed-Point Arithmetic

fimath Rules for Fixed-Point Arithmetic

fimath properties define the rules for performing arithmetic operations on fi objects. The fimath properties that govern fixed-point arithmetic operations can come from a local fimath object or the fimath default values.

To determine whether a fi object has a local fimath object, use the isfimathlocal function.

The following sections discuss how fi objects with local fimath objects interact with fi objects without local fimath.

Binary Operations

In binary fixed-point operations such as c = a + b, the following rules apply:

If both a and b have no local fimath, the operation uses default fimath values to perform the fixed-point arithmetic. The output fi object c also has no local fimath.
If either a or b has a local fimath object, the operation uses that fimath object to perform the fixed-point arithmetic. The output fi object c has the same local fimath object as the input.

Unary Operations

In unary fixed-point operations such as b = abs(a), the following rules apply:

If a has no local fimath, the operation uses default fimath values to perform the fixed-point arithmetic. The output fi object b has no local fimath.
If a has a local fimath object, the operation uses that fimath object to perform the fixed-point arithmetic. The output fi object b has the same local fimath object as the input a.

When you specify a fimath object in the function call of a unary fixed-point operation, the operation uses the fimath object you specify to perform the fixed-point arithmetic. For example, when you use a syntax such as b = abs(a,F) or b = sqrt(a,F), the abs and sqrt operations use the fimath object F to compute intermediate quantities. The output fi object b always has no local fimath.

Concatenation Operations

In fixed-point concatenation operations such as c = [a b], c = [a;b] and c = bitconcat(a,b), the following rule applies:

The fimath properties of the leftmost fi object in the operation determine the fimath properties of the output fi object c.

For example, consider the following scenarios for the operation d = [a b c]:

If a is a fi object with no local fimath, the output fi object d also has no local fimath.
If a has a local fimath object, the output fi object d has the same local fimath object.
If a is not a fi object, the output fi object d inherits the fimath properties of the next leftmost fi object. For example, if b is a fi object with a local fimath object, the output fi object d has the same local fimath object as the input fi object b.

fimath Object Operations: add, mpy, sub

The output of the fimath object operations add, mpy, and sub always have no local fimath. The operations use the fimath object you specify in the function call, but the output fi object never has a local fimath object.

MATLAB Function Block Operations

Fixed-point operations performed with the MATLAB Function block use the same rules as fixed-point operations performed in MATLAB^®.

All input signals to the MATLAB Function block that you treat as fi objects associate with whatever you specify for the MATLAB Function block fimath parameter. When you set this parameter to Same as MATLAB, your fi objects do not have local fimath. When you set the MATLAB Function block fimath parameter to Specify other, you can define your own set of fimath properties for all fi objects in the MATLAB Function block to associate with. You can choose to treat only fixed-point input signals as fi objects or both fixed-point and integer input signals as fi objects. See Use fimath Objects in MATLAB Function Blocks.

Binary-Point Arithmetic

The fimath object encapsulates the math properties of Fixed-Point Designer™ software.

fi objects only have a local fimath object when you explicitly specify fimath properties in the fi constructor. When you use the sfi or ufi constructor or do not specify any fimath properties in the fi constructor, the resulting fi object does not have any local fimath and uses default fimath values.

a = fi(pi)

a = 

    3.1416

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

a.fimath
isfimathlocal(a)

ans = 


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

ans =

  logical

   0

To perform arithmetic with +, -, .*, or * on two fi operands with local fimath objects, the local fimath objects must be identical. If one of the fi operands does not have a local fimath, the fimath properties of the two operands need not be identical. See fimath Rules for Fixed-Point Arithmetic for more information.

a = fi(pi);
b = fi(8);
isequal(a.fimath, b.fimath)

ans =

  logical

   1

a + b

ans = 

   11.1416

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 19
        FractionLength: 13

To perform arithmetic with +, -, .*, or *, two fi operands must also have the same data type. For example, you can add two fi objects with data type double, but you cannot add an object with data type double and one with data type single:

a = fi(3, 'DataType', 'double')

a = 

     3

          DataTypeMode: Double

b = fi(27, 'DataType', 'double')

b = 

    27

          DataTypeMode: Double

a + b

ans = 

    30

          DataTypeMode: Double

c = fi(12, 'DataType', 'single')

c = 

    12

          DataTypeMode: Single

a + c

Error using  +  (line 24)
Math operations are not allowed on fi objects with different data types.

Fixed-point fi object operands do not have to have the same scaling. You can perform binary math operations on a fi object with a fixed-point data type and a fi object with a scaled doubles data type. In this sense, the scaled double data type acts as a fixed-point data type:

a = fi(pi)

a = 

    3.1416

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

b = fi(magic(2), ...
'DataTypeMode', 'Scaled double: binary point scaling')

b = 

     1     3
     4     2


          DataTypeMode: Scaled double: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 12

a + b

ans = 

    4.1416    6.1416
    7.1416    5.1416


          DataTypeMode: Scaled double: binary point scaling
            Signedness: Signed
            WordLength: 18
        FractionLength: 13

Use the divide function to perform division with doubles, singles, or binary point-only scaling fi objects.

[Slope Bias] Arithmetic

Fixed-Point Designer software supports fixed-point arithmetic using the local fimath object or default fimath for all binary point-only signals. The toolbox also supports arithmetic for [Slope Bias] signals with the following restrictions:

[Slope Bias] signals must be real.
You must set the SumMode and ProductMode properties of the governing fimath to 'SpecifyPrecision' for sum and multiply operations, respectively.
You must set the CastBeforeSum property of the governing fimath to 'true'.
Fixed-Point Designer does not support the divide function for [Slope Bias] signals.

f = fimath('SumMode', 'SpecifyPrecision', ...
           'SumFractionLength', 16)

f = 


        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: SpecifyPrecision
         SumWordLength: 32
     SumFractionLength: 16
         CastBeforeSum: true

a = fi(pi, 'fimath', f)

a = 

    3.1416

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

        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: SpecifyPrecision
         SumWordLength: 32
     SumFractionLength: 16
         CastBeforeSum: true

b = fi(22, true, 16, 2^-8, 3, 'fimath', f)

b = 

    22

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.00390625
                  Bias: 3

        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: SpecifyPrecision
         SumWordLength: 32
     SumFractionLength: 16
         CastBeforeSum: true

a + b

ans = 

   25.1416

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

        RoundingMethod: Nearest
        OverflowAction: Saturate
           ProductMode: FullPrecision
               SumMode: SpecifyPrecision
         SumWordLength: 32
     SumFractionLength: 16
         CastBeforeSum: true

Setting the SumMode and ProductMode properties to SpecifyPrecision are mutually exclusive except when performing the * operation between matrices. In this case, you must set both the SumMode and ProductMode properties to SpecifyPrecision for [Slope Bias] signals. Doing so is necessary because the * operation performs both sum and multiply operations to calculate the result.