`APyCFloat`¶

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

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

Added in version 0.4.

Note

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

Attributes:

bias: Exponent bias.
bits: Total number of bits.
exp_bits: Number of exponent bits.
imag: Imaginary part.
is_zero: True if, and only if, both the real and imaginary parts are zero.
man_bits: Number of mantissa bits.
real: Real part.

Methods

`cast`	Change format of the complex-valued floating-point number.
`copy`	Create a copy of the object.
`from_bits`
`from_complex`
`from_float`
`is_identical`	Test if two `APyCFloat` objects are identical.
`to_bits`	Get the bit-representation of an `APyCFloat`.

Constructor¶

__init__(self, sign: bool | int, exp: int, man: int, exp_bits: int, man_bits: int, bias: int | None = None) → None¶

__init__(self, sign: tuple[bool | int, bool | int], exp: tuple[int, int], man: tuple[int, int], exp_bits: int, man_bits: int, bias: int | None = None) → None

Overloaded function.

__init__(self, sign: bool | int, exp: int, man: int, exp_bits: int, man_bits: int, bias: int | None = None) -> None
__init__(self, sign: tuple[bool | int, bool | int], exp: tuple[int, int], man: tuple[int, int], exp_bits: int, man_bits: int, bias: int | None = None) -> None

Create an APyCFloat object and initialize both real and imaginary parts.

Parameters:

signtuple of int or bool: Sign of real/imaginary parts. True/non-zero equals negative.
exptuple of int: Exponent of real/imaginary parts as stored, i.e., actual value + bias.
mantuple of int: Mantissa of the real/imaginary parts as stored, i.e., without a hidden one.
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:

APyCFloat

Creation from other types¶

from_complex(value: object, exp_bits: int, man_bits: int, bias: int | None = None) → APyCFloat¶

Create an APyCFloat object from an int, float, or complex.

The initialize floating-point value is the one closest to value. Ties are rounded using QuantizationMode.TIES_EVEN.

Parameters:

valuecomplex, float, int: Value to initialize from.
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:

APyCFloat

See also

from_complex

Examples

>>> import apytypes as apy
>>> a = apy.APyCFloat.from_complex(1.375, exp_bits=10, man_bits=15)
>>> a
APyCFloat(sign=(0, 0), exp=(511, 0), man=(12288, 0), exp_bits=10, man_bits=15)
>>> str(a)
'(1.375+0j)'

from_float(value: object, exp_bits: int, man_bits: int, bias: int | None = None) → APyCFloat¶

Create an APyCFloat object from an int, float, or complex.

The initialize floating-point value is the one closest to value. Ties are rounded using QuantizationMode.TIES_EVEN.

Parameters:

valueint, float, complex: Value to initialize from.
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:

APyCFloat

See also

from_complex

Examples

>>> import apytypes as apy
>>> a = apy.APyCFloat.from_float(1.25, exp_bits=10, man_bits=15)
>>> a
APyCFloat(sign=(0, 0), exp=(511, 0), man=(8192, 0), exp_bits=10, man_bits=15)
>>> str(a)
'(1.25+0j)'

from_bits(bits: tuple, exp_bits: int, man_bits: int, bias: int | None = None) → APyCFloat¶

Create an APyCFloat object from a bit-representation. For convenience, leaving out the second item in the tuple initializes the imaginary part to 0.

Parameters:

bitstuple of int: The bit-representation for the float.
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:

APyCFloat

See also

to_bits
from_float

Examples

Create a complex-valued floating-point number a of value -5.75 + 2j from its bit pattern (real, imag).

>>> import apytypes as apy
>>>
>>> a = apy.APyCFloat.from_bits((791, 256), exp_bits=5, man_bits=4)
>>> a
APyCFloat(sign=(1, 0), exp=(17, 16), man=(7, 0), exp_bits=5, man_bits=4)

Create a floating-point number b of value 1.0 + 0j from its bit pattern. Initializing from (240,) is equivalent to initializing from (240, 0).

>>> b = apy.APyCFloat.from_bits((240, ), exp_bits=5, man_bits=4)
>>> b
APyCFloat(sign=(0, 0), exp=(15, 0), man=(0, 0), exp_bits=5, man_bits=4)

Change word length¶

cast(self, exp_bits: int | None = None, man_bits: int | None = None, bias: int | None = None, quantization: QuantizationMode | None = None) → APyCFloat¶

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

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

Parameters:

exp_bitsint, optional: Number of exponent bits in the result.
man_bitsint, optional: Number of mantissa bits in the result.
biasint, optional: Exponent bias. If not provided, bias is 2**exp_bits - 1.
quantizationQuantizationMode, optional.: Quantization mode to use in this cast. If None, use the global quantization mode.

Returns:

APyCFloat

Get bit representation¶

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

Get the bit-representation of an APyCFloat.

Returns:

tuple of int

See also

from_bits

Examples

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

>>> import apytypes as apy
>>>
>>> a = apy.fp(-5.75 + 2j, exp_bits=5, man_bits=4)
>>> a.to_bits()
(791, 256)

Comparison¶

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

Test if two APyCFloat objects are identical.

Two APyCFloat objects are considered identical if, and only if, they have the same sign, exponent, mantissa, and format.

Parameters:

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