utils

Operators Utilities API

The utils module provides utility functions for AOT operators.

Copyright 2025 Ambiq. All Rights Reserved.

Functions

pad_shape_to_4d

pad_shape_to_4d(shape: tuple[int, ...]) -> tuple[int, int, int, int]

Pad a tensor shape to 4D (N, H, W, C) order, filling missing dims with 1.

clamp_to_int_range

clamp_to_int_range(x: float, dtype: dtype = np.int8) -> int

Clamp a float to the specified integer type range.

Parameters:

• x

  (float) –

  The float to clip.

• dtype

  (dtype, default: int8 ) –

  The target integer type. Defaults to np.int8.

Returns:

• int ( int ) –

  The clipped integer value.

lut_populate_s16

lut_populate_s16(input_scale: float, input_zero_point: int, output_scale: float, output_zero_point: int, transform_fn) -> np.ndarray

Recreates TFLM's LUTPopulate behavior.

Args input_scale, input_zero_point: affine scale for LUT input domain output_scale, output_zero_point: affine scale for LUT output domain transform_fn: function f: R -> R (e.g., exp, 1/(1+x))

Returns np.int16 array of length 513.

calculate_input_radius

calculate_input_radius(input_integer_bits, input_left_shift, total_signed_bits=31) -> int

Mimics litert::CalculateInputRadius (non-emulated version).

This computes the maximum representable difference in the scaled domain.

Parameters:

• input_integer_bits

  (int) –

  Number of integer bits reserved (e.g., kScaledDiffIntegerBits, typically 5).

• input_left_shift

  (int) –

  The left shift computed from PreprocessSoftmaxScaling.

• total_signed_bits

  (int, default: 31 ) –

  Total bits available in the representation (typically 31 for Q31 arithmetic).

Returns:

• int ( int ) –

  The computed input radius.

tflite_round

tflite_round(x: float) -> int

TFLM's TfLiteRound: round half away from zero, implemented with +/-0.5 then trunc. Args: x (float): The float to round.

Returns:

• int ( int ) –

  The rounded integer.

checked_log2

checked_log2(x: float, tol: float = 0.001) -> tuple[bool, int]

Exact port of TFLM's CheckedLog2: - Uses log(x) / log(2) (not math.log2) - Rounds with TfLiteRound - 'Power-of-two' if |fracpart| < 1e-3

Parameters:

• x

  (float) –

  The positive float to compute log2 for.

• tol

  (float, default: 0.001 ) –

  The tolerance for determining if the value is a power of two.

Returns:

• tuple[bool, int] –

  tuple[bool, int]: A tuple where the first element indicates if x is a power of two, and the second element is the rounded log2 value.

downscale_q31_to_q15

downscale_q31_to_q15(q31: int) -> int

Downscale a Q31 integer to Q15.

Parameters:

• q31

  (int) –

  The Q31 integer to downscale.

Returns:

• int ( int ) –

  The downscaled Q15 integer.

vector_sum_s8

vector_sum_s8(vector_data: ndarray, vector_cols: int, vector_rows: int, lhs_offset: int, rhs_offset: int, bias_data: ndarray | None = None) -> np.ndarray

Pure-Python port of CMSIS-NN's arm_vector_sum_s8 helper.

Parameters:

• vector_data

  (ndarray) –

  Flattened (rows * cols) int8 buffer containing the kernel matrix.

• vector_cols

  (int) –

  Number of columns per output channel (accumulation depth).

• vector_rows

  (int) –

  Number of rows/output channels.

• lhs_offset

  (int) –

  Input offset applied during accumulation.

• rhs_offset

  (int) –

  Filter/weight offset applied during accumulation.

• bias_data

  (ndarray | None, default: None ) –

  Optional per-output bias (length == vector_rows), int32.

Returns:

• ndarray –

  np.ndarray: int32 array with the kernel sums, matching CMSIS-NN behaviour.