aimath_q31.h File Reference

Definition of the Q31 (aiq31) data-type. More...

Go to the source code of this file.

Data Structures
struct	aimath_q31_params
	Parameters used for the quantized Q31 values, used as property of a tensor. More...
struct	aiscalar_q31
	Single quantized Q31 value/scalar. More...

Typedefs
typedef struct aimath_q31_params	aimath_q31_params_t
typedef struct aiscalar_q31	aiscalar_q31_t

Functions
void	aimath_q31_print_aitensor (const aitensor_t *tensor)
	Printing a Q31 tensor to console. More...
void	aimath_q31_print_aiscalar (const void *scalar)
	Printing a Q31 scalar to console. More...
void	aimath_q31_calc_q_params_from_f32 (float min_value, float max_value, aimath_q31_params_t *q_params)
	Calculates the aimath_q31_params parameters. More...
void	aimath_q31_quantize_tensor_from_f32 (const aitensor_t *tensor_f32, aitensor_t *tensor_q31)
	Converts a float f32 tensor into a quantized q31 tensor. More...

Variables
const aimath_dtype_t *	aiq31
	The Q31 data-type indicator. More...

Detailed Description

Definition of the Q31 (aiq31) data-type.

Version

2.2.0

Copyright

Copyright (C) 2020-2023 Fraunhofer Institute for Microelectronic Circuits and Systems. All rights reserved.

AIfES is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

The Q31 (aiq31) data-type stores data as quantized 32 bit integer values. In addition a scaling factor (shift) and a zero point (zero_point) is needed to fully define the value.

The Q31 quantization is a asymmetric 32 bit integer quantization that allows integer-only calculations on real values. A real value \( r \) is represented by an integer value \( q \), the scaling factor / shift \( s \) and the zero point \( z \) according to the following formula:

\[ r = 2^{-s} * (q - z) \]

To get the quantized value \( q \) out of a real value you have to calculate

\[ q = round(\frac{x}{2^{-s}} + z) \]

Example: Create a Q31 tensor
The tensor

\[ \left( \begin{array}{rrr} 0 & 1 & 2 \\ 3 & 4 & 5 \end{array}\right) \]

can be created with In C:

int32_t example_data[] = {0, 1, 2
                          3, 4, 5};
uint16_t example_shape[] = {2, 3};
aimath_q31_params_t example_q_params = { .shift = 0, .zero_point = 0 };
aitensor_t example_tensor = {
    .dtype = aiq31,
    .dim = 2,
    .shape = example_shape,
    .tensor_params = example_q_params,
    .data = example_data
};

In C, C++ and on Arduino:

int32_t example_data[] = {0, 1, 2
                          3, 4, 5};
uint16_t example_shape[] = {2, 3};
aimath_q31_params_t example_q_params = { .shift = 0, .zero_point = 0 };
aitensor_t example_tensor = AITENSOR_2D_Q31(example_shape, &example_q_params, example_data);

Example: Create a Q31 scalar
Either create it with the helper macro

aiscalar_q31_t scalar = AISCALAR_Q31(42.0f, 16, 0);

or manual with

aiscalar_q31_t scalar = { .value = 2552512, .shift = 16, .zero_point = 0};

Example: Print a Q31 tensor to the console

print_aitensor(&example_tensor);

Example: Print a Q31 scalar to the console

print_aiscalar(&scalar, aiq31);

Function Documentation

aimath_q31_calc_q_params_from_f32()

void aimath_q31_calc_q_params_from_f32	(	float	min_value,
		float	max_value,
		aimath_q31_params_t *	q_params
	)

Calculates the aimath_q31_params parameters.

Given a minimum and a maximum value, this function calculates the scaling shift and zero shift parameters for aimath_q31_params

Parameters

min_value	Minimum value of a given range
max_value	Maximum value of a given range
*q_params	Pointer to write the results aimath_q31_params::zero_point and aimath_q31_params::shift into

aimath_q31_print_aiscalar()

void aimath_q31_print_aiscalar

(

const void *

scalar

)

Printing a Q31 scalar to console.

For users the function

print_aiscalar(&scalar, aiq31);

is prefered.

Parameters

*scalar

The scalar (type: aiscalar_q31_t) to print.

aimath_q31_print_aitensor()

void aimath_q31_print_aitensor

(

const aitensor_t *

tensor

)

Printing a Q31 tensor to console.

For users the function

print_aitensor(&tensor);

is prefered.

Parameters

*tensor

The tensor to print.

aimath_q31_quantize_tensor_from_f32()

void aimath_q31_quantize_tensor_from_f32	(	const aitensor_t *	tensor_f32,
		aitensor_t *	tensor_q31
	)

Converts a float f32 tensor into a quantized q31 tensor.

Converts a float f32 tensor into a quantized q31 tensor by applying the aimath_q31_params_t given in the quantized q31 tensor

Parameters

*tensor_f32	Float f32 tensor to convert from
*tensor_q31	quantized q31 tensor to convert to, included aimath_q31_params must be set beforehand

Variable Documentation

aiq31

const aimath_dtype_t* aiq31

extern

The Q31 data-type indicator.

Use this variable to configure some element with the Q31 data-type,