ket.qint

Quantum integer and fixed-point real number data structures.

This module provides Qreal and Qint, two high-level quantum data structures that wrap a Quant register and expose Python-style arithmetic operators as quantum operations.

Both types use a QFT-based arithmetic approach:

  • In-place addition/subtraction are implemented via phase rotations in the Quantum Fourier Transform basis.

  • Quantum comparisons (__lt__, etc.) produce ancilla qubit results that are cleaned up automatically via undo.

  • Multiplication and division are built from repeated addition in the Fourier basis.

All operations produce uncomputed intermediate registers where possible, keeping the circuit depth manageable.

Typical Usage

from ket import Process, measure

p = Process()
q = p.alloc(8)

# Integer arithmetic
qi = q.as_int(7)    # initialize register to |7⟩
qi += 3             # quantum addition: |7⟩ → |10⟩
print(measure(qi).value)   # 10
# 10

from ket import Process, measure

p = Process()
q = p.alloc(8)

# Fixed-point real arithmetic with 4 bits of fractional precision
qr = q.as_real(4, 1.5)   # step size 2**-4 = 0.0625
qr += 0.25
print(measure(qr).value)  # 1.75
# 1.75

Classes ket.qint

Qint

A quantum register interpreted as a signed integer.

Qreal

A quantum register interpreted as a fixed-point signed real number.
class Qint(qubits, number: int = 0)

A quantum register interpreted as a signed integer.

A specialization of Qreal with exp=0, meaning the stored integer is the value directly (no fractional scaling). Uses two’s-complement representation for signed arithmetic.

Example

from ket import Process, measure

p = Process()
q = p.alloc(4)

qi = q.as_int(-3)   # two's-complement encoding
qi += 5
print(measure(qi).value)   # 2
# 2
Parameters:

  • qubits – The quantum register to wrap.

  • number – Initial integer value to encode. Defaults to 0.

postprocessing()

Return a function that converts a raw measurement to a signed integer.

Returns:

A function that accepts the unsigned integer measurement result and returns the corresponding signed (two’s complement) integer value.

class Qreal(qubits: Quant, exp, number: float = 0.0)

A quantum register interpreted as a fixed-point signed real number.

Extends Quant to support in-place arithmetic (\(+=\), \(-=\)), non-in-place arithmetic (\(+\), \(-\), \(\times\), \(/\)), and comparisons (\(<\), \(>\), \(\leq\), \(\geq\), \(=\), \(\neq\)) as quantum operations.

The register stores a two’s-complement signed integer \(n\) that represents the real value

\[x = \frac{n}{2^{\texttt{exp}}}\]

  • A positive exp gives finer fractional resolution (\(2^{-\texttt{exp}}\) per step).

  • A negative exp gives coarser resolution but a larger range.

Example

from ket import Process, measure

p = Process()
q = p.alloc(8)            # 8-qubit register

# Fixed-point with 4-bit fractional precision (step = 1/16)
qr = q.as_real(4, 1.5)    # stored integer = round(1.5 * 16) = 24
qr += 0.5                 # 24 + 8 = 32 → x = 32/16 = 2.0
print(measure(qr).value)  # 2.0
# 2.0
Parameters:

  • qubits – The quantum register to wrap.

  • exp – Fixed-point exponent. The register stores round(number * 2**exp).

  • number – Initial real value to encode. Defaults to 0.0.

copy()

Create a copy of this register in a fresh auxiliary register.

Allocates a new auxiliary qubit register of the same size and uses CNOT gates to copy the state qubit-by-qubit. The copy is wrapped in undo so that the auxiliary register is automatically uncomputed when the returned object goes out of scope.

Returns:

A new Qreal wrapping an auxiliary register that holds a copy of this register’s state.

mul(other, result)

Quantum multiplication: accumulate self * other into result.

Performs an in-place multiply-accumulate: each bit of self (the multiplier) controls an addition of the appropriately shifted other (the multiplicand) into result.

This method is used internally by __mul__ and __truediv__.

Parameters:

  • other – The multiplicand. If a Qreal, the fixed-point exponents are reconciled automatically.

  • result – The target register where the product is accumulated. Must be initialized to 0.

postprocessing()

Return a function that converts the raw qubit measurement to a float.

Used internally by measure and dump to convert the measured integer back to its fixed-point float representation.

Returns:

A function that accepts the raw unsigned integer measurement result and returns the corresponding float value (with sign extension for two’s-complement).

dump_format()

Return the state-formatting callable used by dump.

Provides a function that converts a raw integer basis-state index into a zero-padded binary string of the correct width for this register. This is used internally by QuantumState to display multi-register states with per-register labels.

Returns:

A function that accepts an integer basis-state value and returns its binary string representation (zero-padded to len(self) bits).