`APyCFixed`¶

class apytypes.APyCFixed¶

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 overall number of bits in an APyCFixed is 2 * bits. Only two of three bit specifers need to be set to uniquely determine the complete fixed-point format.

For real-valued fixed-point formats, see APyFixed.

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.
real: Real part.

Methods

`cast`	Change format of the complex-valued fixed-point number.
`from_complex`
`from_float`
`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_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.

Note

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.

>>> from apytypes import APyCFixed
>>>
>>> fx_a = APyCFixed.from_complex(1.234 + 0.4j, int_bits=2, frac_bits=2)
>>> fx_a
APyCFixed((5, 2), bits=4, int_bits=2)
>>> str(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¶

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

Note

It is in all cases better to use cast() to create an APyCFixed from an APyCFixed.

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

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

>>> from apytypes import APyCFixed
>>> from apytypes import QuantizationMode
>>> from apytypes import OverflowMode
>>>
>>> fx = APyCFixed.from_complex(2.125 + 1.625j, int_bits=3, frac_bits=3)
>>>
>>> # Truncation: 2.0 + 1.5j
>>> fx.cast(int_bits=3, frac_bits=2, quantization=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=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=OverflowMode.WRAP)
APyCFixed((17, 13), bits=5, int_bits=2)

Get bit representation¶

to_bits(self) → tuple¶

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)

>>> from apytypes import APyCFixed
>>>
>>> fx_a = APyCFixed.from_complex(-5.75 + 2j, int_bits=4, frac_bits=4)
>>> fx_a.to_bits()
(164, 32)

Comparison¶

is_identical(self, other: APyCFixed) → 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.

>>> from apytypes import APyCFixed
>>>
>>> fx_a = APyCFixed.from_complex(2.0 + 3.0j, int_bits=3, frac_bits=3)
>>> fx_b = APyCFixed.from_complex(2.0 + 3.0j, int_bits=4, frac_bits=3)
>>> fx_a == fx_b
True
>>> fx_a.is_identical(fx_b)
False