fixed.Quantizer

Quantize fixed-point numbers

fixed.Quantizer is not recommended. Use cast, zeros, ones, eye, or subsasgn instead. For more information, see Compatibility Considerations.

Description

The fixed.Quantizer object describes data type properties to use for quantization. After you create a fixed.Quantizer object, use quantize to quantize fi values.

Creation

Syntax

q = fixed.Quantizer

q = fixed.Quantizer(nt,rm,oa)

q = fixed.Quantizer(s,wl,fl,rm,oa)

q = fixed.Quantizer(Name,Value)

Description

q = fixed.Quantizer creates a quantizer object q that quantizes fixed-point numbers using the fixed-point settings of q.

q = fixed.Quantizer(nt,rm,oa) creates a fixed-point quantizer object with numerictype nt, rounding method rm, and overflow action oa.

The numerictype, rounding method, and overflow action apply only during the quantization. The output q does not have an attached fimath.

q = fixed.Quantizer(s,wl,fl,rm,oa) creates a binary-point scaled fixed-point quantizer object with signedness s, word length wl, fraction length fl, rounding method rm, and overflow action oa.

q = fixed.Quantizer(Name,Value) creates a quantizer object with the property options specified by one or more property Name,Value arguments.

Input Arguments

nt — numerictype object

numerictype(true,16,15) (default) | numerictype object

numerictype object that describes a binary-point scaled or a slope-bias scaled fixed-point data type, specified as a numerictype object.

If fixed.Quantizer uses a numerictype object that has either a Signedness of Auto or unspecified Scaling, an error occurs.

rm — Rounding method

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

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

• 'Ceiling' — Round up to the next allowable quantized value.

• 'Convergent' — Round to the nearest allowable quantized value. Numbers that are exactly halfway between the two nearest allowable quantized values are rounded up only if the least significant bit after rounding would be set to 0.

• 'Floor' — Round down to the next allowable quantized value.

• 'Nearest' — Round to the nearest allowable quantized value. Numbers that are halfway between the two nearest allowable quantized values are rounded up.

• 'Round' — Round to the nearest allowable quantized value. Numbers that are halfway between the two nearest allowable quantized values are rounded up in absolute value.

• 'Zero' — Round negative numbers up and positive numbers down to the next allowable quantized value.

oa — Action to take on overflow

'Wrap' (default) | 'Saturate'

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

• 'Saturate' — Overflows saturate.

  When the values of data to be quantized lie outside the range of the largest and smallest representable numbers as specified by the numeric type properties, these values are quantized to the value of either the largest or smallest representable value, depending on which is closest.

• 'Wrap' — Overflows wrap.

  When the values of data to be quantized lie outside the range of the largest and smallest representable numbers as specified by the numeric type properties, these values are wrapped back into that range using modular arithmetic relative to the smallest representable number.

s — Whether output is signed

1 or true (default) | 0 or false

Whether output is signed, specified as one of the following:

• 1 or true — Signed

• 0 or false — Unsigned

wl — Word length

16 (default) | positive scalar integer

Word length of the stored integer value of the output data in bits, specified as a positive scalar integer.

fl — Fraction length

15 (default) | scalar integer

Fraction length of the stored integer value of the output data in bits, specified as a scalar integer.

Properties

Bias — Bias

0 (default) | scalar integer

Bias associated with the quantizer object, specified as a scalar integer.

The bias is a part of the numerical representation used to interpret a fixed-point number. Along with the slope, the bias forms the scaling of the number. For more information, see Fixed-point numbers.

FixedExponent — Fixed-point exponent

-15 (default) | scalar integer

Fixed-point exponent associated with the quantizer object, specified as a scalar integer. The exponent is part of the numerical representation used to interpret a fixed-point number. The exponent of a fixed-point number is equal to the negative of the fraction length. For more information, see Fixed-point numbers.

FractionLength — Fraction length

15 (default) | scalar integer

Fraction length of the stored integer value of the object, in bits, specified as a scalar integer.

The fraction length automatically defaults to the best precision possible based on the value of the word length and the real-world value of the fi object being quantized.

OverflowAction — Action to take on overflow

'Wrap' (default) | 'Saturate'

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

• 'Saturate' — Overflows saturate.

  When the values of data to be quantized lie outside the range of the largest and smallest representable numbers, as specified by the numeric type properties, these values are quantized to the value of either the largest or smallest representable value, depending on which is closest.

• 'Wrap' — Overflows wrap.

  When the values of data to be quantized lie outside the range of the largest and smallest representable numbers, as specified by the numeric type properties, these values are wrapped back into that range using modular arithmetic relative to the smallest representable number.

Data Types: char

RoundingMethod — Rounding method

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

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

• 'Ceiling' — Round up to the next allowable quantized value.

• 'Convergent' — Round to the nearest allowable quantized value. Numbers that are exactly halfway between the two nearest allowable quantized values are rounded up only if the least significant bit after rounding would be set to 0.

• 'Floor' — Round down to the next allowable quantized value.

• 'Nearest' — Round to the nearest allowable quantized value. Numbers that are halfway between the two nearest allowable quantized values are rounded up.

• 'Round' — Round to the nearest allowable quantized value. Numbers that are halfway between the two nearest allowable quantized values are rounded up in absolute value.

• 'Zero' — Round negative numbers up and positive numbers down to the next allowable quantized value.

Data Types: char

Signed — Whether output is signed

1 or true (default) | 0 or false

Whether output is signed, specified as one of the following:

• 1 or true — Signed

• 0 or false — Unsigned

Note

Although the Signed property is still supported, the Signedness property always appears in the fixed.Quantizer object display. If you choose to change or set the signedness of your fixed.Quantizer object using the Signed property, MATLAB^® updates the corresponding value of the Signedness property.

Signedness — Whether output is signed

'Signed' (default) | 'Unsigned'

Whether output is signed, specified as 'Signed' or 'Unsigned'.

Slope — Slope associated with object

2^-15 (default) | positive scalar

Slope associated with the object. The slope is part of the numerical representation used to express a fixed-point number. Along with the bias, the slope forms the scaling of a fixed-point number. For more information, see Fixed-point numbers.

SlopeAdjustmentFactor — Slope adjustment associated with object

1 (default) | scalar greater than or equal to 1 and less than 2

Slope adjustment associated with the object, specified as a scalar greater than or equal to 1 and less than 2. The slope adjustment is equivalent to the fractional slope of a fixed-point number. The fractional slope is part of the numerical representation used to express a fixed-point number. For more information, see Fixed-point numbers.

WordLength — Word length

16 (default) | positive scalar integer

Word length of the stored integer value of the output data, in bits, specified as a positive scalar integer.

Object Functions

quantize

Quantize fi values using fixed.Quantizer object

Examples

Reduce Word Length Resulting From Adding Two Fixed-Point Numbers

Use fixed.Quantizer to reduce the word length that results from adding two fixed-point numbers.

q = fixed.Quantizer
x1 = fi(0.1,1,16,15);
x2 = fi(0.8,1,16,15);
y  = quantize(q,x1+x2)

q = 

  fixed.Quantizer with properties:

                   Signed: 1
               WordLength: 16
    SlopeAdjustmentFactor: 1
            FixedExponent: -15
                     Bias: 0
               Signedness: 'Signed'
                    Slope: 3.0518e-05
           FractionLength: 15
           RoundingMethod: 'Floor'
           OverflowAction: 'Wrap'


y = 

    0.9000

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

Quantize Binary-Point Scaled Fixed-Point fi to Slope-Bias Scaled Fixed-Point fi

Use a fixed.Quantizer object to change a binary-point scaled fixed-point fi to a slope-bias scaled fixed-point fi.

x = fi(pi,1,16,13)
q = fixed.Quantizer(numerictype(1,7,1.6,0.2),'Round','Saturate')
y = quantize(q,x)

x = 

    3.1416

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

q = 

  fixed.Quantizer with properties:

                   Signed: 1
               WordLength: 7
    SlopeAdjustmentFactor: 1.6000
            FixedExponent: 0
                     Bias: 0.2000
               Signedness: 'Signed'
                    Slope: 1.6000
           FractionLength: 0
           RoundingMethod: 'Round'
           OverflowAction: 'Saturate'


y = 

    3.4000

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 7
                 Slope: 1.6
                  Bias: 0.2

More About

Fixed-point numbers

Fixed-point numbers can be represented as

$$real\text{-}worldvalue=(slope\times storedinteger)+bias$$

where the slope can be expressed as

$$slope=fractionalslope\times 2^{fixedexponent}$$

Tips

• Use y = quantize(q,x) to quantize input array x using the fixed-point settings of the quantizer object q. x can be any fixed-point fi number, except a Boolean value. If x is a scaled double, the x and y data will be the same, but y will have fixed-point settings. If x is a double or single, then y = x. This functionality lets you share the same code for both floating-point data types and fi objects when quantizers are present.

• Use n = numerictype(q) to get a numerictype for the current settings of the quantizer object q.

• Use clone(q) to create a quantizer object with the same property values as q.

Extended Capabilities

C/C++ Code Generation

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

fixed.Quantizer is a handle object and must be declared as persistent in code generation.

Version History

Introduced in R2011b

R2013a: fixed.Quantizer is not recommended

fixed.Quantizer is not recommended. Use cast, zeros, ones, eye, or subsasgn instead. There are no plans to remove fixed.Quantizer.

Starting in R2013a, use cast, zeros, ones, eye, or subsasgn instead. The cast, zeros, ones, eye, and subsasgn functions can quantize other data types in addition to fi objects.

Not Recommended	Recommended
x = fi(pi,1,16,13); q = fixed.Quantizer(numerictype(1,7,1.6,0.2),'Round','Saturate'); y = quantize(q,x) y = 3.4000 DataTypeMode: Fixed-point: slope and bias scaling Signedness: Signed WordLength: 7 Slope: 1.6 Bias: 0.2	x = fi(pi,1,16,13); F = fimath('RoundingMethod','Round','OverflowAction','Saturate'); nt = fi([],1,7,1.6,0.2,F); y = cast(x,'like',nt) y = 3.4000 DataTypeMode: Fixed-point: slope and bias scaling Signedness: Signed WordLength: 7 Slope: 1.6 Bias: 0.2