Main Content

quantize

Quantize fixed-point numbers

collapse all in page

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

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.

example

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

example

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

example

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.

example

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.

example

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.

example

Examples

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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

collapse all

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

numerictype object that describes a fixed-point data type.

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

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

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

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

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

expand all

See Also

| | |