`APyCFixed`¶

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

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

Added in version 0.3.

APyCFixed is an arbitrary precision complex-valued two’s complement fixed-point scalar type. In many ways it behaves like the built-in Python type complex in that it can be used within ordinary arithmetic expressions that allows complex numbers. Every fixed-point instance has an associated word length, determined by its bits, int_bits, and frac_bits bit specifiers. These specifiers determine the location of the binary fix-point and the total word length. Both the real and imaginary part share bit specifiers, and the total number of bits in an APyCFixed is 2 * bits. Only two of three bit specifiers need to be set to uniquely determine the complete fixed-point format.

Note

For complex-valued fixed-point arrays, see APyCFixedArray. For real-valued fixed-point formats, see APyFixed and APyFixedArray.

Word-length of fixed-point arithmetic operations using `APyCFixed`¶
Operation	Result `int_bits`	Result `frac_bits`
`a + b`	`max(a.int_bits, b.int_bits) + 1`	`max(a.frac_bits, b.frac_bits)`
`a - b`	`max(a.int_bits, b.int_bits) + 1`	`max(a.frac_bits, b.frac_bits)`
`a * b`	`a.int_bits + b.int_bits + 1`	`a.frac_bits + b.frac_bits`
`a / b`	`a.int_bits + b.frac_bits + 1`	`a.frac_bits + b.int_bits`
`-a`	`a.int_bits + 1`	`a.frac_bits`

Attributes:

bits: Total number of bits.
frac_bits: Number of fractional bits.
imag: Imaginary part.
int_bits: Number of integer bits.
is_zero: True if the value equals zero, false otherwise.
leading_ones: Number of leading ones.
leading_signs: Number of leading sign-bits.
leading_zeros: Number of leading zeros.
real: Real part.
trailing_zeros: Number of trailing zeros.

Methods

`cast`	Change format of the complex-valued fixed-point number.
`conj`	Retrieve complex conjugate.
`copy`	Create a copy of the object.
`from_complex`
`from_float`
`from_number`
`is_identical`	Test if two fixed-point objects are exactly identical.
`to_bits`	Retrieve underlying bit-pattern in a `tuple` of `int`.

Constructor¶

__init__(self, bit_pattern: int, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → None¶
__init__(self, bit_pattern: tuple[int, int], int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → None

Creation from other types¶

from_complex(value: object, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyCFixed¶

Create an APyCFixed object from an int, float, complex, APyFixed, APyFloat, or APyCFixed.

Attention

It is in all cases better to use cast() to create an APyCFixed from an 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.

Parameters:

valueint, float, complex: Value to initialize from
int_bitsint, optional: Number of integer bits in the created fixed-point object
frac_bitsint, optional: Number of fractional bits in the created fixed-point object
bitsint, optional: Total number of bits in the created fixed-point object

Returns:

APyCFixed

Examples

Complex-valued fixed-point fx_a, initialized from the complex number 1.234 + 0.4j, rounded to 1.25 + 0.5j as it is the closest representable number.

>>> import apytypes as apy
>>> fx_a = apy.APyCFixed.from_complex(1.234 + 0.4j, int_bits=2, frac_bits=2)
>>> fx_a
APyCFixed((5, 2), bits=4, int_bits=2)
>>> print(fx_a)
(1.25+0.5j)

from_float(value: object, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyCFixed¶: Alias for from_complex().

from_number(value: object, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyCFixed¶: Alias for from_complex().

Change word length¶

Change format of the complex-valued fixed-point number.

This is the primary method for performing quantization and overflowing/saturation when dealing with APyTypes fixed-point numbers. The specified quantization and overflow are applied piecewise to the real and imaginary part.

Exactly two of three bit-specifiers (bits, int_bits, frac_bits) needs to 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:

APyCFixed

Examples

>>> import apytypes as apy
>>> fx = apy.fx(2.125 + 1.625j, int_bits=3, frac_bits=3)

# Truncation: 2.0 + 1.5j >>> fx.cast(int_bits=3, frac_bits=2, quantization=apy.QuantizationMode.TRN) APyCFixed((8, 6), bits=5, int_bits=3)

# Fixed-point rounding: 2.25 + 1.75j >>> fx.cast(int_bits=3, frac_bits=2, quantization=apy.QuantizationMode.RND) APyCFixed((9, 7), bits=5, int_bits=3)

# Two’s complement overflowing: -1.875 + 1.625j >>> fx.cast(int_bits=2, frac_bits=3, overflow=apy.OverflowMode.WRAP) APyCFixed((17, 13), bits=5, int_bits=2)

Get bit representation¶

to_bits(self) → tuple[int, int]¶

Retrieve underlying bit-pattern in a tuple of int.

Returns:

tuple of int

Examples

Create complex-valued fixed-point number fx_a of value -5.75 + 2j and show its bit pattern (real, imag)

>>> import apytypes as apy
>>>
>>> fx_a = apy.fx(-5.75 + 2j, int_bits=4, frac_bits=4)
>>> fx_a.to_bits()
(164, 32)

Comparison¶

is_identical(self, other: APyCFixed | APyCFixedArray) → bool¶

Test if two fixed-point objects are exactly identical.

Two APyCFixed objects are considered exactly identical if, and only if, they represent the same fixed-point value, and have the exact same bit-specification (bits, int_bits, and frac_bits). This is a more restrictive test than ==, that only tests equality of the numerical fixed-point value.

Parameters:

otherAPyCFixed: The fixed-point number to test identicality against

Returns:

bool

Examples

Complex-valued fixed-point fx_a and fx_b. They are equal, as they store the same value, but they are not identical as the differ in the int_bits specifier.

>>> import apytypes as apy
>>> fx_a = apy.fx(2.0 + 3.0j, int_bits=3, frac_bits=3)
>>> fx_b = apy.fx(2.0 + 3.0j, int_bits=4, frac_bits=3)
>>> fx_a == fx_b
True
>>> fx_a.is_identical(fx_b)
False