fxpmath

0.4.10 verified Mon Apr 27 auth: no python

A Python library for fractional fixed-point (base 2) arithmetic and binary manipulation with NumPy compatibility. Current version 0.4.10 (latest stable), released roughly every few months. Supports Python >=3.7. Widely used in digital signal processing and hardware emulation contexts.

pip install fxpmath

Common errors

error ValueError: invalid literal for int() with base 2: '...' ↓

cause Passing a binary string with spaces or invalid characters (e.g., '0101 0110') directly to Fxp().

fix

Use Fxp.from_bin('01010110', ...) which handles spaces and proper parsing.

error OverflowError: number of bits > n_word_max (64 bits) and no config to increase it ↓

cause Attempting to create an Fxp with a value that requires more than 64 bits without setting config.n_word_max.

fix

Set fxpmath.config.n_word_max = 128 (or required size) before creation.

error TypeError: unsupported operand type(s) for +: 'Fxp' and 'float' ↓

cause Trying to add a Python float to an Fxp object without conversion.

fix

Convert float to Fxp first: float_val = Fxp(2.5, signed=True, n_word=8, n_frac=4) then add.

Warnings

gotcha Default word length overflow wraps silently without warning unless you set config.rounding or check the overflow flag explicitly. Always specify signed, n_word, n_frac to avoid unexpected bits. ↓

fix Always pass explicit fixed-point format arguments: Fxp(value, signed=True, n_word=16, n_frac=8). Use config.overflow='wrap' or 'saturate' to control behavior.

gotcha Operations between Fxp objects with different formats may silently coerce to larger word lengths if config.op_input_size is not set to 'consistent' or 'best'. This can lead to unexpected bit growth. ↓

fix Set fxpmath.config.op_input_size = 'consistent' to require identical formats, or explicitly manage operand formats.

breaking In v0.4.9, the behavior of the wrap function changed for values exceeding n_word_max (64 bits). Previously it might have truncated; now it raises an error or wraps differently. This can break code that relied on raw binary manipulation beyond 64 bits. ↓

fix Set config.n_word_max to a higher value if you need >64 bits, or use the `Fxp` constructor with explicit word lengths rather than relying on wrap. Check the wrap utility documentation.

deprecated The `from_bin` function was introduced in 0.4.9; older code using `Fxp(val, dtype=...)` with binary string might break or produce wrong results. ↓

fix Use `Fxp.from_bin(binary_string, ...)` for binary string input. Update to fxpmath >=0.4.9.

Imports

Fxp
wrong
```
import fxpmath; fxpmath.Fxp
```
correct
```
from fxpmath import Fxp
```
While that works, direct import is idiomatic.

Quickstart

Create two fixed-point numbers with 8-bit word length and 7 fractional bits, add them, and show the result.

from fxpmath import Fxp

x = Fxp(0.5, signed=True, n_word=8, n_frac=7)
y = Fxp(0.75, signed=True, n_word=8, n_frac=7)
z = x + y
print(z)  # Returns 1.25
print(z.bin())  # Binary representation: 01.0100000