`APyFixed`¶

class apytypes.APyFixed¶

Class for configurable scalar fixed-point formats.

APyFixed is an arbitrary precision two’s complement fixed-point scalar type. In many ways it behaves like the built-in Python types int and float, in that it can be used within ordinary arithmetic expressions. 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. Only two of three bit specifers need to be set to uniquely determine the complete fixed-point format.

In general, the fixed-point representation is described by:

\[\underbrace{ \underbrace{ x_{n-1} \; x_{n-2} \; \ldots \; x_{k+1} \; x_{k} }_{\mathrm{int\_bits}} \; . \; \underbrace{ x_{k-1} \; x_{k-2} \; \ldots \; x_{1} \; x_{0} }_{\mathrm{frac\_bits}} }_{\mathrm{bits}}\]

The following is an example of a fixed-point number with bits=8, int_bits=5, and frac_bits=3, that has a stored value of -6.625:

\[\begin{align*} 1 \, 1 \, 0 \, 0 \, 1 \,.\, 0 \, 1 \, 1_{2} = \frac{-53_{10}}{2^3} = -6.625_{10} \end{align*}\]

APyFixed uses static word-length inference to determine word lengths of results to arithmetic operations. This ensures that overflow or quantization never occurs unless explicitly instructed to by a user through the cast() method. The following table shows word lengths of elementary arithmetic operations.

For complex-valued fixed-point formats, see APyCFixed.

Word-length of fixed-point arithmetic operations using `APyFixed`¶
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`	`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.
int_bits: Number of integer bits.
is_zero: True if the value equals zero, false otherwise.
leading_fractional_zeros: Number of leading zeros after the binary fixed-point.
leading_ones: Number of leading ones.
leading_signs: Number of leading signs.
leading_zeros: Number of leading zeros.

Methods

`cast`	Change format of the fixed-point number.
`from_float`
`from_str`
`is_identical`	Test if two fixed-point objects are exactly identical.
`to_bits`	Retrieve underlying bit-pattern in an `int`.

Constructor¶

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

Creation from other types¶

from_float(value: object, int_bits: int | None = None, frac_bits: int | None = None, bits: int | None = None) → APyFixed¶

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

Note

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

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: Floating point 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:

APyFixed

Examples

>>> from apytypes import APyFixed
>>> fx_a = APyFixed.from_float(1.234, int_bits=2, frac_bits=2)

Fixed-point fx_a, initialized from the floating-point value 1.234, rounded to 1.25 as it is the closest representable number

>>> fx_a
APyFixed(5, bits=4, int_bits=2)
>>> str(fx_a)
'1.25'

from_str(string_value: str, int_bits: int | None = None, frac_bits: int | None = None, base: int = 10, bits: int | None = None) → APyFixed¶

Create an APyFixed object from str.

Exactly two of three bit-specifiers (bits, int_bits, frac_bits) must be set.

Parameters:

string_valuestr: String to initialize the value 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
baseint, default: 10: Numeric base used in string_value
bitsint, optional: Total number of bits in the created fixed-point object

Returns:

APyFixed

Examples

>>> from apytypes import APyFixed

Larger fixed-point value initialization from a string (base-10)

>>> fx_a = APyFixed.from_str(
...     "-1376018206341311063223476816643087998331620501540496640."
...     "021222579872958058370179355618716816066859017361262100333952697594702"
...     "314679773970519809467311447652539955943903993200932791396783892142688"
...     "708904952458654442554723081083186210082207584128592922850820472478833"
...     "257136662269306798708182072507551281664490003441493733349403017982015"
...     "56238154807942919433116912841796875",
...     bits=511,
...     int_bits=199,
...     base=10
... )

Change word length¶

Change format of the fixed-point number.

This is the primary method for performing quantization and overflowing/saturation when dealing with APyTypes fixed-point numbers.

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:

APyFixed

Examples

>>> from apytypes import APyFixed
>>> from apytypes import QuantizationMode
>>> from apytypes import OverflowMode
>>> fx = APyFixed.from_float(2.125, int_bits=3, frac_bits=3)

Truncation (2.0)

>>> fx.cast(int_bits=3, frac_bits=2, quantization=QuantizationMode.TRN)
APyFixed(8, bits=5, int_bits=3)

Rounding (2.25)

>>> fx.cast(int_bits=3, frac_bits=2, quantization=QuantizationMode.RND)
APyFixed(9, bits=5, int_bits=3)

Two’s complement overflowing (-1.875)

>>> fx.cast(int_bits=2, frac_bits=3, overflow=OverflowMode.WRAP)
APyFixed(17, bits=5, int_bits=2)

Get bit representation¶

to_bits(self) → int¶

Retrieve underlying bit-pattern in an int.

Returns:

int

Examples

>>> from apytypes import APyFixed

Create fixed-point number fx_a of value -5.75

>>> fx_a = APyFixed.from_float(-5.75, int_bits=4, frac_bits=4)

Returns: 164 == 0xA4 == 0b10100100

>>> fx_a.to_bits()
164

Comparison¶

is_identical(self, other: APyFixed) → bool¶

Test if two fixed-point objects are exactly identical.

Two APyFixed 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:

otherAPyFixed: The fixed-point number to test identicality against

Returns:

bool

Examples

>>> from apytypes import APyFixed
>>> fx_a = APyFixed.from_float(2.0, int_bits=3, frac_bits=3)
>>> fx_b = APyFixed.from_float(2.0, int_bits=4, frac_bits=3)