quantizenumeric

R2026b

Quantize numeric data

Syntax

y = quantizenumeric(x,s,w,f)

y = quantizenumeric(x,s,w,f,r)

y = quantizenumeric(x,s,w,f,r,o)

y = quantizenumeric(x,T)

y = quantizenumeric(x,T,F)

Description

y = quantizenumeric(x,s,w,f) quantizes the value specified in x using signedness s, word length w, and fraction length f.

Tip

Use the quantizenumeric function when you want to simulate full-precision arithmetic with doubles and then add quantization at certain steps in your algorithm without casting to fixed-point types.

y = quantizenumeric(x,s,w,f,r) also specifies rounding mode r.

y = quantizenumeric(x,s,w,f,r,o) also specifies overflow mode o.

In R2026b: y = quantizenumeric(x,T) quantizes the value specified in x using the numerictype specified in T.

In R2026b: y = quantizenumeric(x,T,F) quantizes the value specified in x using numerictype T and the fimath specified in F.

Examples

Quantize Value of pi with Different Rounding Modes

Quantize the value of pi using a signed numeric type with a word length of 16 bits, a fraction length of 13 bits, and rounding towards positive infinity.

x = pi;
y = quantizenumeric(x,1,16,13,'ceil')

y =

    3.1416

Specify a different rounding method. Observe that rounding towards zero affects the quantized value.

x = pi;
y = quantizenumeric(x,1,16,13,'fix')

y =

    3.1415

Quantize Numeric Data

This example shows the effect of overflow action on the quantization of numeric data.

Create some data and quantize it with saturation on overflow specified.

x = linspace(-5,5,100);
y = quantizenumeric(x,1,6,4,'floor','saturate');
plot(x,x,x,y)

Change the overflow action to wrap on overflow and observe how the quantized data changes.

z = quantizenumeric(x,1,6,4,'floor','wrap');
plot(x,x,x,z);

Quantize Data Using numerictype and fimath Objects

Since R2026b

This example shows how to use the numerictype and fimath objects to specify how data is quantized.

x = 1.6;
T = numerictype(1,16,0);
F = fimath(RoundingMethod='floor',OverflowAction='saturate');
y = quantizenumeric(x,T,F)

y =

     1

Input Arguments

x — Value to quantize

scalar | vector | matrix | multidimensional array

Value to quantize, specified as a scalar, vector, matrix, or multidimensional array.

Data Types: double
Complex Number Support: Yes

s — Signedness

0 or 'false' | 1 or 'true'

Signedness of quantized value, specified as either 0 or 'false' (unsigned) or 1 or 'true' (signed).

Data Types: double

w — Word length

positive scalar integer

Word length of quantized value, specified as a positive scalar integer.

Data Types: double

f — Fraction length

scalar integer

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

Data Types: double

r — Rounding method

'nearest' (default) | 'ceil' | 'ceiling' | 'convergent' | 'fix' | 'floor' | 'round' | 'zero'

Rounding method to use for quantization, specified as a character vector:

• 'ceil' — Round towards positive infinity (same as 'ceiling')

• 'ceiling' — Round towards positive infinity (same as 'ceil')

• 'convergent'— Convergent rounding

• 'fix'— Round towards zero (same as 'zero')

• 'floor'— Round towards negative infinity

• 'nearest'— Round towards nearest with ties rounding towards positive infinity

• 'round'— Round towards nearest with ties rounding up in absolute value

• 'zero'— Round towards zero (same as 'fix')

Data Types: char

o — Overflow action

'saturate' (default) | 'wrap'

Overflow action to use for quantization, specified as either 'saturate' or 'wrap'.

Data Types: char

T — Numeric type

numerictype object

Since R2026b

Numeric type of quantized value, specified as a numerictype object.

Example: T = numerictype(1,16,0);

F — Fixed-point math settings

fimath object

Since R2026b

Fixed-point math settings, specified as a fimath object.

Example: F = fimath(RoundingMethod='floor',OverflowAction='saturate');

Output Arguments

y — Quantized output value

scalar | vector | matrix | multidimensional array

Quantized output value, returned as a scalar, vector, matrix, or multidimensional array. y always has the same dimensions as x and is always a double.

Tips

• Use quantizenumeric when you want to simulate full-precision arithmetic with doubles and then add quantization at certain steps in your algorithm without casting to fixed-point types.

• When designing fixed-point algorithms, use cast, zeros, ones, eye, and subsasgn to separate the core algorithm from data type definitions.

Extended Capabilities

C/C++ Code Generation

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

The word length must be an integer in the range 1 ≤ w ≤ 65535. The fraction length must be an integer in the range -65535 ≤ f ≤ 65535.

Version History

Introduced in R2016a

R2026b: quantizenumeric supports numerictype and fimath inputs

The quantizenumeric function now supports numerictype and fimath objects as inputs to specify how data is quantized.

R2024b: quantizenumeric supports C/C++ code generation

The quantizenumeric function now supports C/C++ code generation.

R2021b: Change in default behavior of quantizenumeric for complex input

In previous releases, quantizenumeric would remove the imaginary part of a complex input x. For example,

x = complex(pi, exp(1))
y = quantizenumeric(x,1,16,12,'floor')

x =

   3.1416 + 2.7183i


y =

    3.1414

quantizenumeric now preserves the imaginary part, in the same way as other quantize functions behave for complex inputs. For example,

x = complex(pi, exp(1))
y = quantizenumeric(x,1,16,12,'floor')

x =

   3.1416 + 2.7183i


y =

   3.1414 + 2.7183i