`APyCFixedArray`¶

class apytypes.APyCFixedArray¶

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

Added in version 0.3.

Attributes:

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

Methods

`broadcast_to`	Broadcast array to new shape.
`cast`	Change format of the fixed-point 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_complex`
`from_float`
`full`
`identity`
`is_identical`	Test if two `APyCFixedArray` objects are identical.
`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.
`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`	Returns the product of the elements along specified axis/axes.
`ravel`	Return a copy of the array collapsed into one dimension.
`reshape`	Reshape the APyCFixedArray 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_numpy`	Return array as a `numpy.ndarray` of `numpy.complex128`.
`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=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'], int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyCFixedArray¶

Create an APyCFixedArray object from an ndarray.

The initialized fixed-point values are the one closest to the input floating-point value, rounded away from zero on ties. 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:

APyCFixedArray

Examples

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

from_complex(complex_sequence: Sequence, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyCFixedArray¶

Create an APyCFixedArray object from a sequence of int, float, complex, APyFixed, APyFloat, or APyCFixed.

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:

complex_sequencesequence of float, int, or complex: 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:

APyCFixedArray

Examples

>>> from apytypes import APyCFixedArray
>>>
>>> a = APyCFixedArray.from_complex(
...         [1.0, 1.25j, 1.49 - 0.5j],
...         int_bits=2,
...         frac_bits=2
...     )
>>> b = APyCFixedArray.from_complex(
...         [
...             [1.0 + 1.0j, 2.0 - 3.0j, 3.0 - 1.0j],
...             [4.0 - 2.0j, 5.0 + 2.0j, 6.0 + 1j],
...         ],
...         bits=5,
...         frac_bits=0
...     )

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

Create an APyCFixedArray object from a sequence of int, float, complex, APyFixed, APyFloat, or APyCFixed. This is an alias for from_complex(), look there for more documentation.

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:

APyCFixedArray

Other creation functions¶

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

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:

APyCFixedArray: An array initialized with zeros.

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

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:

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

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:

APyCFixedArray: An array with ones on the diagonal.

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

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:

APyCFixedArray: An identity matrix with ones on the diagonal.

full(shape: tuple, fill_value: APyCFixed) → APyCFixedArray¶

Initializes an array with the specified value.

Parameters:

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

Returns:

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

APyCFixedArray

Comparison¶

is_identical(self, other: APyCFixedArray) → bool¶

Test if two APyCFixedArray objects are identical.

Two APyCFixedArray 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¶

Transposition¶

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

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:

APyCFixedArray: a with its axes permuted.

Examples

>>> from apytypes import APyCFixedArray
>>>
>>> a = APyCFixedArray.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.+0.j, -4.+0.j],
       [ 2.+0.j, -5.+0.j],
       [ 3.+0.j, -6.+0.j]])

>>> a = APyCFixedArray.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) → APyCFixedArray¶

Return a copy of the array collapsed into one dimension.

Returns:

APyCFixedArray

Examples

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

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

ravel(self) → APyCFixedArray¶

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

Returns:

APyCFixedArray

Examples

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

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

reshape(self, number_sequence: tuple) → APyCFixedArray¶

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

APyCFixedArray

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 APyCFixedArray
>>>
>>> a = APyCFixedArray([2, 3, 4, 5], int_bits=2, frac_bits=1)
>>> a.to_numpy()
array([ 1. +0.j,  1.5+0.j, -2. +0.j, -1.5+0.j])

>>> a.reshape((2, 2)).to_numpy()
array([[ 1. +0.j,  1.5+0.j],
       [-2. +0.j, -1.5+0.j]])

>>> a.reshape((4,)).to_numpy()
array([ 1. +0.j,  1.5+0.j, -2. +0.j, -1.5+0.j])

>>> a.reshape((2, -1)).to_numpy()
array([[ 1. +0.j,  1.5+0.j],
       [-2. +0.j, -1.5+0.j]])

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

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:

APyCFixedArray

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

Interchange two axes of an array.

Parameters:

axis1int: First axis.
axis2int: Second axis.

Returns:

a_swappedAPyCFixedArray: Copy of a with axes swapped

Examples

>>> from apytypes import APyCFixedArray
>>>
>>> x = APyCFixedArray.from_float([[1, 2, 3]], bits=5, frac_bits=0)
>>> x.swapaxes(0,1).to_numpy()
array([[1.+0.j],
       [2.+0.j],
       [3.+0.j]])

>>> x = APyCFixedArray.from_float(
...         [[[0, 1], [2, 3]], [[4, 5], [6, 7]]],
...         bits=5,
...         frac_bits=0
...     )
>>> x.to_numpy()
array([[[0.+0.j, 1.+0.j],
        [2.+0.j, 3.+0.j]],

       [[4.+0.j, 5.+0.j],
        [6.+0.j, 7.+0.j]]])

>>> x.swapaxes(0,2).to_numpy()
array([[[0.+0.j, 4.+0.j],
        [2.+0.j, 6.+0.j]],

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

Mathematical functions¶

sum(self, axis: tuple | int | None = None) → APyCFixedArray | APyCFixed¶

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:

APyCFixedArray or APyCFixed

Raises:

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

Examples

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

prod(self, axis: tuple | int | None = None) → APyCFixedArray | APyCFixed¶

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

APyCFixedArray or APyCFixed

Raises:

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

Examples

>>> from apytypes import APyCFixedArray
>>>
>>> a = APyCFixedArray.from_complex(
...     [1, 2 + 1j, 3 + 3j, -4 + 1j, 5 - 2j, 6 - 3j],
...     int_bits=10,
...     frac_bits=0
... )
>>> complex(a.prod())
(-1395-225j)

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

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:

APyCFixedArray

Raises:

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

Examples

>>> from apytypes import APyCFixedArray
>>> a = APyCFixedArray.from_complex(
...     [
...         [1+1j, 2+3j, 3-2j],
...         [4-1j, 5+2j, 6+0j]
...     ],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.cumsum().to_numpy()
array([ 1.+1.j,  3.+4.j,  6.+2.j, 10.+1.j, 15.+3.j, 21.+3.j])

>>> a.cumsum(0).to_numpy()
array([[1.+1.j, 2.+3.j, 3.-2.j],
       [5.+0.j, 7.+5.j, 9.-2.j]])

>>> a.cumsum(1).to_numpy()
array([[ 1.+1.j,  3.+4.j,  6.+2.j],
       [ 4.-1.j,  9.+1.j, 15.+1.j]])

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

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:

APyCFixedArray

Raises:

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

Examples

>>> from apytypes import APyCFixedArray
>>>
>>> a = APyCFixedArray.from_complex(
...     [[1+1j, 2+1j, 3+2j],
...      [4-2j, 5+2j, 6+1j]],
...     int_bits=10,
...     frac_bits=0
... )
>>> a.cumprod().to_numpy()
array([   1.+1.00e+00j,    1.+3.00e+00j,   -3.+1.10e+01j,   10.+5.00e+01j,
        -50.+2.70e+02j, -570.+1.57e+03j])

>>> a.cumprod(0).to_numpy()
array([[ 1. +1.j,  2. +1.j,  3. +2.j],
       [ 6. +2.j,  8. +9.j, 16.+15.j]])

>>> a.cumprod(1).to_numpy()
array([[  1. +1.j,   1. +3.j,  -3.+11.j],
       [  4. -2.j,  24. -2.j, 146.+12.j]])

Broadcasting¶

broadcast_to(self, shape: tuple | int) → APyCFixedArray¶

Broadcast array to new shape.

Parameters:

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

Returns:

APyCFixedArray

Properties¶

Real and imaginary part¶

property real¶

Real part.

Returns:

APyFixedArray

property imag¶

Imaginary part.

Returns:

APyFixedArray

Word length¶

property bits¶

Total number of bits.

Returns:

int

property int_bits¶

Number of integer bits.

Returns:

int

property frac_bits¶

Number of fractional bits.

Returns:

int

Array properties¶

property ndim¶

Number of dimensions in the array.

Returns:

int

property shape¶

The shape of the array.

Returns:

tuple of int

Transposition¶

property T¶

The transposition of the array.

Equivalent to calling APyCFixedArray.transpose().

Returns:

APyCFixedArray