`APyFixedArray`¶

class apytypes.APyFixedArray¶

Attributes:

T: The transposition of the array.
bits: Total number of bits.
frac_bits: Number of fractional bits.
int_bits: Number of integer bits.
ndim: Number of dimensions in the array.
shape: The shape of the array.

Methods

`broadcast_to`	Broadcast array to new shape.
`cast`	Change format of the fixed-point array.
`convolve`	Return the discrete linear convolution with another one-dimensional array.
`cumprod`	Return the cumulative product of the elements along a given axes.
`cumsum`	Return the cumulative sum of the elements along a given axes.
`eye`
`flatten`	Return a copy of the array collapsed into one dimension.
`from_array`
`from_float`
`full`
`identity`
`is_identical`	Test if two `APyFixedArray` objects are identical.
`max`	Return the maximum value from an array or the maximum values along an axis.
`min`	Return the minimum value from an array or the minimum values along an axis.
`nancumprod`	Return the cumulative product of the elements along a given axis treating NaN as 0.
`nancumsum`	Return the cumulative sum of the elements along a given axis treating NaN as 0.
`nanmax`	Return the maximum value from an array or the maximum values along an axis, ignoring NaN.
`nanmin`	Return the minimum value from an array or the minimum values along an axis, ignoring NaN.
`nanprod`	Return the product of the elements along a given axis treating NaN as 0.
`nansum`	Return the sum of the elements along specified axis/axes treating NaN as 0.
`ones`
`prod`	Return the product of the elements along specified axis/axes.
`ravel`	Return a copy of the array collapsed into one dimension.
`reshape`	Reshape the APyFixedArray to the specified shape without changing its data.
`squeeze`	Removes axes of size one at the specified axis/axes, if no axis is given removes all dimensions with size one.
`sum`	Return the sum of the elements along specified axis/axes.
`swapaxes`	Interchange two axes of an array.
`to_bits`	Return the underlying bit representations.
`to_numpy`	Return array as a `numpy.ndarray` of `numpy.float64`.
`transpose`	Return copy of array with axes transposed.
`zeros`

Constructor¶

__init__(self, bit_pattern_sequence: Sequence, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → None¶

Conversion to other types¶

to_numpy(self) → numpy.ndarray[dtype=float64]¶

Return array as a numpy.ndarray of numpy.float64.

The returned array has the same shape and values as self. This method rounds away from infinity on ties.

Returns:

numpy.ndarray

to_bits(self, numpy: bool = False) → list | numpy.ndarray[dtype=uint64] | numpy.ndarray[dtype=uint32] | numpy.ndarray[dtype=uint16] | numpy.ndarray[dtype=uint8]¶

Return the underlying bit representations.

When numpy is true, the bit representations are returned in a numpy.ndarray. Otherwise, they are returned in a list.

Returns:

list or numpy.ndarray

Creation from other types¶

from_array(ndarray: ndarray[order='C'], int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Create an APyFixedArray object from an ndarray.

The input is quantized using QuantizationMode.RND_INF and overflow is handled using the OverflowMode.WRAP mode. Exactly two of the three bit-specifiers (bits, int_bits, frac_bits) must be set.

Using NumPy arrays as input is in general faster than e.g. lists.

Parameters:

ndarrayndarray: Values to initialize from. The tensor shape will be taken from the ndarray shape.
int_bitsint, optional: Number of integer bits in the created fixed-point tensor.
frac_bitsint, optional: Number of fractional bits in the created fixed-point tensor.
bitsint, optional: Total number of bits in the created fixed-point tensor.

Returns:

APyFixedArray

Examples

>>> from apytypes import APyFixedArray
>>> import numpy as np
>>>
>>> a = APyFixedArray.from_array(
...     np.array([
...         [1.0, 2.0, 3.0],
...         [4.0, 5.0, 6.0],
...     ]),
...     int_bits=10,
...     frac_bits=0
... )

from_float(number_seq: Sequence, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Create an APyFixedArray object from a sequence of int, float, APyFixed, or APyFloat.

The input is quantized using QuantizationMode.RND_INF and overflow is handled using the OverflowMode.WRAP mode. Exactly two of the three bit-specifiers (bits, int_bits, frac_bits) must be set.

Using NumPy arrays as input is in general faster than e.g. lists.

Parameters:

number_seqsequence of numbers: Values to initialize from. The tensor shape will be taken from the sequence shape.
int_bitsint, optional: Number of integer bits in the created fixed-point tensor.
frac_bitsint, optional: Number of fractional bits in the created fixed-point tensor.
bitsint, optional: Total number of bits in the created fixed-point tensor.

Returns:

APyFixedArray

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray.from_float([1.0, 1.25, 1.49], int_bits=2, frac_bits=2)
>>> b = APyFixedArray.from_float(
...     [
...         [1.0, 2.0, 3.0],
...         [4.0, 5.0, 6.0],
...     ],
...     bits=5,
...     frac_bits=0
... )

Other creation functions¶

zeros(shape: tuple, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Initializes an array with zeros.

Parameters:

shapetuple: Shape of the array.
int_bitsint, optional: Number of integer bits.
frac_bitsint, optional: Number of fractional bits.
bitsint, optional: Total number of bits.

Returns:

APyFixedArray: An array initialized with zeros.

ones(shape: tuple, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Initializes an array with ones.

Parameters:

shapetuple: Shape of the array.
int_bitsint, optional: Number of integer bits.
frac_bitsint, optional: Number of fractional bits.
bitsint, optional: Total number of bits.

Returns:

APyFixedArray: An array initialized with ones.

eye(n: int, m: int | None = None, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Initializes an array with ones on the diagonal.

Parameters:

nint: Number of rows.
mint, optional: Number of columns.
int_bitsint, optional: Number of integer bits.
frac_bitsint, optional: Number of fractional bits.
bitsint, optional: Total number of bits.

Returns:

APyFixedArray: An array with ones on the diagonal.

identity(n: int, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixedArray¶

Initializes an identity matrix with ones on the diagonal.

Parameters:

nint: Number of rows (and columns) in n x n output.
int_bitsint, optional: Number of integer bits.
frac_bitsint, optional: Number of fractional bits.
bitsint, optional: Total number of bits.

Returns:

APyFixedArray: An identity matrix with ones on the diagonal.

full(shape: tuple, fill_value: APyFixed) → APyFixedArray¶

Initializes an array with the specified value.

Parameters:

shapetuple: Shape of the array.
fill_valueAPyFixed: Value to fill the array.

Returns:

APyFixedArray: An array filled with the specified value.

Change word length¶

Change format of the fixed-point array.

This is the primary method for performing quantization and overflowing/saturation when dealing with APyTypes fixed-point arrays.

Exactly two of three bit-specifiers (bits, int_bits, frac_bits) must be set.

Parameters:

int_bitsint, optional: Number of integer bits in the result.
frac_bitsint, optional: Number of fractional bits in the result.
quantizationQuantizationMode, optional: Quantization mode to use in this cast.
overflowOverflowMode, optional: Overflowing mode to use in this cast.
bitsint, optional: Total number of bits in the result.

Returns:

APyFixedArray

Comparison¶

is_identical(self, other: APyFixedArray) → bool¶

Test if two APyFixedArray objects are identical.

Two APyFixedArray objects are considered identical if, and only if:

They represent exactly the same tensor shape
They store the exact same fixed-point values in all tensor elements
They have the exact same bit specification (bits, int_bits, and frac_bits are all equal)

Returns:

bool

Convolution¶

convolve(self, other: APyFixedArray, mode: str = 'full') → APyFixedArray¶

Return the discrete linear convolution with another one-dimensional array.

Requires that ndim = 1 for both self and other.

Parameters:

otherAPyFixedArray

The one-dimensional array of length N to convolve with.

mode{‘full’, ‘same’, ‘valid’}, default: ‘full’

‘full’:: Return the full convolution for each point of overlap. The resulting single-dimensional shape will have length N + M - 1. Boundary effects occurs for points where the a and v do not overlap completely.
‘same’:: Return a convolution of length max(M, N). Boundary effects still occur around the edges of the result.
‘valid’:: Return the convolution for each point of full overlap. The resulting single-dimensional shape will have length max(M, N) - min(M, N) + 1

Returns:

convolvedAPyFixedArray: The convolved array.

Transposition¶

transpose(self, axes: tuple | None = None) → APyFixedArray¶

Return copy of array with axes transposed.

For a 1-D array, this return the same array. For a 2-D array, this is the standard matrix transpose. For an n-D array, if axes are given, their order indicates how the axes are permuted (see Examples). If axes are not provided, then a.transpose(a).shape == a.shape[::-1].

Parameters:

axestuple of int, optional: If specified, it must be a tuple or list which contains a permutation of [0,1,…,N-1] where N is the number of axes of a. The i’th axis of the returned array will correspond to the axis numbered axes[i] of the input. If not specified, defaults to range(a.ndim)[::-1], which reverses the order of the axes.

Returns:

APyFixedArray: a with its axes permuted.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray.from_float(
...         [[ 1.0,  2.0,  3.0],
...          [-4.0, -5.0, -6.0]],
...         bits=5,
...         frac_bits=0
...     )
>>> a.transpose().to_numpy()
array([[ 1., -4.],
       [ 2., -5.],
       [ 3., -6.]])

>>> a = APyFixedArray.from_float(
...         [1.0] * 6,
...         bits=5,
...         frac_bits=0
...     ).reshape((1, 2, 3))
>>> a.transpose((1, 0, 2)).shape
(2, 1, 3)

>>> a.transpose((-2, -3, -1)).shape
(2, 1, 3)

Array shape manipulation¶

flatten(self) → APyFixedArray¶

Return a copy of the array collapsed into one dimension.

Returns:

APyFixedArray

Examples

>>> from apytypes import APyFixedArray
>>>
>>> arr = APyFixedArray([[2, 3], [4, 5]], int_bits=2, frac_bits=1)
>>> arr.to_numpy()
array([[ 1. ,  1.5],
       [-2. , -1.5]])

>>> arr.flatten().to_numpy()
array([ 1. ,  1.5, -2. , -1.5])

ravel(self) → APyFixedArray¶

Return a copy of the array collapsed into one dimension. Same as flatten with current memory-copy model.

Returns:

APyFixedArray

Examples

>>> from apytypes import APyFixedArray
>>>
>>> arr = APyFixedArray([[2, 3], [4, 5]], int_bits=2, frac_bits=1)
>>> arr.to_numpy()
array([[ 1. ,  1.5],
       [-2. , -1.5]])

>>> arr.ravel().to_numpy()
array([ 1. ,  1.5, -2. , -1.5])

reshape(self, number_sequence: tuple) → APyFixedArray¶

Reshape the APyFixedArray to the specified shape without changing its data.

Parameters:

new_shapetuple: The new shape should be compatible with the original shape. If a dimension is -1, its value will be inferred from the length of the array and remaining dimensions. Only one dimension can be -1.

Returns:

APyFixedArray

Raises:

ValueError: If negative dimensions less than -1 are provided, if the total size of the new array is not unchanged and divisible by the known dimensions, or if the total number of elements does not match the original array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray([2, 3, 4, 5], int_bits=2, frac_bits=1)
>>> a.to_numpy()
array([ 1. ,  1.5, -2. , -1.5])
>>> a.reshape((2, 2)).to_numpy()
array([[ 1. ,  1.5],
       [-2. , -1.5]])
>>> a.reshape((4,)).to_numpy()
array([ 1. ,  1.5, -2. , -1.5])
>>> a.reshape((2, -1)).to_numpy()
array([[ 1. ,  1.5],
       [-2. , -1.5]])

squeeze(self, axis: int | tuple | None = None) → APyFixedArray¶

Removes axes of size one at the specified axis/axes, if no axis is given removes all dimensions with size one.

Parameters:

axistuple of int or int, optional: The axes to squeeze, a given axis with a size other than one will result in an error. No given axes will be remove all dimensions of size one.

Returns:

APyFixedArray

Raises:

ValueError: If given an axis of a size other than one a ValueError will be thrown.
IndexError: If a specified axis is outside of the existing number of dimensions for the array.

swapaxes(self, axis1: int, axis2: int) → APyFixedArray¶

Interchange two axes of an array.

Parameters:

axis1int: First axis.
axis2int: Second axis.

Returns:

a_swappedAPyFixedArray: Copy of a with axes swapped

Examples

>>> from apytypes import APyFixedArray
>>>
>>> x = APyFixedArray.from_float([[1, 2, 3]], bits=5, frac_bits=0)
>>> x.swapaxes(0,1).to_numpy()
array([[1.],
       [2.],
       [3.]])
>>> x = APyFixedArray.from_float(
...     [[[0, 1], [2, 3]], [[4, 5], [6, 7]]],
...     bits=5,
...     frac_bits=0
... )
>>> x.to_numpy()
array([[[0., 1.],
        [2., 3.]],

       [[4., 5.],
        [6., 7.]]])
>>> x.swapaxes(0,2).to_numpy()
array([[[0., 4.],
        [2., 6.]],

       [[1., 5.],
        [3., 7.]]])

Mathematical functions¶

sum(self, axis: tuple | int | None = None) → APyFixedArray | APyFixed¶

Return the sum of the elements along specified axis/axes.

Parameters:

axistuple of int or int, optional: The axis/axes to summate across. Will summate the whole array if no int or tuple is specified.

Returns:

APyFixedArray or APyFixed

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [1, 2, 3, 4, 5, 6],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.sum()
APyFixed(21, bits=13, int_bits=13)

prod(self, axis: tuple | int | None = None) → APyFixedArray | APyFixed¶

Return the product of the elements along specified axis/axes.

Parameters:

axistuple, int, optional: The axis/axes to calculate the product across. If not given an axis it will return the product of the flattened array.

Returns:

APyFixedArray or APyFixed

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [1,2,3,4,5,6],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.prod()
APyFixed(720, bits=60, int_bits=60)

cumsum(self, axis: int | None = None) → APyFixedArray¶

Return the cumulative sum of the elements along a given axes.

Parameters:

axisint, optional: The axes to summate across. If not given an axis it will return the cumulative sum of the flattened array.

Returns:

APyFixedArray

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [[1,2,3],[4,5,6]],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.cumsum()
APyFixedArray([1, 3, 6, 10, 15, 21], shape=(6,), bits=13, int_bits=13)
>>> a.cumsum(0)
APyFixedArray([1, 2, 3, 5, 7, 9], shape=(2, 3), bits=11, int_bits=11)
>>> a.cumsum(1)
APyFixedArray([1, 3, 6, 4, 9, 15], shape=(2, 3), bits=12, int_bits=12)

cumprod(self, axis: int | None = None) → APyFixedArray¶

Return the cumulative product of the elements along a given axes.

Parameters:

axisint, optional: The axes to calculate the product across. If not given an axis it will return the cumulative product of the flattened array.

Returns:

APyFixedArray

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [[1,2,3],[4,5,6]],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.cumprod()
APyFixedArray([1, 2, 6, 24, 120, 720], shape=(6,), bits=60, int_bits=60)
>>> a.cumprod(0)
APyFixedArray([1, 2, 3, 4, 10, 18], shape=(2, 3), bits=20, int_bits=20)
>>> a.cumprod(1)
APyFixedArray([1, 2, 6, 4, 20, 120], shape=(2, 3), bits=30, int_bits=30)

max(self, axis: tuple | int | None = None) → APyFixedArray | APyFixed¶

Return the maximum value from an array or the maximum values along an axis.

Parameters:

axistuple of int or int, optional: The axis to get the maximum along.

Returns:

APyFixedArray or APyFixed

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [[1,2,3],[4,5,6]],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.max()
APyFixed(6, bits=10, int_bits=10)
>>> a.max(0)
APyFixedArray([4, 5, 6], shape=(3,), bits=10, int_bits=10)
>>> a.max(1)
APyFixedArray([3, 6], shape=(2,), bits=10, int_bits=10)

min(self, axis: tuple | int | None = None) → APyFixedArray | APyFixed¶

Return the minimum value from an array or the minimum values along an axis.

Parameters:

axistuple of int or int, optional: The axis to get the minimum along.

Returns:

APyFixedArray or APyFixed

Raises:

IndexError: If a specified axis is outside of the existing number of dimensions for the array.

Examples

>>> from apytypes import APyFixedArray
>>>
>>> a = APyFixedArray(
...     [[1,2,3],
...      [4,5,6]],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.min()
APyFixed(1, bits=10, int_bits=10)
>>> a.min(0)
APyFixedArray([1, 2, 3], shape=(3,), bits=10, int_bits=10)
>>> a.min(1)
APyFixedArray([1, 4], shape=(2,), bits=10, int_bits=10)