ket.base.quant

Quantum register abstraction.

This module defines the Quant class, which represents a list of qubit indices and serves as the fundamental quantum object in Ket.

Classes ket.base.quant

Quant

List of qubits.

class Quant(*, qubits: list[int], process, undo=None, source=None)

List of qubits.

This class represents a list of qubit indices within a quantum process. Direct instantiation of this class is not recommended. Instead, it should be created by calling the alloc method.

A Quant serves as a fundamental quantum object where quantum operations should be applied.

Example

from ket import *
# Create a quantum process
p = Process()
# Allocate 2 qubits
q1 = p.alloc(2)
# Apply a Hadamard gates on the first qubit of `q1`
H(q1[0])
# Allocate more 2 qubits
q2 = p.alloc(2)
# Concatenate two Quant objects
result_quant = q1 + q2
print(result_quant)
# <Ket 'Quant' [0, 1, 2, 3] pid=0x...>
# Use the fist qubit to control the application of
# a Pauli X gate on the other qubits
ctrl(result_quant[0], X)(result_quant[1:])
# Select qubits at specific indexes
selected_quant = result_quant.at([0, 1])
print(selected_quant)
# <Ket 'Quant' [0, 1] pid=0x...>

Supported operations:

• Addition (+): Concatenates two Quant objects. The processes must be the same.

• Indexing ([index]): Returns a new Quant object with selected qubits based on the provided index.

• Iteration (for q in qubits): Allows iterating over qubits in a Quant object.

• Reversal (reversed(qubits)): Returns a new Quant object with reversed qubits.

• Length (len(qubits)): Returns the number of qubits in the Quant object.

at(index: list[int]) → Quant

Return a subset of qubits at specified indices.

Create a new Quant object with qubit references at the positions defined by the provided index list.

Example

from ket import *
# Create a quantum process
p = Process()
# Allocate 5 qubits
q = p.alloc(5)
# Select qubits at odd indices (1, 3)
odd_qubits = q.at([1, 3])

Parameters:

index – List of indices specifying the positions of qubits to be included in the new Quant.

Returns:

A new Quant object containing the selected qubits.

as_int(number: int = 0)

Interpret and initialize this quantum register as a quantum integer.

Wraps the register as a Qint, enabling quantum arithmetic operations (addition, subtraction, comparison, etc.) on the underlying qubits. The register is initialized to the given classical integer value using X gates.

The Qint uses a two’s-complement signed representation internally.

Example

from ket import Process, measure
p = Process()
q = p.alloc(5)
qi = q.as_int(5)    # register initialized to |5⟩
qi += 3             # in-place addition: |5⟩ → |8⟩
print(measure(qi).value)
# 8

Parameters:

number – The initial classical integer value to encode into the quantum register. Defaults to 0.

Returns:

A quantum integer wrapping this register, initialized to number.

as_real(exp: int, number: float = 0.0)

Interpret and initialize this quantum register as a fixed-point quantum real number.

Wraps the register as a Qreal, enabling quantum arithmetic operations on floating-point values encoded in a fixed-point binary representation.

The real number is stored internally as an integer scaled by \(2^{\texttt{exp}}\):

• A positive exp increases fractional precision (smaller representable step size of \(2^{-\texttt{exp}}\)).

• A negative exp increases the representable magnitude at the cost of precision.

Example

from ket import Process, measure
p = Process()
q = p.alloc(8)         # 8 qubits for fixed-point
qr = q.as_real(4, 1.5) # precision: 1/16, initialized to 1.5
qr += 0.25             # in-place addition
print(measure(qr).value)
# 1.75

Parameters:

• exp – The exponent defining the fixed-point scale. The stored integer n represents the real value n / 2**exp.

• number – The initial classical float value to encode into the quantum register. Defaults to 0.0.

Returns:

A quantum real number wrapping this register, initialized to number.

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).

copy(depends_on: list | None = None)

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.

Parameters:

depends_on – A list of objects (such as other Quant instances) that the new auxiliary register depends on. This dependency prevents early uncomputation; for example, if b depends on a, a cannot be uncomputed before b. Defaults to None.

Returns:

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