`APyFloatArray`¶

class apytypes.APyFloatArray(*args, **kwargs)¶

Class for multidimensional arrays with configurable floating-point formats.

APyFloatArray is a class for multidimensional arrays with configurable floating-point formats. The interface is much like the one of NumPy, and direct plotting is supported by most functions in Matplotlib. APyFloatArray should always be preferred, if possible, when working with arrays as it allows for better performance, and integration with other features of APyTypes.

For information about the workings of floating-point numbers, see its scalar equivalent APyFloat.

Attributes:

T: The transposition of the array.
bias: Exponent bias.
bits: Total number of bits.
exp_bits: Number of exponent bits.
man_bits: Number of mantissa 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 floating-point number.
`cast_to_bfloat16`	Cast to bfloat16 format.
`cast_to_double`	Cast to IEEE 754 binary64 (double-precision) format.
`cast_to_half`	Cast to IEEE 754 binary16 (half-precision) format.
`cast_to_single`	Cast to IEEE 754 binary32 (single-precision) format.
`convolve`	Return the discrete linear convolution with another one-dimensional array.
`copy`	Create a copy of the object.
`cumprod`	Return cumulative product of elements along a given axes.
`cumsum`	Return the cumulative sum of the elements along a given axis.
`eye`
`flatten`	Return a copy of the array collapsed into one dimension.
`from_array`
`from_bits`
`from_float`
`full`
`identity`
`is_identical`	Test if two `APyFloatArray` objects are identical.
`max`	Return maximum value of array or along an axis.
`min`	Return maximum value of array or along an axis.
`nancumprod`	Return cumulative product of elements along a given axis treating NaN as 0.
`nancumsum`	Return cumulative sum of elements along a given axis treating NaN as 0.
`nanmax`	Return maximum value of array or along an axis ignoring NaN.
`nanmin`	Return minimum value of array or along an axis ignoring NaN.
`nanprod`	Return 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 product of elements along specified axis/axes.
`ravel`	Return a copy of the array collapsed into one dimension.
`reshape`	Reshape the APyFloatArray to the specified shape without changing its data.
`squeeze`	Remove axes of size one at the specified axis/axes.
`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, signs: Sequence, exps: Sequence, mans: Sequence, exp_bits: int, man_bits: int, bias: int | None = None) → None¶

Create an APyFloatArray object.

Parameters:

signssequence of bools or ints: The sign of the float. False/0 means positive. True/non-zero means negative.
expssequence of ints: Exponents of the floats as stored, i.e., actual value + bias.
manssequence of ints: Mantissas of the floats as stored, i.e., without a hidden one.
exp_bitsint: Number of exponent bits.
man_bitsint: Number of mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

APyFloatArray

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'], exp_bits: int, man_bits: int, bias: int | None = None) → APyFloatArray¶

Create an APyFloatArray from an ndarray.

Parameters:

ndarrayndarray: Values to initialize from. The tensor shape will be taken from the ndarray shape.
exp_bitsint: Number of exponent bits in the created floating-point tensor
man_bitsint: Number of mantissa bits in the created floating-point tensor
biasint, optional: Bias in the created floating-point tensor

Returns:

APyFloatArray

Other creation functions¶

copy(self) → APyFloatArray¶: Create a copy of the object.

Added in version 0.3.

eye(n: int, exp_bits: int, man_bits: int, m: int | None = None, bias: int | None = None) → APyFloatArray¶

Initialize an array with ones on the diagonal.

Parameters:

nint: Number of rows (and columns) in the n x n output.
exp_bitsint: Number of exponent bits.
man_bitsint: Number of mantissa bits.
mint, optional: Number of columns. Default is None, which results in an n x n output.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

APyFloatArray: An array with the specified value on the diagonal.

full(shape: int | tuple[int, ...], fill_value: APyFloat) → APyFloatArray¶

Initialize an array filled with the specified value.

Parameters:

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

Returns:

APyFloatArray: An array filled with the specified value.

identity(n: int, exp_bits: int, man_bits: int, bias: int | None = None) → APyFloatArray¶

Initialize an identity matrix with ones on the diagonal.

Parameters:

nint: Number of rows (and columns) in the n x n output.
exp_bitsint: Number of exponent bits.
man_bitsint: Number of mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

APyFloatArray: An identity matrix with ones on the diagonal.

ones(shape: int | tuple[int, ...], exp_bits: int, man_bits: int, bias: int | None = None) → APyFloatArray¶

Initialize an array with ones.

Parameters:

shapetuple: Shape of the array.
exp_bitsint: Number of exponent bits.
man_bitsint: Number of mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

APyFloatArray: An array filled with ones.

zeros(shape: int | tuple[int, ...], exp_bits: int, man_bits: int, bias: int | None = None) → APyFloatArray¶

Initialize an array with zeros.

Parameters:

shapetuple: Shape of the array.
exp_bitsint: Number of exponent bits.
man_bitsint: Number of mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

APyFloatArray: An array filled with zeros.

Change word length¶

cast(self, exp_bits: int | None = None, man_bits: int | None = None, bias: int | None = None, quantization: QuantizationMode | None = None) → APyFloatArray¶

Change format of the floating-point number.

This is the primary method for performing quantization when dealing with APyTypes floating-point numbers.

Parameters:

exp_bitsint, optional: Number of exponent bits in the result.
man_bitsint, optional: Number of mantissa bits in the result.
biasint, optional: Bias used in the result.
quantizationQuantizationMode, optional.: Quantization mode to use in this cast. If None, use the global quantization mode.

Returns:

APyFloat

Comparison¶

is_identical(self, other: APyFloatArray | APyFloat) → bool¶

Test if two APyFloatArray objects are identical.

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

They represent exactly the same tensor shape
They store the exact same floating-ppint values in all tensor elements
They have the exact same bit format (exp_bits, man_bits, and bias)

Returns:

bool

Convolution¶

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

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

Requires that ndim = 1 for both self and other.

Parameters:

otherAPyFloatArray

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:

convolvedAPyFloatArray: The convolved array.

Transposition¶

transpose(self, axes: tuple[int, ...] | None = None) → APyFloatArray¶

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:

APyFloatArray: a with its axes permuted.

Examples

>>> import apytypes as apy
>>> a = apy.fp([[1, 2, 3], [-4, -5, -6]], exp_bits=5, man_bits=2)
>>> print(a)
[[ 1,  2,  3],
 [-4, -5, -6]]
>>> print(a.transpose())
[[ 1, -4],
 [ 2, -5],
 [ 3, -6]]

>>> b = apy.fp([1.0] * 6, exp_bits=5, man_bits=2).reshape((1, 2, 3))
>>> b.shape
(1, 2, 3)
>>> b.transpose((1, 0, 2)).shape
(2, 1, 3)
>>> b.transpose((-2, -3, -1)).shape
(2, 1, 3)

Array shape manipulation¶

flatten(self) → APyFloatArray¶

Return a copy of the array collapsed into one dimension.

Returns:

APyFloatArray

Examples

>>> import apytypes as apy
>>> arr = apy.fp([[ 1,  2],
...               [-3, -4]], exp_bits=8, man_bits=23)
>>> print(arr)
[[ 1,  2],
 [-3, -4]]
>>> print(arr.flatten())
[ 1,  2, -3, -4]

ravel(self) → APyFloatArray¶

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

Returns:

APyFloatArray

Examples

>>> import apytypes as apy
>>> arr = apy.fp([[ 1,  2],
...               [-3, -4]], exp_bits=8, man_bits=23)
>>> print(arr)
[[ 1,  2],
 [-3, -4]]
>>> print(arr.ravel())
[ 1,  2, -3, -4]

reshape(self, new_shape: int | tuple[int, ...]) → APyFloatArray¶

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

Parameters:

new_shapetuple of int: 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:

APyFloatArray

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

>>> import apytypes as apy
>>> arr = apy.fp([1, 2, -3, -4], exp_bits=8, man_bits=23)
>>> print(arr)
[ 1,  2, -3, -4]
>>> print(arr.reshape((2, 2)))
[[ 1,  2],
 [-3, -4]]
>>> print(arr.reshape((4, 1)))
[[ 1],
 [ 2],
 [-3],
 [-4]]

squeeze(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray¶

Remove axes of size one at the specified axis/axes.

If no axis is given, remove all dimensions with size one.

Parameters:

axistuple of int or int, optional: The axis/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 1.

Returns:

APyFloatArray

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) → APyFloatArray¶

Interchange two axes of an array.

Parameters:

axis1int: First axis.
axis2int: Second axis.

Returns:

a_swappedAPyFloatArray: Copy of a with axes swapped

Examples

>>> import apytypes as apy
>>> a = apy.fp([[1 ,2, 3]], exp_bits=5, man_bits=2)
>>> print(a)
[[1, 2, 3]]
>>> print(a.swapaxes(0,1))
[[1],
 [2],
 [3]]

>>> b = apy.fp([[[0, 1], [2, 3]], [[4, 5], [6, 7]]], exp_bits=5, man_bits=5)
>>> print(b)
[[[0, 1],
  [2, 3]],

 [[4, 5],
  [6, 7]]]
>>> print(b.swapaxes(0,2))
[[[0, 4],
  [2, 6]],

 [[1, 5],
  [3, 7]]]

Mathematical functions¶

sum(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

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:

APyFloatArray or APyFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [1, 2, 3, 4, 5, 6],
...     exp_bits=10,
...     man_bits=10
... )
>>> a
APyFloatArray(
    [  0,   0,   0,   0,   0,   0],
    [511, 512, 512, 513, 513, 513],
    [  0,   0, 512,   0, 256, 512],
    exp_bits=10,
    man_bits=10
)
>>> a.sum()
APyFloat(sign=0, exp=515, man=320, exp_bits=10, man_bits=10)
>>> print(a)
[1, 2, 3, 4, 5, 6]
>>> print(a.sum())
21

prod(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return product of 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:

APyFloatArray or APyFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [1, 2, 3, 4, 5, 6],
...     exp_bits=10,
...     man_bits=10
... )
>>> a
APyFloatArray(
    [  0,   0,   0,   0,   0,   0],
    [511, 512, 512, 513, 513, 513],
    [  0,   0, 512,   0, 256, 512],
    exp_bits=10,
    man_bits=10
)
>>> a.prod()
APyFloat(sign=0, exp=520, man=416, exp_bits=10, man_bits=10)
>>> print(a)
[1, 2, 3, 4, 5, 6]
>>> print(a.prod())
720

nansum(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return the sum of the elements along specified axis/axes treating NaN as 0.

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:

APyFloatArray or APyFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> nan = float("nan")
>>> a = apy.fp(
...     [1, 2, 3, 4, 5, nan],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[  1,   2,   3,   4,   5, nan]
>>> print(a.sum())
nan
>>> print(a.nansum())
15

nanprod(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return product of the elements along a given axis treating NaN as 0.

Parameters:

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

Returns:

APyFloatArray or APyFloat

Raises:

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

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

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

Parameters:

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

Returns:

APyFloatArray

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [[1, 2, 3], [4, 5, 6]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[1, 2, 3],
 [4, 5, 6]]
>>> print(a.cumsum())
[ 1,  3,  6, 10, 15, 21]
>>> print(a.cumsum(0))
[[1, 2, 3],
 [5, 7, 9]]
>>> print(a.cumsum(1))
[[ 1,  3,  6],
 [ 4,  9, 15]]

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

Return cumulative product of 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:

APyFloatArray

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [[1, 2, 3], [4, 5, 6]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[1, 2, 3],
 [4, 5, 6]]
>>> print(a.cumprod())
[  1,   2,   6,  24, 120, 720]
>>> print(a.cumprod(0))
[[ 1,  2,  3],
 [ 4, 10, 18]]
>>> print(a.cumprod(1))
[[  1,   2,   6],
 [  4,  20, 120]]

nancumsum(self, axis: int | None = None) → APyFloatArray¶

Return cumulative sum of elements along a given axis treating NaN as 0.

Parameters:

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

Returns:

APyFloatArray

Raises:

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

Examples

>>> import apytypes as apy
>>> nan = float("nan")
>>> a = apy.fp(
...     [[1, 2, 3], [4, 5, nan]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[  1,   2,   3],
 [  4,   5, nan]]
>>> print(a.cumsum())
[  1,   3,   6,  10,  15, nan]
>>> print(a.nancumsum())
[ 1,  3,  6, 10, 15, 15]

>>> print(a.cumsum(0))
[[  1,   2,   3],
 [  5,   7, nan]]
>>> print(a.nancumsum(0))
[[1, 2, 3],
 [5, 7, 3]]

>>> print(a.cumsum(1))
[[  1,   3,   6],
 [  4,   9, nan]]
>>> print(a.nancumsum(1))
[[1, 3, 6],
 [4, 9, 9]]

nancumprod(self, axis: int | None = None) → APyFloatArray¶

Return cumulative product of elements along a given axis treating NaN as 0.

Parameters:

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

Returns:

APyFloatArray

Raises:

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

max(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return maximum value of array or along an axis.

Parameters:

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

Returns:

APyFloatArray or APyFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [[1, 2, 3], [4, 5, 6]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[1, 2, 3],
 [4, 5, 6]]
>>> print(a.max())
6
>>> print(a.max(0))
[4, 5, 6]
>>> print(a.max(1))
[3, 6]

min(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return maximum value of array or along an axis.

Parameters:

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

Returns:

APyFloatArray or APyFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.fp(
...     [[1, 2, 3], [4, 5, 6]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[1, 2, 3],
 [4, 5, 6]]

>>> print(a.min())
1

>>> print(a.min(0))
[1, 2, 3]

>>> print(a.min(1))
[1, 4]

nanmax(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return maximum value of array or along an axis ignoring NaN.

Issues a warning when encountering an all-nan slice or axis.

Parameters:

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

Returns:

APyFloatArray or APyFloat

Raises:

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

nanmin(self, axis: int | tuple[int, ...] | None = None) → APyFloatArray | APyFloat¶

Return minimum value of array or along an axis ignoring NaN.

Issues a warning when encountering an all-nan slice or axis.

Parameters:

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

Returns:

APyFloatArray or APyFloat

Raises:

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

Broadcasting¶

broadcast_to(self, shape: int | tuple[int, ...]) → APyFloatArray¶

Broadcast array to new shape.

Added in version 0.2.

Parameters:

shapetuple of int or int: The shape to broadcast to. A single integer i is interpreted as (i,).

Returns:

APyFloatArray

Convenience casting methods¶

cast_to_bfloat16(self, quantization: QuantizationMode | None = None) → APyFloatArray¶

Cast to bfloat16 format.

Convenience method corresponding to

f.cast(exp_bits=8, man_bits=7)

Parameters:

quantizationQuantizationMode, optional: Quantization mode to use. If not provided, the global mode, see get_float_quantization_mode(), is used.

cast_to_double(self, quantization: QuantizationMode | None = None) → APyFloatArray¶

Cast to IEEE 754 binary64 (double-precision) format.

Convenience method corresponding to

f.cast(exp_bits=11, man_bits=52)

Parameters:

quantizationQuantizationMode, optional: Quantization mode to use. If not provided, the global mode, see get_float_quantization_mode(), is used.

cast_to_half(self, quantization: QuantizationMode | None = None) → APyFloatArray¶

Cast to IEEE 754 binary16 (half-precision) format.

Convenience method corresponding to

f.cast(exp_bits=5, man_bits=10)

Parameters:

quantizationQuantizationMode, optional: Quantization mode to use. If not provided, the global mode, see get_float_quantization_mode(), is used.

cast_to_single(self, quantization: QuantizationMode | None = None) → APyFloatArray¶

Cast to IEEE 754 binary32 (single-precision) format.

Convenience method corresponding to

f.cast(exp_bits=8, man_bits=23)

Parameters:

quantizationQuantizationMode, optional: Quantization mode to use. If not provided, the global mode, see get_float_quantization_mode(), is used.