Array functions¶

Array creation functions¶

Create an array of shape with all zeros.

Word lengths need to be specified and the return type is deduced from the bit specifiers. Either specify exactly two of three from int_bits, frac_bits, and bits, for APyFixedArray, or specify both exp_bits and man_bits for APyFloatArray. Specify force_complex to retrieve a complex-valued array type.

Parameters:

shapetuple of int: Shape of the array.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.
force_complexbool, optional: Retrieve the complex-valued array type, APyCFixedArray for fixed-point and APyCFloatArray for floating-point.

Returns:

resultAPyFloatArray or APyFixedArray or APyCFixedArray: The initialized array with zeros.

Create an array of shape with all ones (stored value).

Parameters:

shapetuple of int: Shape of the array.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.
force_complexbool, optional: Retrieve the complex-valued array type, APyCFixedArray for fixed-point and APyCFloatArray for floating-point.

Returns:

resultAPyFloatArray or APyFixedArray or APyCFixedArray: The array initialized filled with ones.

Return a 2-D array with ones (stored value) on the main diagonal and zeros elsewhere.

Parameters:

nint: Number of rows in the output.
mint, optional: Number of columns in the output. If None, defaults to n.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.
force_complexbool, optional: Retrieve the complex-valued array type, APyCFixedArray for fixed-point and APyCFloatArray for floating-point.

Returns:

resultAPyFloatArray or APyFixedArray or APyCFixedArray: An array where all elements are equal to zero, except for the k-th diagonal, whose values are equal to one.

Return the identity array.

Parameters:

nint: Number of rows and columns in output.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.
force_complexbool, optional: Retrieve the complex-valued array type, APyCFixedArray for fixed-point and APyCFloatArray for floating-point.

Returns:

resultAPyFloatArray or APyFixedArray or APyCFixedArray: n x n array with ones (stored value) on the main diagonal and zeros elsewhere.

Return a new array of given shape and type, filled with fill_value.

If fill_value is of type int or float, you must specify the word lengths. Either specify exactly two of three from int_bits, frac_bits, and bits, for APyFixedArray, or specify both exp_bits and man_bits for APyFloatArray. If fill_value is of type APyFloat or APyFixed, the array will use the provided word lengths only if specified, otherwise the word lengths are inherited from fill_value.

Parameters:

shapetuple: Shape of the array.
fill_valueAPyFloat or APyFixed or int or :class`float`: Fill value.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

resultAPyFloatArray or APyFixedArray: Array of all fill_value with the given shape.

Return an array of all zeros with the same shape and type as a.

The type and bit-specifiers of the returned array can be overwritten through the bit-specifier arguments. To overwrite the type, either specify exactly two of three from int_bits, frac_bits, and bits, for APyFixedArray, or specify both exp_bits and man_bits for APyFloatArray.

Parameters:

aAPyFloatArray or APyFixedArray: The shape and data-type define these same attributes of the returned array.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

resultAPyFloatArray or APyFixedArray: The initialized array with all zeros.

apytypes.ones_like(a: APyFixedArray) → APyFixedArray¶

apytypes.ones_like(a: APyCFixedArray) → APyCFixedArray

apytypes.ones_like(a: APyFloatArray) → APyFloatArray

Return an array of all ones (stored value) with the same shape and type as a.

Parameters:

aAPyFloatArray or APyFixedArray: The shape and data-type of a define these same attributes of the returned array.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

resultAPyFloatArray or APyFixedArray: The array initialized filled with all ones.

Return an array with all values initialized to fill_value, with the same shape and type as a.

Parameters:

aAPyFloatArray or APyFixedArray: The shape and array type of the returned array.
fill_valueAPyFloat or APyFixed or int or float: The value to fill the array with.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

resultAPyFloatArray or APyFixedArray: Array filled with fill_value, having the same shape and type as a.

Create an array with evenly spaced values within a given interval.

The function can be called with varying number of positional arguments:

arange(stop): Values are generated within the half-open interval [0, stop) (in other words, the interval including start but excluding stop).
arange(start, stop): Values are generated within the half-open interval [start, stop).
arange(start, stop, step): Values are generated within the half-open interval [start, stop), with spacing between values given by step.

If no bit-specifiers are given, the array type is deduced based on start, stop, and step. In this case, all APyTypes scalars must be of the same format.

Parameters:

startint, float, APyFloat, APyFixed: Start number.
stopint, float, APyFloat, APyFixed, optional: Stop number.
stepint, float, APyFloat, APyFixed, optional: Step size in range.
int_bitsint, optional: Number of fixed-point integer bits.
frac_bitsint, optional: Number of fixed-point fractional bits.
bitsint, optional: Number of fixed-point bits.
exp_bitsint, optional: Number of floating-point exponential bits.
man_bitsint, optional: Number of floating-point mantissa bits.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.

Returns:

resultAPyFloatArray or APyFixedArray: Array with evenly spaced values within a given interval.

Array modification functions¶

Expand the shape of an array.

Insert a new axis that will appear at the axis position in the expanded array shape.

Parameters:

aAPyFloatArray, APyFixedArray, or APyCFixedArray: The array whose axes should be reordered.
axisint or tuple of ints: Position in the expanded axes where the new axis (or axes) is placed.

Returns:

resultAPyFloatArray or APyFixedArray: copy of a with the number of dimensions increased.

Examples

>>> import apytypes as apy
>>> x = apy.APyFixedArray.from_float([1, 2], int_bits=5, frac_bits=0)
>>> x.shape
(2,)

>>> y = apy.expand_dims(x, axis=0)
>>> y.to_numpy()
array([[1., 2.]])
>>> y.shape
(1, 2)

>>> y = apy.expand_dims(x, axis=1)
>>> y.to_numpy()
array([[1.],
       [2.]])
>>> y.shape
(2, 1)

axis may also be a tuple:

>>> y = apy.expand_dims(x, axis=(0, 1))
>>> y.to_numpy()
array([[[1., 2.]]])

>>> y = apy.expand_dims(x, axis=(2, 0))
>>> y.to_numpy()
array([[[1.],
        [2.]]])

apytypes.ravel(a: APyFixedArray | APyCFixedArray | APyFloatArray) → APyFixedArray | APyCFixedArray | APyFloatArray¶

Return a copy of the array collapsed into one dimension.

Same as flatten() with current memory-copy model.

Returns:

collapsedAPyFloatArray or APyFixedArray: copy of a but collapsed

Examples

>>> from apytypes import APyFloatArray
>>> signs = [[0, 0], [1, 1]]
>>> exps = [[127, 128], [128, 129]]
>>> mans = [[0, 0], [4194304, 0]]
>>> arr = APyFloatArray(signs=signs, exps=exps, mans=mans, exp_bits=8, man_bits=23)
>>> arr.to_numpy()
array([[ 1.,  2.],
       [-3., -4.]])

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

apytypes.moveaxis(a: APyFixedArray | APyCFixedArray | APyFloatArray, source, destination) → APyFixedArray | APyCFixedArray | APyFloatArray¶

Move axes of an array to new positions.

Other axes remain in their original order.

Parameters:

aAPyFloatArray or APyFixedArray: The array whose axes should be reordered.
sourceint or sequence of int: Original positions of the axes to move. These must be unique.
destinationint or sequence of int: Destination positions for each of the original axes. These must also be unique.

Returns:

resultAPyFloatArray or APyFixedArray: Copy of array with moved axes.

Examples

import apytypes as apy

>>> x = apy.APyFixedArray.from_float([0] * 60, int_bits=2**16, frac_bits=0).reshape(
...     (3, 4, 5)
... )
>>> apy.moveaxis(x, 0, -1).shape
(4, 5, 3)
>>> apy.moveaxis(x, -1, 0).shape
(5, 3, 4)

These all achieve the same result:

>>> apy.transpose(x).shape
(5, 4, 3)
>>> apy.swapaxes(x, 0, -1).shape
(5, 4, 3)
>>> apy.moveaxis(x, [0, 1], [-1, -2]).shape
(5, 4, 3)
>>> apy.moveaxis(x, [0, 1, 2], [-1, -2, -3]).shape
(5, 4, 3)

Remove axes of length one from a.

Parameters:

aAPyFloatArray, APyFixedArray, or APyCFixedArray: Input data.
axisint or tuple of ints, optional: Selects a subset of the entries of length one in the shape.

Returns:

squeezedAPyFloatArray, APyFixedArray, or APyCFixedArray: The input array, but with all or a subset of the dimensions of length 1 removed.

Raises:

ValueError: If axis is not None, and an axis being squeezed is not of length 1

apytypes.swapaxes(a: APyFixedArray | APyCFixedArray | APyFloatArray, axis1: int, axis2: int) → APyFixedArray | APyCFixedArray | APyFloatArray¶

Interchange two axes of an array.

Parameters:

aAPyFloatArray or APyFixedArray: The array whose axes should be reordered.
axis1int: First axis.
axis2int: Second axis.

Returns:

a_swapped APyFloatArray or APyFixedArray: Copy of a with axes swapped

Examples

>>> from apytypes import APyFloatArray
>>> x = APyFloatArray.from_float([[1, 2, 3]], exp_bits=5, man_bits=2)
>>> x.swapaxes(0, 1).to_numpy()
array([[1.],
       [2.],
       [3.]])

>>> x = APyFloatArray.from_float(
...     [[[0, 1], [2, 3]], [[4, 5], [6, 7]]], exp_bits=5, man_bits=3
... )
>>> 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.]]])

Array utility functions¶

Return the discrete linear convolution of two one-dimensional arrays.

Parameters:

aAPyFloatArray or APyFixedArray

First one-dimensional array of length M

vAPyFloatArray or APyFixedArray

Second one-dimensional array of length N.

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 or APyFixedArray: The convolved array.

apytypes.shape(arr: APyFixedArray | APyCFixedArray | APyFloatArray) → tuple[int, ...]¶

Return the shape of an array.

Parameters:

arrAPyFloatArray or APyFixedArray: Input data.

Returns:

tuple of int: Shape of the input array.

Raises:

TypeError: If the input does not have a shape attribute.