Using fimath Properties to Perform Fixed-Point Arithmetic :: Working with fimath Objects (Fixed-Point Toolbox™)

Using fimath Properties to Perform Fixed-Point Arithmetic

On this page…
fimath Rules for Fixed-Point Arithmetic Binary-Point Arithmetic [Slope Bias] Arithmetic

On this page…

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 fimath object or the global fimath. fimath objects and the global fimath have the following differences:

Individual fi objects can have a fimath object attached to them. fi objects have an attached fimath object when you specify fimath properties in a fi constructor or use dot notation to set a fimath object property of a fi object.
The global fimath is the set of fimath properties that fi constructors associate with, and fimath constructors return, when you do not specify any fimath properties in the constructor. When you use the sfi or ufi constructor or when you fail to specify any fimath properties in the fi constructor, the resulting fi object associates itself with the global fimath. It does not have its own attached fimath object. See Working with the Global fimath for more information.

To determine whether a fi object has its own fimath object or associates with the global fimath, use the isfimathlocal function.

The following sections discuss the rules for when a fi object with an attached fimath object interacts with a fi object associated with the global fimath.

Binary Operations

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

If both a and b associate with the global fimath, the operation uses the global fimath to perform the fixed-point arithmetic. The output fi object c also associates with the global fimath.
If either a or b has an attached fimath object, the operation uses that attached fimath object to perform the fixed-point arithmetic. The fimath object used for the operation gets attached to the output fi object c.

Unary Operations

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

If a associates with the global fimath, the operation uses the global fimath to perform the fixed-point arithmetic. The output fi object b also associates with the global fimath.
If a has an attached fimath object, the operation uses that fimath object to perform the fixed-point arithmetic. The fimath object used for the operation attaches to the output fi object b.

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 associates with the global 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 left-most 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 associated with the global fimath, the output fi object d also associates with the global fimath.
If a has its own fimath object, that fimath object also attaches to the output fi object d.
If a is not a fi object, the output fi object d inherits the fimath properties of the next left-most fi object. For example, if b is a fi object with an attached fimath object, the output fi object d has the same attached 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 associates with the global fimath. The operations use the fimath object you specify in the function call, but the output fi object never has its own attached fimath object.

Embedded MATLAB Subset Operations

Fixed-point operations performed with Embedded MATLAB subset functions use the same rules as fixed-point operations performed in MATLAB.

All input signals to the Embedded MATLAB Function block that you treat as fi objects associate with whatever you specify for the Embedded MATLAB Function block fimath parameter. When you set this parameter to Same as MATLAB, your fi objects associate with the global fimath. When you set the Embedded MATLAB Function block fimath parameter to Specify other, you can define your own set of fimath properties for all fi objects in the Embedded 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 Using fimath Objects in Embedded MATLAB Function Blocks for more information.

Binary-Point Arithmetic

The fimath object and the global fimath encapsulate the math properties of Fixed-Point Toolbox software.

fi objects only have an attached 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 associates itself with the global fimath.

a = fi(pi)
 
a =
    3.1416

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

a.fimath
isfimathlocal(a)
 
ans =
 

             RoundMode: nearest
          OverflowMode: saturate
           ProductMode: FullPrecision
  MaxProductWordLength: 128
               SumMode: FullPrecision
      MaxSumWordLength: 128
         CastBeforeSum: true

ans =
     0

To perform arithmetic with +, -, .*, or * on two fi operands with attached fimath objects, the fimath objects attached to the operands must be identical. If one of the fi operands is associated with the global 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 =

     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 perform addition on two fi objects with data type double, but not on 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
??? 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 Toolbox software supports fixed-point arithmetic using the fimath object or the global 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 Toolbox does not support the divide function for [Slope Bias] signals.

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

                    RoundMode: nearest
                 OverflowMode: saturate
                  ProductMode: FullPrecision
         MaxProductWordLength: 128
                      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

                    RoundMode: nearest
                 OverflowMode: saturate
                  ProductMode: FullPrecision
         MaxProductWordLength: 128
                      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

                    RoundMode: nearest
                 OverflowMode: saturate
                  ProductMode: FullPrecision
         MaxProductWordLength: 128
                      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

                    RoundMode: nearest
                 OverflowMode: saturate
                  ProductMode: FullPrecision
         MaxProductWordLength: 128
                      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.

fimath Object Properties

Using fimath to Specify Rounding and Overflow Modes

Free Early Verification Kit

Learn how to apply early verification to your development process through these technical resources.

Get technical kit

Trial software available

How much time do you spend on testing to ensure implementation meets system-level requirements?

Learn more