quantize

Quantize fixed-point numbers

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

Syntax

y = quantize(x)

y = quantize(x,nt)

y = quantize(x,nt,rm)

y = quantize(x,nt,rm,oa)

yBP = quantize(x,s)

yBP = quantize(x,s,wl)

yBP = quantize(x,s,wl,fl)

yBP = quantize(x,s,wl,fl,rm)

yBP = quantize(x,s,wl,fl,rm,oa)

Description

Quantize Using a numerictype Object

y = quantize(x) quantizes the input x values using the default settings.

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

y = quantize(x,nt) quantizes x to the specified numerictype, nt.

y = quantize(x,nt,rm) quantizes x to the specified numerictype, nt using the specified rounding method, rm.

y = quantize(x,nt,rm,oa) quantizes x to the specified numerictype, nt using the specified rounding method, rm, and overflow action, oa.

Quantize by Specifying Numeric Type Properties

yBP = quantize(x,s) quantizes x to a binary-point scaled fixed-point number with signedness s.

yBP = quantize(x,s,wl) quantizes x to a binary-point scaled fixed-point number with signedness s and word length wl.

yBP = quantize(x,s,wl,fl) quantizes x to a binary-point scaled fixed-point number with signedness s, word length wl, and fraction length fl.

yBP = quantize(x,s,wl,fl,rm) quantizes x to a binary-point scaled fixed-point number with signedness s, word length wl, and fraction length fl using rounding method rm.

yBP = quantize(x,s,wl,fl,rm,oa) quantizes x to a binary-point scaled fixed-point number with signedness s, word length wl, and fraction length fl using rounding method rm and overflow action oa.

Examples

Quantize Binary-Point Scaled to Binary-Point Scaled Data

Define the input fi value to quantize.

x_BP = fi(pi)

x_BP = 
    3.1416

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

Use a numerictype Object

Create numerictype object which specifies a signed fixed-point data type with 8-bit word length and 4-bit fraction length.

ntBP = numerictype(1,8,4);

Use the defined numerictype object ntBP to quantize the input x_BP to a binary-point scaled fixed-point data type.

yBP1 = quantize(x_BP,ntBP)

yBP1 = 
    3.1250

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Specify Numeric Type Properties at the Input

yBP2 = quantize(x_BP,1,8,4)

yBP2 = 
    3.1250

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Quantize Binary-Point Scaled to Slope-Bias Data

Create a numerictype object that specifies a slope-bias scaled fixed-point data type.

ntSB = numerictype('Scaling','SlopeBias',...
      'SlopeAdjustmentFactor',1.8,...
      'Bias',1,...
      'FixedExponent',-12);

Define the input fi value to quantize.

x_BP = fi(pi)

x_BP = 
    3.1416

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

Use the defined numerictype ntSB to quantize the input x_BP to a slope-bias scaled fixed-point data type.

ySB1 = quantize(x_BP, ntSB)

ySB1 = 
    3.1415

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.000439453125
                  Bias: 1

Quantize Slope-Bias Scaled to Binary-Point Scaled Data

Define the input fi values to quantize.

x_SB = fi(rand(5,3),numerictype('Scaling','SlopeBias','Bias',-0.125))

x_SB = 
    0.8147    0.0975    0.1576
    0.8750    0.2785    0.8750
    0.1270    0.5469    0.8750
    0.8750    0.8750    0.4854
    0.6324    0.8750    0.8003

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 3.0517578125e-5
                  Bias: -0.125

Use a numerictype Object

Create a numerictype object ntBP that specifies a signed, binary-point scaled fixed-point data type with 8-bit word length and 4-bit fraction length.

ntBP = numerictype(1,8,4);

Use the defined numerictype ntBP to quantize the input x_SB to a binary-point scaled fixed-point data type. Additionally, round to nearest and saturate on overflow.

yBP1 = quantize(x_SB,ntBP,'Nearest','Saturate')

yBP1 = 
    0.8125    0.1250    0.1875
    0.8750    0.2500    0.8750
    0.1250    0.5625    0.8750
    0.8750    0.8750    0.5000
    0.6250    0.8750    0.8125

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Specify Numeric Type Properties at the Input

yBP2 = quantize(x_SB,1,8,4,'Nearest','Saturate')

yBP2 = 
    0.8125    0.1250    0.1875
    0.8750    0.2500    0.8750
    0.1250    0.5625    0.8750
    0.8750    0.8750    0.5000
    0.6250    0.8750    0.8125

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Quantize Slope-Bias Scaled to Slope-Bias Scaled Data

Define the input fi values to quantize.

x_SB = fi(rand(5,3),numerictype('Scaling','SlopeBias','Bias',-0.125))

x_SB = 
    0.8147    0.0975    0.1576
    0.8750    0.2785    0.8750
    0.1270    0.5469    0.8750
    0.8750    0.8750    0.4854
    0.6324    0.8750    0.8003

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 3.0517578125e-5
                  Bias: -0.125

Create a numerictype object which specifies a slope-bias scaled fixed-point data type.

ntSB = numerictype('Scaling','SlopeBias', ...
      'SlopeAdjustmentFactor',1.8,'Bias',...
      1,'FixedExponent',-12);

Use the defined numerictype ntSB to quantize the input x_SB to a slope-bias scaled fixed-point data type. Additionall, round to ceiling.

ySB2 = quantize(x_SB,ntSB,'Ceiling')

ySB2 = 
    0.8150    0.0978    0.1580
    0.8752    0.2789    0.8752
    0.1272    0.5469    0.8752
    0.8752    0.8752    0.4854
    0.6326    0.8752    0.8005

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.000439453125
                  Bias: 1

Quantize Built-in Integer to Binary-Point Scaled Data

Define the input values to quantize.

xInt = int8(-16:4:16)

xInt = 1x9 int8 row vector

   -16   -12    -8    -4     0     4     8    12    16

Use a numerictype Object

Create a numerictype object that specifies a signed binary-point scaled fixed-point data type with 8-bit word length and 4-bit fraction length.

ntBP = numerictype(1,8,4);

Use the defined numerictype ntBP to quantize the input xInt to a binary-point scaled fixed-point data type.

yBP1 = quantize(xInt,ntBP,'Zero')

yBP1 = 
     0     4    -8    -4     0     4    -8    -4     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Show the range of the quantized output.

range(yBP1)

ans = 
   -8.0000    7.9375

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

The first two and last three values are wrapped because they are outside the representable range of the output type.

Specify Numeric Type Properties at the Input

yBP2 = quantize(xInt,1,8,4,'Zero')

yBP2 = 
     0     4    -8    -4     0     4    -8    -4     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 8
        FractionLength: 4

Quantize Built-in Integer to Slope-Bias Data

Define the input values to quantize.

xInt = int8(-16:4:16)

xInt = 1x9 int8 row vector

   -16   -12    -8    -4     0     4     8    12    16

Create a numerictype object that specifies a slope-bias scaled fixed-point data type.

ntSB = numerictype('Scaling','SlopeBias', ...
      'SlopeAdjustmentFactor',1.8,'Bias',...
      1,'FixedExponent',-12);

Use the defined numerictype ntSB to quantize the input xInt to a slope-bias scaled fixed-point data type.

ySB = quantize(xInt,ntSB,'Round','Saturate')

ySB = 
  -13.4000  -11.9814   -7.9877   -3.9939   -0.0002    3.9936    7.9873   11.9811   15.3996

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.000439453125
                  Bias: 1

Show the range of the quantized output.

range(ySB)

ans = 
  -13.4000   15.3996

          DataTypeMode: Fixed-point: slope and bias scaling
            Signedness: Signed
            WordLength: 16
                 Slope: 0.000439453125
                  Bias: 1

The first and last values saturate because they are at the limits of he representable range of the output type.

Input Arguments

x — Input data to quantize

fi object | built-in integer

Input data to quantize, specified as:

• Built-in signed or unsigned integers

• Binary point scaled fixed-point fi

• Slope-bias scaled fixed-point fi

Although fi doubles and fi singles are allowed as inputs, they pass through the quantize function without being quantized.

Data Types: int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | fi
Complex Number Support: Yes

nt — numerictype object

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

numerictype object that describes a fixed-point data type.

rm — Rounding method to use

'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

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.

Data Types: char

s — Signedness

1 (default) | 0

Signedness of the quantized fixed-point number, specified as 1 (signed) or 0 (unsigned).

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

wl — Word length

16 (default) | positive scalar integer

Word length of the stored integer value of the output data, in bits.

fl — Fraction length

wl-1 (default) | scalar integer

Fraction length of the quantized value, specified as a scalar integer.

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

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced before R2006a

R2013a: quantize is not recommended

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

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 and encapsulate type information for quantization in an object rather than as separate input arguments.

Not Recommended	Recommended
x_BP = fi(pi); ntBP = numerictype(1,8,4); yBP = quantize(x_BP,ntBP) yBP = 3.1250 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 4	x_BP = fi(pi); ntBP = fi([],1,8,4); yBP = cast(x_BP,'like',ntBP) yBP = 3.1250 DataTypeMode: Fixed-point: binary point scaling Signedness: Signed WordLength: 8 FractionLength: 4