Quantize

The Quantize class is used to quantize a float-point/integer number or NumPy array.

Note

Quantize does not aim to change the data type of the input, i.e., the output is still a float-point/integer number/array.

class rtlsim.Quantize(S, W, F, overflow: str = 'wrap', rounding: str = 'truncate')

Fixed-point quantization scheme.

Parameters:

• S (boolean) – Sign bit (True for signed, False for unsigned)

• W (positive integer) – Word bit width

• F (integer) – Fractional bit width

• overflow (str, optional) – Overflow behavior, defaults to 'wrap'

• rounding (str, optional) – Rounding behavior, defaults to 'truncate'

asBits(x)

Get the string bits representation of the quantized fixed-point number (from float-point).

Parameters:

x (Float or numpy.ndarray) – Fixed-point number

Returns:

String bits representation of the fixed-point number

Return type:

String or numpy.ndarray of strings

Here are some examples.

>>> a = np.array([1.23, -1.2, 34.1, 0, 3.26, 1, -2.34])
>>> print(rtlsim.Quantize(False, 6, 2).asBits(a))
['000100' '111011' '001000' '000000' '001101' '000100' '110110']
>>> print(rtlsim.Quantize(False, 6, 2).asBits(3.14))
001100

asBitsInt(x)

Get the integer representation of the quantized fixed-point number (from float-point).

This considers the Overflow behavior and the Rounding behavior.

Parameters:

x (Float or numpy.ndarray) – Fixed-point number

Returns:

Scaled integer value of the fixed-point number

Return type:

Integer-valued float or numpy.ndarray

asBitsUInt(x)

Get the unsigned integer representation of the quantized fixed-point number (from float-point).

This considers the Overflow behavior and the Rounding behavior.

Parameters:

x (Float or numpy.ndarray) – Fixed-point number

Returns:

Scaled unsigned integer value of the fixed-point number

Return type:

Unsigned integer-valued float or numpy.ndarray

info(verbose: bool = False)

Get the information of the quantization scheme.

Parameters:

verbose (boolean, optional) – Whether to print the information, defaults to False

Returns:

Information of the quantization scheme

Return type:

String

In the following example, we create a Quantize object and print its information. The verbose option is set to True to print more information about the fixed-point property.

>>> Q_u_6_2 = rtlsim.Quantize(False, 6, 2)
>>> print(Q_u_6_2.info())
Quantization scheme (rtlsim.Quantize):
  Sign bit:              False
  Word bit width:        6
  Fractional bit width:  2
  Overflow behavior:     wrap (0)
  Rounding behavior:     truncate (0)
>>> print(Q_u_6_2.info(verbose=True))
Quantization scheme (rtlsim.Quantize):
  Sign bit:              False
  Word bit width:        6
  Fractional bit width:  2
  Overflow behavior:     wrap (0)
  Rounding behavior:     truncate (0)
  Minimum value:         0.0
  Maximum value:         15.75
  Range:                 15.75
  Precision:             0.25
  Minimum integer value: 0
  Maximum integer value: 63
  Range of integer:      63

q(x)

Alias for quantize()

qs(x)

Alias for quantizeSelf()

quantize(x)

Quantize the fixed-point number (from float-point).

This considers the Overflow behavior and the Rounding behavior.

Parameters:

x (Float or numpy.ndarray) – Fixed-point number

Returns:

Quantized fixed-point number

Return type:

Float or numpy.ndarray

Here are some use examples.

>>> Q_u_6_2 = rtlsim.Quantize(False, 6, 2)
>>> Q_u_6_2.quantize(a) # or Q_u_6_2.q(a)
>>> a = np.array([1.23, -1.2, 34.1, 0, 3.26, 1, -2.34])
>>> Q_u_6_2.quantize(a) # or Q_u_6_2.q(a)
array([ 1.  , 14.75,  2.  ,  0.  ,  3.25,  1.  , 13.5 ])
>>> rtlsim.quantize(a, False, 6, 2, overflow='saturate')
array([ 1.  ,  0.  , 15.75,  0.  ,  3.25,  1.  ,  0.  ])
>>> Q_u_6_2.q(np.random.rand(2, 3))
array([[0.75, 0.25, 0.25],
       [0.  , 0.75, 0.  ]])
>>> Q_u_6_2.q(3.1415926)
3.0

quantizeSelf(x)

Quantize the fixed-point number (from float-point) in-place.

Parameters:

x (numpy.ndarray) – numpy.ndarray of fixed-point numbers

Raises:

TypeError – If x is not a numpy.ndarray

This considers the Overflow behavior and the Rounding behavior.

Caution

The input x must be a numpy.ndarray.

Here are some use examples and error showcase.

>>> Q_u_6_2 = rtlsim.Quantize(False, 6, 2)
3.0
>>> a = np.array([1.23, -1.2, 34.1, 0, 3.26, 1, -2.34])
>>> Q_u_6_2.quantizeSelf(a)
>>> a
array([ 1.  , 14.75,  2.  ,  0.  ,  3.25,  1.  , 13.5 ])
>>> Q_u_6_2.qs(3.1415926)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/Users/tvj/Documents/Code/Python/rtlsim/rtlsim/Quantize.py", line 166, in quantizeSelf
    raise TypeError('Input must be a numpy.ndarray.')
TypeError: Input must be a numpy.ndarray.

Some standalone functions are defined for simpler use.

rtlsim.quantize(x, S, W, F, overflow: str = 'wrap', rounding: str = 'truncate')

Quantize the fixed-point number (from float-point).

This function internally creates a Quantize object and calls quantize().

Parameters:

• x (Float or numpy.ndarray) – Fixed-point number

• S (boolean) – Sign bit (True for signed, False for unsigned)

• W (positive integer) – Word bit width

• F (integer) – Fractional bit width

• overflow (str, optional) – Overflow behavior, defaults to 'wrap'

• rounding (str, optional) – Rounding behavior, defaults to 'truncate'

Returns:

Quantized fixed-point number

Return type:

Float or numpy.ndarray

Here are some examples.

>>> rtlsim.quantize(3.1415926, True, 3, -1)
2.0
>>> rtlsim.quantize(np.array([1.23, -1.2, 34.1, 0, 3.26, 1, -2.34]), True, 3, -1)
array([ 0.,  0.,  2.,  0.,  2.,  0., -2.])

rtlsim.quantizeSelf(x, S, W, F, overflow: str = 'wrap', rounding: str = 'truncate')

Quantize the fixed-point number (from float-point) in-place.

This function internally creates a Quantize object and calls quantizeSelf().

Parameters:

• x (numpy.ndarray) – numpy.ndarray of fixed-point numbers

• S (boolean) – Sign bit (True for signed, False for unsigned)

• W (positive integer) – Word bit width

• F (integer) – Fractional bit width

• overflow (str, optional) – Overflow behavior, defaults to 'wrap'

• rounding (str, optional) – Rounding behavior, defaults to 'truncate'

Raises:

TypeError – If x is not a numpy.ndarray

Caution

The input x must be a numpy.ndarray.

Here is an example.

>>> a = np.array([1.23, -1.2, 34.1, 0, 3.26, 1, -2.34])
>>> rtlsim.quantizeSelf(a, True, 6, 2, rounding='around')
>>> a
array([ 1.25, -1.  ,  2.  ,  0.  ,  3.25,  1.  , -2.  ])