`APyCFloatArray`¶

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

Class for configurable complex-valued array floating-point formats.

Added in version 0.4.

Note

For real-valued floating-point formats, see APyFloat and APyFloatArray.

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 array.
`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_complex`
`from_float`
`full`
`identity`
`is_identical`	Test if two `APyCFloatArray` objects are identical.
`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.
`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 APyCFloatArray 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_numpy`	Return array as a `numpy.ndarray` of `numpy.complex128`.
`transpose`	Return copy of array with axes transposed.
`zeros`

Constructor¶

__init__(self, sign_seq: Iterable[Any], exp_seq: Iterable[Any], man_seq: Iterable[Any], exp_bits: int, man_bits: int, bias: int | None = None) → None¶

Conversion to other types¶

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

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

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

Returns:

numpy.ndarray

Creation from other types¶

from_array(ndarray: ndarray[order='C'], exp_bits: int, man_bits: int, bias: int | None = None) → APyCFloatArray¶

Create an APyCFloatArray 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:

APyCFloatArray

Other creation functions¶

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

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

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:

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

full(shape: int | tuple[int, ...], fill_value: APyCFloat) → APyCFloatArray¶

Initialize an array filled with the specified value.

Parameters:

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

Returns:

APyCFloatArray: An array filled with the specified value.

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

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:

APyCFloatArray: An identity matrix with ones on the diagonal.

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

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:

APyCFloatArray: An array filled with ones.

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

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:

APyCFloatArray: 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) → APyCFloatArray¶

Change format of the floating-point array.

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

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:

APyCFloatArray

Comparison¶

is_identical(self, other: object, ignore_zero_sign: bool = False) → bool¶

Test if two APyCFloatArray objects are identical.

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

They represent exactly the same tensor shape

They store the exact same floating-point values in all elements

They have the exact same bit format (exp_bits, man_bits, and bias)

Parameters:

otherAPyCFloatArray: The floating-point object to test identicality against.
ignore_zero_signbool, default: False: If True, plus and minus zero are considered identical. If False, plus and minus zero are considered different.

Returns:

bool

Convolution¶

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

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

Requires that ndim = 1 for both self and other.

Parameters:

otherAPyCFloatArray

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:

convolvedAPyCFloatArray: The convolved array.

Transposition¶

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

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:

APyCFloatArray: a with its axes permuted.

Examples

>>> import apytypes as apy
>>> a = apy.APyCFloatArray.from_float(
...         [[ 1.0,  2.0,  3.0],
...          [-4.0, -5.0, -6.0]],
...         exp_bits=5,
...         man_bits=5
...     )
>>> print(a)
[[ 1+0j,  2+0j,  3+0j],
 [-4+0j, -5+0j, -6+0j]]
>>> print(a.transpose())
[[ 1+0j, -4+0j],
 [ 2+0j, -5+0j],
 [ 3+0j, -6+0j]]

>>> b = apy.APyCFloatArray.from_float(
...         [1.0] * 6,
...         exp_bits=5,
...         man_bits=5
...     ).reshape((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) → APyCFloatArray¶

Return a copy of the array collapsed into one dimension.

Returns:

APyCFloatArray

Examples

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

ravel(self) → APyCFloatArray¶

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

Returns:

APyCFloatArray

Examples

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

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

Reshape the APyCFloatArray 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:

APyCFloatArray

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.APyCFloatArray.from_float(
...     [1, 2, -3, -4], exp_bits=8, man_bits=23
... )
>>> print(arr)
[ 1+0j,  2+0j, -3+0j, -4+0j]
>>> print(arr.reshape((2, 2)))
[[ 1+0j,  2+0j],
 [-3+0j, -4+0j]]
>>> print(arr.reshape((4, 1)))
[[ 1+0j],
 [ 2+0j],
 [-3+0j],
 [-4+0j]]

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

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 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:

APyCFloatArray

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

Interchange two axes of an array.

Parameters:

axis1int: First axis.
axis2int: Second axis.

Returns:

a_swappedAPyCFloatArray: Copy of a with axes swapped

Examples

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

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

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

 [[1+0j, 5+0j],
  [3+0j, 7+0j]]]

Mathematical functions¶

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

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:

APyCFloatArray or APyCFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.APyCFloatArray.from_float(
...     [1, 2, 3, 4, 5, 6],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[1+0j, 2+0j, 3+0j, 4+0j, 5+0j, 6+0j]
>>> print(a.sum())
(21+0j)

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

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:

APyCFloatArray or APyCFloat

Raises:

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

Examples

>>> import apytypes as apy
>>> a = apy.APyCFloatArray.from_float(
...     [1, 2, 3, 4, 5, 6], exp_bits=10, man_bits=10
... )
>>> print(a)
[1+0j, 2+0j, 3+0j, 4+0j, 5+0j, 6+0j]
>>> print(a.prod())
(720+0j)

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

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:

APyCFloatArray or APyCFloat

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.APyCFloatArray.from_float(
...     [1, 2, 3, 4, 5, nan],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[  1+0j,   2+0j,   3+0j,   4+0j,   5+0j, nan+0j]
>>> print(a.sum())
(nan+0j)
>>> print(a.nansum())
(15+0j)

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

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:

APyCFloatArray or APyCFloat

Raises:

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

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

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:

APyCFloatArray

Raises:

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

Examples

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

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

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:

APyCFloatArray

Raises:

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

Examples

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

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

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:

APyCFloatArray

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.APyCFloatArray.from_float(
...     [[  1,   2,   3],
...      [  4,   nan, 6]],
...     exp_bits=10,
...     man_bits=10
... )
>>> print(a)
[[  1+0j,   2+0j,   3+0j],
 [  4+0j, nan+0j,   6+0j]]
>>> print(a.cumsum())
[  1+0j,   3+0j,   6+0j,  10+0j, nan+0j, nan+0j]
>>> print(a.nancumsum())
[ 1+0j,  3+0j,  6+0j, 10+0j, 10+0j, 16+0j]

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

>>> print(a.cumsum(1))
[[  1+0j,   3+0j,   6+0j],
 [  4+0j, nan+0j, nan+0j]]
>>> print(a.nancumsum(1))
[[ 1+0j,  3+0j,  6+0j],
 [ 4+0j,  4+0j, 10+0j]]