Welcome to QformatPy documentation!

Introduction

Welcome to the qformat Python library, a powerful tool for formatting floating-point numbers into fixed-point representation with Q notation.

This library supports ARM’s Q format, where QI includes the sign bit.

The main function, qformat, allows users to specify the number of integer bits (QI), fractional bits (QF), whether the number is signed or unsigned, and provides flexibility in choosing rounding and overflow handling methods.

Whether you’re working on embedded systems, signal processing, or any application requiring fixed-point representation, qformat is here to streamline the process.

The example below shows pi being converter to the sQ4.8 format, using Truncation as the rounding method:

>>> from qformatpy import qformat

>>> x = 3.141592653589793
>>> result = qformat(x, qi=4, qf=8, rnd_method='Trunc')
>>> result
array([3.140625])

Installation

The qformatpy library is available via PIP install:

python3 -m venv pyenv
source pyenv/bin/activate

pip install qformatpy

Import the package as shown below:

import qformatpy

The following functions should be available:

A brief description of the functions can be seen below:

overflow(iarray[, signed, w, overflow_action])

Handle overflow in an integer array based on the specified overflow action.

rounding(iarray[, rnd_method])

Rounds each element in the input array according to the specified rounding method.

qformat(x, qi, qf[, signed, rnd_method, ...])

Format a given numeric value 'x' into fixed-point representation with Q format.

Example usage

>>> import numpy as np
>>> import qformatpy

>>> test_array = np.array([1.4, 5.57, 3.14])
>>> qformatpy.rounding(test_array, 'TowardsZero')
array([1, 5, 3])

>>> qformatpy.rounding(test_array, 'HalfDown')
array([1, 6, 3])

# Tests showing overflow and wrap
>>> test_array = np.array([4, 5.6778, 356.123])
>>> qformatpy.qformat(test_array, qi=5, qf=3)
array([4.   , 5.625, 4.   ])

>>> qformatpy.qformat(test_array, qi=9, qf=3)
array([   4.   ,    5.625, -156.   ])

# The input does not need to be an array
>>> qformatpy.qformat(np.pi, qi=3, qf=4)
3.125

Rounding methods

The library support the rounding methods listed below

Directed rounding to an integer: the displacements from the original number x to the rounded value y are all directed toward or away from the same limiting value (0, +inf, or -inf)

  • ‘Trunc’: Round towards -inf.

  • ‘Ceiling’: Round towards +inf.

  • ‘TowardsZero’: Round towards zero.

  • ‘AwayFromZero’: Round away from zero.

Round to the nearest: Rounding a number x to the nearest integer requires some tie-breaking rule for those cases when x is exactly half-way between two integers — that is, when the fraction part of x is exactly 0.5.

  • ‘HalfUp’: Round half up.

  • ‘HalfDown’: Round half down.

  • ‘HalfTowardsZero’: Round half towards zero.

  • ‘HalfAwayFromZero’: Round half away from zero.

For more information about the rounding methods above, refer to: Rounding

Speed Comparison

The test compares the time needed to convert 2^20 samples to the sQ6.8, using HalfAwayFromZero rounding method, and wrap overflow method.

Results:

  • QformatPy: 4.6 ms ± 51.8 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

  • FxpMath: 6.2 ms ± 21.3 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

  • Numfi: 33.7 ms ± 125 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)

  • Matlab: Elapsed time is 0.037031 seconds.

Using Truncation as rounding method (round towards -inf) and saturate for overlflow:

  • QformatPy: 2.19 ms ± 44.5 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)

  • FxpMath: 522 ms ± 4.84 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

  • Numfi: 23.5 ms ± 113 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)

  • Matlab: Elapsed time is 0.026836 seconds.

Example code used for the comparison:

Matlab code:

n_samples = 2^20;
test_data = randn(n_samples, 1)*10;

% save test data to use it in python tests
save('test_data.txt', 'test_data', '-ascii');

F = fimath('OverflowAction','Wrap', 'RoundingMethod','Round');
% Round: round towards nearest. Ties round toward negative infinity for
% negative numbers, and toward positive infinity for positive numbers.

qi = 6;
qf = 8;
w = qi + qf;

tic;
fxp_data = fi(test_data, 1, w, qf, F);
toc;

Elapsed time is 0.037031 seconds.

import numpy as np
from qformatpy import qformat
from fxpmath import Fxp
import numfi

x = np.loadtxt('examples/test_data.txt')

# Used by numfi and fxpmath
s = 1
qi = 6
qf = 8
w = qi + qf
# Qformat (used by QformatPy)

# Fixed point initialization
init_qfmt = %timeit -o qfmt_x = qformat(x, qi=qi, qf=qf, rnd_method='HalfAwayFromZero')
init_fxp = %timeit -o fxpmath_x = Fxp(x, s, w, qf, rounding='around', overflow='wrap')
init_numfi = %timeit -o numfi_x = numfi(x, s, w, qf, RoudingMethod='Round', OverflowAction='Wrap')

init_qfmt = %timeit -o qfmt_x = qformat(x, qi=qi, qf=qf, rnd_method='Trunc', overflow_action="Saturate")
init_fxp = %timeit -o fxpmath_x = Fxp(x, s, w, qf, rounding='trunc', overflow='saturate')
init_numfi = %timeit -o numfi_x = numfi(x, s, w, qf, RoudingMethod='Floor', OverflowAction='Saturate')