pyfxp 0.2.0

Python fixed-point library..

pyfxp package

• Documentation
• PyPI
• Sources
• Issues

pyfxp brings fixed-point precision to Python — simple, fast, and explicit.

Define numbers in ARM-style Q-format, control every bit of precision, rounding, and overflow, and even JIT-compile your code with Numba for high-speed execution.

Key Features

• Clear, expressive API (fxp, fxpt, and Q)
• Configurable overflow & rounding modes (SAT, WRAP, HALF_EVEN, etc.)
• Numba-compatible — ready for high-performance, JIT-compiled fixed-point operations.
• Works with scalars and numpy arrays.
• No need to work with a custom fixed-point data-type.
• Perfect for DSP, control, and embedded algorithm prototyping.

Installation

Installing it is pretty easy:

pip install pyfxp

Quick Start

pyfxp offers two ways to convert numbers to a fixed-point format:

• fxpt → “typed” (parameter-based) Pass the format directly as function parameters.
• fxp → “spec-based” (explicit FxpSpec) Build a reusable spec with Q(...), then pass that spec.

Use the fxpt function when the format is simple or used in a single place:

from pyfxp import fxpt
from pyfxp.constants import SAT, HALF_EVEN  # overflow & rounding modes

y = fxpt(
    x=3.14159,
    qi=3,            # integer bits (including sign when signed=True)
    qf=13,           # fractional bits
    signed=True,     # signed or unsigned format
    ovf=SAT,         # overflow behavior: WRAP | SAT | ERROR
    rnd=HALF_EVEN,   # rounding: TRUNC, CEIL, TO_ZERO, AWAY, HALF_UP, ...
)

!!! note "ARM-style Q-format" In ARM-style Q-format notation (used by pyfxp), the sign bit is included in the integer bit count qi. Refer to Q (number format) for more information.

Use fxp when you want a reusable, readable definition. The fixed-point format is defined using the Q(...) function once, and can be reused for different fxp calls:

import numpy as np
from pyfxp import fxp, Q
from pyfxp.constants import SAT, HALF_EVEN

# Define the format once
Q3_13 = Q(qi=3, qf=13, signed=True, ovf=SAT, rnd=HALF_EVEN)

# Reuse it across your codebase
y1 = fxp(3.14159, Q3_13)
y2 = fxp(np.array([0.1, 0.2, 0.3]), Q3_13)

Q(...) returns an FxpSpec instance which is basically a named tuple containing the specs used by fxp.

When specifying the fixed-point specs using either fxpt or Q, all the following rounding and overflow modes are supported:

Rounding modes:

Constant	Description
TRUNC	Bit truncation (rounds toward negative infinity)
CEIL	Round toward positive infinity
TO_ZERO	Round toward zero
AWAY	Round away from zero
HALF_UP	Round to nearest; ties toward positive infinity
HALF_DOWN	Round to nearest; ties toward negative infinity
HALF_EVEN	Round to nearest; ties to even
HALF_ZERO	Round to nearest; ties toward zero
HALF_AWAY	Round to nearest; ties away from zero

Overflow modes:

Constant	Description
WRAP	Wrap around on overflow (modular arithmetic)
SAT	Saturate at the maximum/minimum representable value
ERROR	Raise an exception on overflow

The constants above are defined in the pyfxp.constants module. They are used by both fxpt and fxp to specify fixed-point arithmetic behavior.

!!! tip "Usage example" These constants are simple numeric codes — meant to be readable and interoperable with compiled or vectorized backends (e.g. Numba or C extensions).

```python
from pyfxp.constants import SAT, HALF_EVEN
fxpt(1.25, qi=3, qf=13, ovf=SAT, rnd=HALF_EVEN)
```