Reference: Qubits Classes¶

Contents¶

Qubits Class
QUInt Class
QInt Class
QUFixed Class
QFixed Class
CompositeRegister Class
VectorRegister Class

Qubits Class¶

psiqworkbench.Qubits ¶

Qubits(num_qubits: int | None = None, name: str | None = None, qpu: QPU | None = None, overlay_offset: int | None = None, scatter: list[int] | None = None, cond_xor: int | None = 0, from_mask: int | None = None, cs_key: str | None = None, fallback_read: FallbackReadGenerator | None = None)

Bases: BaseQubits

Qubits is the base class for all qubit-based variables. Unlike classical bit-based variables, they may be any number of bits in length.

Qubits class has subclasses with high-level-language behaviors of quantum arithmetic data types:

QInt: Signed integer
QUInt: Unsigned integer
QFixed: Signed fixed-point (fractional) values
QUFixed: Unsigned fixed-point (fractional) values

When Qubits are used raw (just as type Qubits), they behave like unsigned integers. The gate count and behavior of arithmetic operations such as addition, multiplication and comparison are determined by the types.

For more details, see Quantum Arithmetic Data Types tutorial.

Qubits objects may be sliced and re-cast as needed to perform desired operations. For example:

a = b[-1]: get just the last (most significant) qubit
a = b[::-1]: endian-reversal (big-endian to little-endian or vice versa)
a = QUInt(b): change type to unsigned integer

Quantum gates generally should be performed on Qubits objects directly. For example, a.x() is preferred over qc.x(a).

Parameters:

Name	Type	Description	Default
`num_qubits`	`int \| None`	Number of qubits to allocate. If zero or from_mask is 0, a zero-qubit register is created.	`None`
`name`	`str \| None`	Name for the qubit register, used in diagrams and labels.	`None`
`qpu`	`QPU \| None`	QPU instance to allocate the qubits from.	`None`
`overlay_offset`	`int \| None`	Deprecated and will be removed in WB 5.0.0; use `scatter` instead for specific qubit addresses.	`None`
`scatter`	`list[int] \| None`	Specifies specific qubit addresses that make up this object in order. Only used internally.	`None`
`cond_xor`	`int \| None`	Bits indicating conditional not-conditions for quantum control.	`0`
`from_mask`	`int \| None`	Global bits in the QPU for qubit addresses, overriding `num_qubits`. Only used internally.	`None`
`cs_key`	`str \| None`	If not None, associate a QubrickComputeState with this allocation. Only used internally.	`None`

Raises:

Type	Description
`ValueError`	If trying to allocate negative or invalid number of qubits.
`RuntimeError`	If `qpu` is not specified.

identifier `property` ¶

identifier: int

Returns the unique identifier for Qubits class, a mask representing the qubits relative to the QPU instance (same as mask()).

x ¶

x(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply an X (NOT) gate to specified qubits in this register.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

cnot ¶

cnot(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None)

Alias for BaseQubits.x. Deprecated and will be removed in WB 5.0.0. Use Qubits.x instead.

lelbow ¶

lelbow(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a Gidney left elbow (lelbow) operation on the specified qubits in the register.

The lelbow operation issues an approximate Toffoli gate with deferred phase correction, optimizing T gate usage in fault-tolerant quantum computing. The left elbow allows a controlled-phase error, enabling intermediate calculations without immediate correction.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

relbow ¶

relbow(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a Gidney right elbow (relbow) operation on the specified qubits in the register.

The relbow operation completes the deferred phase correction initiated by the lelbow, using a measurement and classically conditioned Z gate to remove the phase error when necessary, further reducing T gate costs in quantum circuits.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

y ¶

y(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a Pauli-Y (Y) operation to the specified qubits in this register.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

z ¶

z(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a Pauli-Z (Z) operation to the specified qubits in this register.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

identity ¶

identity(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply an identity (I) operation to the specified qubits in this register.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

s ¶

s(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply an S (π/2 phase) gate to the specified qubits in this register.

The S gate applies a π/2 phase rotation, represented by the matrix:

\[ S = \begin{bmatrix} 1 & 0 \\ 0 & i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

t ¶

t(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a T (π/4 phase) gate to the specified qubits in this register.

The T gate applies a π/4 phase rotation, represented by the matrix:

\[ T = \begin{bmatrix} 1 & 0 \\ 0 & e^{i\pi/4} \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

s_inv ¶

s_inv(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply the inverse of the S (S-dagger) gate to the specified qubits in this register.

The \(S^{\dagger}\) gate applies a -π/2 phase rotation, represented by the matrix:

\[ S^{\dagger} = \begin{bmatrix} 1 & 0 \\ 0 & -i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

t_inv ¶

t_inv(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply the inverse of the T (T-dagger) gate to the specified qubits in this register.

The \(T^{\dagger}\) gate applies a -π/4 phase rotation, represented by the matrix:

\[ T^{\dagger} = \begin{bmatrix} 1 & 0 \\ 0 & e^{-i\pi/4} \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

reflect ¶

reflect(basis: Literal['x'] | Literal['y'] | Literal['z'] = 'z', theta: float | RotationAngle | tuple[int, int] | None = None, ctrl: BaseQubits | None = None, error_param: float = 0.0) -> None

Perform a reflection about a state using the Reflect Qubrick.

Parameters:

Name	Type	Description	Default
`basis`	`str`	The reflection basis 'x', 'y', 'z'. Defaults to 'z'.	`'z'`
`theta`	`float \| RotationAngle or None`	Phase reflect angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi). Defaults to 180 degrees.	`None`
`ctrl`	`Qubits or None`	Optional quantum control.	`None`
`error_param`	`float`	A parameter to control the precision of the angle. Defaults to 0 (no error).	`0.0`

Example

reg.reflect()      # Reflection about |1...1>, equivalent to controlled Z (reg[0].z(cond=reg[1:]))
(~reg).reflect()   # Reflection about |0...0>

QFT ¶

QFT(ctrl=0, dagger=False, do_bit_reverse=True, error_param=0) -> None

Apply the quantum Fourier transform using the QFT Qubrick.

Parameters:

Name	Type	Description	Default
`ctrl`	`Qubits or None`	Optional quantum control.	`0`
`dagger`	`bool`	Optionally apply the dagger of QFT.	`False`
`do_bit_reverse`	`bool`	Optionally enable/disable for trailing bit reversal.	`True`
`error_param`	`float`	Optional error_param for all rotations. Defaults to 0 for ideal precision.	`0`

Example

reg.QFT()      # Perform QFT on reg

rx ¶

rx(theta: float | RotationAngle | tuple[int, int], tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None, error_param: float = 0.0) -> None

Apply an RX rotation gate to the specified qubits in this register.

This gate applies a rotation around the X-axis, represented by the matrix:

\[ R_x(\theta) = \begin{bmatrix} \cos(\theta/2) & -i\sin(\theta/2) \\ -i\sin(\theta/2) & \cos(\theta/2) \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`theta`	`float \| RotationAngle \| tuple[int, int]`	The rotation angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi).	required
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`
`error_param`	`float`	Parameter to control the precision of the RX rotation. Defaults to 0 for ideal precision.	`0.0`

ry ¶

ry(theta: float | RotationAngle | tuple[int, int], tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None, error_param: float = 0.0) -> None

Apply an RY rotation gate to the specified qubits in this register.

This gate applies a rotation around the Y-axis, represented by the matrix:

\[ R_y(\theta) = \begin{bmatrix} \cos(\theta/2) & -\sin(\theta/2) \\ \sin(\theta/2) & \cos(\theta/2) \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`theta`	`float \| RotationAngle \| tuple[int, int]`	The rotation angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi).	required
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`
`error_param`	`float`	Parameter to control the precision of the RY rotation. Defaults to 0 for ideal precision.	`0.0`

rz ¶

rz(theta: float | RotationAngle | tuple[int, int], tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None, error_param: float = 0.0) -> None

Apply an RZ rotation gate to the specified qubits in this register.

This gate applies a rotation around the Z-axis, represented by the matrix:

\[ R_z(\theta) = \begin{bmatrix} e^{-i\theta/2} & 0 \\ 0 & e^{i\theta/2} \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`theta`	`float \| RotationAngle \| tuple[int, int]`	The rotation angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi).	required
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`
`error_param`	`float`	Parameter to control the precision of the RZ rotation. Defaults to 0 for ideal precision.	`0.0`

phase ¶

phase(theta: float | RotationAngle | tuple[int, int] = 0.0, tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None, error_param: float = 0.0) -> None

Apply a phase rotation gate to the specified qubits in this register.

This gate applies a phase rotation, represented by the matrix:

\[ \text{Phase}(\theta) = \begin{bmatrix} 1 & 0 \\ 0 & e^{i\theta} \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`theta`	`float \| RotationAngle \| tuple[int, int]`	The phase rotation angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi).	`0.0`
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`
`error_param`	`float`	Parameter to control the precision of the phase gate. Defaults to 0 for ideal precision.	`0.0`

cphase ¶

cphase(theta: float | RotationAngle | tuple[int, int] = 0.0, error_param: float = 0.0) -> None

Apply a phase to the computational basis state \(|1...1\rangle\) of this register.

Example

reg.cphase(120) applies a phase of 120 degrees onto the basis state \(|2^n - 1\rangle\) of reg (where n = len(reg)).
(~reg).cphase(120) applies a phase of 120 degrees onto the basis state \(|0\rangle\) of reg.
(reg == 5).cphase(120) applies a phase of 120 degrees onto the basis state \(|5\rangle\) of reg.

had ¶

had(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply the Hadamard (H) operation to the specified qubits in this register.

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

rootx ¶

rootx(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a square root of the NOT gate to the specified qubits in this register.

This gate is represented by the matrix:

\[ \sqrt{X} = \frac{1}{2} \begin{bmatrix} 1+i & 1-i \\ 1-i & 1+i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

rootx_inv ¶

rootx_inv(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply the inverse of the square root of the NOT gate to the specified qubits in this register.

This gate is represented by the matrix:

\[ \sqrt{X}^\dagger = \frac{1}{2} \begin{bmatrix} 1-i & 1+i \\ 1+i & 1-i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

rooty ¶

rooty(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply a square root of the Y gate to the specified qubits in this register.

This gate applies a half rotation about the Y-axis, represented by the matrix:

\[ \sqrt{Y} = \frac{1}{2} \begin{bmatrix} 1+i & -1+i \\ 1+i & 1-i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

rooty_inv ¶

rooty_inv(tgt_bits: OpInput = None, cond: OpInput = None, cond_zip: T | None = None, cond_reg: T | None = None) -> None

Apply the inverse of the square root of the Y gate to the specified qubits in this register.

This gate is a -π/2 rotation around the Y-axis, represented by the matrix:

\[ \sqrt{Y}^\dagger = \frac{1}{2} \begin{bmatrix} 1-i & -1-i \\ 1-i & 1+i \end{bmatrix} \]

Parameters:

Name	Type	Description	Default
`tgt_bits`	`OpInput`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`OpInput`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`T \| None`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`T \| None`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

check_value_fits_in_type ¶

check_value_fits_in_type(value: int | float, do_warning: bool = True) -> bool

Check if the provided value can fit within the number of qubits available in the current register without overflow.

For example

The number 100 won't fit in a 4-qubit register.
The number 250 fits in an 8-qubit QUInt, but not in an 8-qubit QInt, since the sign bit takes up one of the qubits.

Notes

These checks do not inspect the state vector for actual zero values; they only consider the register size and type to determine if the value can fit.
Special case: For a 1-qubit QInt register (using 2's complement), only the values 0 and -1 are technically representable, but 1 is also allowed, as it is generally expected with a 1-qubit register.
For QFixed and QUFixed, approximate values (e.g., 0.1) will return True if they fit within the qubit capacity, even if they cannot be represented precisely.

Parameters:

Name	Type	Description	Default
`value`	`int or float`	The value to be checked.	required
`do_warning`	`bool`	If True, issue a warning if the value does not fit. Defaults to True.	`True`

Returns:

Type	Description
`bool`	True if the Qubits register can represent the value without overflow.

coerce_value ¶

coerce_value(value: int | float, do_warning: bool = True) -> int | float

Convert a value to this type, and warn if it's not exact.

Parameters:

Name	Type	Description	Default
`value`	`int or float`	The value to be converted.	required
`do_warning`	`bool`	If True, issue a warning if the value does not fit. Defaults to True.	`True`

qubit_indices ¶

qubit_indices()

Get the indices of the qubits in the register.

Returns:

Type	Description
`tuple`	Indices of the qubits in this register.

pull_state ¶

pull_state(normalize: bool = True) -> np.ndarray

Pull the quantum state of the qubit register as a state vector directly from the full system state.

This method extracts the pure quantum state of a register from the full statevector when the register is not entangled with the rest of the system (the environment).

If the state of the register is entangled with the rest of the system, this function returns a normalized verison of the most populated state vector, with the most non-zero amplitudes for the given register among the other states in the system.

Mathematical Background

The global state can be assumed to be of the form:

\[ |\Psi\rangle = \sum_{i,j} c_{ij} \, |i\rangle_R \otimes |j\rangle_E \]

Here:

\(|i\rangle_R\) are basis states of the register,
\(|j\rangle_E\) are basis states of the environment (all other qubits),
\(c_{ij}\) are complex amplitudes in the full statevector.

If the system is in a product state, then all its amplitudes factor as \(c_{ij} = \alpha_i \beta_j\), and the state can be represented as follows:

\[ |\Psi\rangle = \left(\sum_i \alpha_i |i\rangle_R\right) \otimes \left(\sum_j \beta_j |j\rangle_E\right) \]

This does not hold if the register is entangled with other register. In this case, the state vector of the register is not fully separable, there may be different state vectors for different environments.

This method:

Iterates over each environment
For each term in the register's state vector
Finds the amplitude of the combination of the environment and register terms
Determines the probability of the isolated register state vector in the overall state.
Determines the register state vector with the greatest probability and the greatest number of non-zero amplitudes.

This yields the register's state vector (up to normalization) for the greatest probability state vector among environments in the system.

Parameters:

Name	Type	Description	Default
`normalize`	`bool`	Whether to normalize the returned state vector. Defaults to True (normalize it).	`True`

Returns:

Type	Description
`ndarray`	A normalized complex vector of length \(2^n\) representing the quantum state of the register, where \(n\) is the number of qubits in the register. The returned state is correct up to a global phase, which means it may differ from the expected state by a complex phase factor \(e^{i\phi}\).

To correct the phase when comparing with an expected state, you can use:

def correct_phase(state, expected_state):
    inner_product = np.vdot(expected_state, state)  # np.vdot does complex conjugate of first arg
    global_phase = np.angle(inner_product)
    phase_correction = np.exp(-1j * global_phase)
    return state * phase_correction

# Then compare the corrected state
corrected_state = correct_phase(state, expected_state)
assert np.allclose(corrected_state, expected_state)

is_allocated ¶

is_allocated() -> bool

Check if the qubits of this register are currently allocated on the QPU.

Returns:

Type	Description
`bool`	True if the qubits are allocated, False otherwise.

allocate ¶

allocate(qpu: QPU | None = None)

Allocate qubits on the QPU for this Qubits object.

Parameters:

Name	Type	Description	Default
`qpu`	`QPU \| None`	The QPU instance on which to allocate the qubits. If not provided, uses the assigned QPU.	`None`

Raises:

Type	Description
`RuntimeError`	If allocation fails or if qubits are already allocated.

release ¶

release(clear_to_zero: bool = False) -> None

Release the qubits associated with this Qubits object.

This method frees the allocated qubits, making them available for other operations. Releasing is idempotent: multiple calls to release() will have no additional effect after the first successful release.

Parameters:

Name	Type	Description	Default
`clear_to_zero`	`bool`	If `True`, resets the qubits to the `0` state before release. Defaults to `False`.	`False`

Notes

Releasing qubits associated with an overlay or scatter does not clear them to zero, as these qubits are managed separately.
If this Qubits object was the initial owner of the allocated qubits, releasing will reset the ownership flags and nullify the address references.

set_random ¶

set_random()

Set the qubits register to a random quantum state.

This method generates a random quantum state and sets the register to that state using push_state. The random state is generated using numpy's random number generator.

Note

The randomness is controlled by numpy's random seed. Use np.random.seed(seed) or qc.random_seed(seed) to set a specific seed for reproducibility.

push_state ¶

push_state(state_vector, normalize=True)

Push a quantum state to the qubits register.

This method uses a native optimized implementation to push the state. The destination register's qubits must be consecutively allocated in the QPU (this is the case by default with most Qubits objects).

Note

The qubits register is reset to |0⟩ before the state vector is pushed to it.

Parameters:

Name	Type	Description	Default
`state_vector`	`list or ndarray`	A state vector describing the desired quantum state. Can be provided as a list or numpy array. The length must be \(2^n\), where \(n\) is the number of qubits in the register. Will be converted to a complex numpy array internally.	required
`normalize`	`bool`	Whether to normalize the state vector. Defaults to True.	`True`

Raises:

Type	Description
`ValueError`	If the destination register is scattered (non-consecutive) qubits.
`ValueError`	If the state vector dimensions don't match the register size.

nop ¶

nop()

Perform a no-operation (NOP) on the associated QPU. Typically used for timing or alignment purposes.

Example:

```python
qubits = Qubits(num_qubits=4, qpu=qpu_instance)
qubits.nop()  # Executes a no-operation on the QPU
```

mask ¶

mask(base_mask: int | None = None) -> int

Calculate and return the binary mask representing the qubits relative to the QPU instance.

Parameters:

Name	Type	Description	Default
`base_mask`	`int`	Base bitmask to apply to the qubits in this register. Defaults to ~0 (all qubits in the register).	`None`

Returns:

Type	Description
`int`	The bitmask representing the active qubits in the register, adjusted according to `base_mask`.

Raises:

Type	Description
`ValueError`	If the Qubits instance has been released or is otherwise inaccessible.

Example

qubits = Qubits(num_qubits=4, qpu=qpu_instance)
qubits_mask = qubits.mask()  # Gets the mask for the qubits

box ¶

box(label='', tgt_bits=None, cond=None, cond_zip=None, cond_reg=None)

Apply a labeled box operation on the qubits in this register.

This method uses the box operation on the qubits specified by tgt_bits, with optional conditions. The box label can be used to create regions in quantum diagrams, showing where operations begin and end.

Parameters:

Name	Type	Description	Default
`label`	`str`	A label for the box to distinguish it in a diagram. Defaults to an empty string.	`''`
`tgt_bits`	`int, list, or None`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`int`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`Qubits`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`Qubits`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

box_open ¶

box_open(label='', tgt_bits=None, cond=None, cond_zip=None, cond_reg=None)

Start a labeled box region on the qubits in this register.

The box_open method defines the beginning of a region in a quantum diagram, encapsulating multiple operations within the specified qubits. Conditional execution can be applied if required.

Parameters:

Name	Type	Description	Default
`label`	`str`	A label for the box to distinguish it in a diagram. Defaults to an empty string.	`''`
`tgt_bits`	`int, list, or None`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`int`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`Qubits`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`Qubits`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

box_close ¶

box_close(label='', tgt_bits=None, cond=None, cond_zip=None, cond_reg=None)

End a labeled box region on the qubits in this register.

The box_close method marks the end of a previously opened box region in a quantum diagram, encapsulating multiple operations within the specified qubits. Conditional execution can be applied if required.

Parameters:

Name	Type	Description	Default
`label`	`str`	A label for the box to distinguish it in a diagram. Defaults to an empty string.	`''`
`tgt_bits`	`int, list, or None`	Target bits within the register or None to apply a gate to each qubit in the register.	`None`
`cond`	`int`	Control qubits register for applying the same condition to all targets.	`None`
`cond_zip`	`Qubits`	Control qubits register for applying a series of conditional gates with different control-target pairs.	`None`
`cond_reg`	`Qubits`	Deprecated and will be removed in WB 5.0.0. Use cond_zip instead.	`None`

swap ¶

swap(target: Qubits, cond: int = 0, condition_mask: int = 0) -> None

Apply a SWAP operation between this qubits register and another specified target register.

Parameters:

Name	Type	Description	Default
`target`	`Qubits`	The target qubits register to swap states with.	required
`cond`	`int`	Control qubits register. Defaults to None.	`0`
`condition_mask`	`int`	Deprecated and will be removed in WB 5.0.0. Use cond instead.	`0`

Raises:

Type	Description
`ValueError`	If the size of the current register does not match the target register.

peek_probability ¶

peek_probability(value)

Alias for Qubits.peek_read_probability. Deprecated and will be removed in WB 5.0.0. Use Qubits.peek_read_probability instead.

peek_read_probability ¶

peek_read_probability(value: int, stop_at: float = 0.0) -> float

Get the probability that reading this register will return the given value.

This function acts via a non-projective inspection of the statevector and does not change the statevector.

Parameters:

Name	Type	Description	Default
`value`	`int`	The value whose read probability is to be queried.	required
`stop_at`	`float`	If the probability is greater than stop_at, return the value stop_at or greater as quickly as possible (used for zero-checking).	`0.0`

peek_max_value ¶

peek_max_value(probability_threshold: float = 1e-10, flush: bool = True) -> float

Efficiently find the maximum value represented in the state vector with a non-zero probability.

Parameters:

Name	Type	Description	Default
`probability_threshold`	`float`	Consider probabilities below that value to be zero.	`1e-10`
`flush`	`bool`	If True, flush the pipeline before reading the probability. Defaults to True.	`True`

peek_min_value ¶

peek_min_value(probability_threshold=1e-10)

Efficiently find the minumum value represented in the state vector with a non-zero amplitude

Parameters:

Name	Type	Description	Default
`probability_threshold`	`float`	Consider probabilities below that value to be zero.	`1e-10`

postselect ¶

postselect(value: int, target_mask: int | None = None) -> None

Collapse the state to terms with the desired value.

Parameters:

Name	Type	Description	Default
`value`	`int`	Desired "read" value of the register.	required
`target_mask`	`int or None`	If specified, which bits to "read".	`None`

max_value ¶

max_value() -> int

Get the maximum representable value for the qubit register.

This function returns the maximum integer value that can be represented by the qubits in this register.

Returns:

Type	Description
`int`	The maximum value based on the number of qubits.

min_value ¶

min_value() -> int

Get the minimum representable value for the qubit register.

This function returns the minimum integer value that can be represented by the qubits in this register.

Returns:

Type	Description
`int`	The minimum representable value.

step_value ¶

step_value() -> int

Get the step value for iterating over the qubit register values.

This function returns the step size for iterating or incrementing values within the range representable by this qubit register.

Returns:

Type	Description
`int`	The step value.

read_async ¶

read_async(target_mask: int = ~0)

Perform an asynchronous read of the qubit register.

This method starts an asynchronous read operation on the qubits specified by target_mask, allowing other operations to proceed before the read result is available.

Parameters:

Name	Type	Description	Default
`target_mask`	`int`	Mask specifying the qubits to read. Defaults to all qubits.	`~0`

Returns:

Type	Description
`AsyncReadResult`	Placeholder for the asynchronous read result.

read ¶

read(target_mask: int = ~0) -> int

Perform a synchronous read of the classical value from the qubit register.

This method reads a classical binary representation of the current quantum state of the qubit register as an integer value. Only qubits specified by the target_mask are read, with the remainder ignored.

Parameters:

Name	Type	Description	Default
`target_mask`	`int`	Mask to specify which qubits to read. Defaults to all qubits in the register.	`~0`

Returns:

Type	Description
`int`	Integer representation of the qubits' classical state.

write ¶

write(value: int, target_mask: int = ~0) -> None

Write a classical value to the qubit register.

This method writes a specified integer value, represented as a computational basis state, into this register.

Parameters:

Name	Type	Description	Default
`value`	`int`	The integer value to write to the qubits.	required
`target_mask`	`int`	Mask specifying which qubits to write to. Defaults to all qubits.	`~0`

add ¶

add(rhs, cond=0, subtract_condition=False, qubrick_type=None, condition_mask=0)

Perform addition on the qubit register with optional conditional control and custom Qubrick type.

Deprecated and will be removed in WB 5.0.0. Use -= or adder Qubricks instead.

This method adds the value represented by rhs to the current qubit register, optionally controlled by a condition mask, and with an option to use a custom Qubrick type for the addition operation.

Parameters:

Name	Type	Description	Default
`rhs`	`Qubits \| int`	The value to be added to the register. If `rhs` is a `Qubits` object, it represents a quantum value; if `rhs` is an int, it represents a classical integer value.	required
`cond`	`int`	Optional control mask specifying which qubits to use as conditions for the operation. Defaults to 0, meaning no control conditions.	`0`
`subtract_condition`	`bool`	If `True`, the operation performs subtraction instead of addition. Defaults to `False`.	`False`
`qubrick_type`	`class or None`	Specifies a custom Qubrick type to perform the addition operation. Defaults to `None`, which uses the adder specified by QPU for "+=" operator.	`None`
`condition_mask`	`int`	Deprecated and will be removed in WB 5.0.0. Use cond instead.	`0`

Example

qreg.add(3)  # Adds 3 to the quantum register.
qreg.add(other_qreg, cond=0b101)  # Adds another register to `qreg` conditionally.

subtract ¶

subtract(rhs, cond=0, qubrick_type=None, condition_mask=0)

Perform subtraction on the qubit register with optional conditional control and custom Qubrick type.

Deprecated and will be removed in WB 5.0.0. Use -= or adder Qubricks instead.

This method subtracts the value represented by rhs from the current qubit register, optionally controlled by a condition mask, and with an option to use a custom Qubrick type for the subtraction operation.

Parameters:

Name	Type	Description	Default
`rhs`	`Qubits \| int`	The value to be subtracted from the register. If `rhs` is a `Qubits` object, it represents a quantum value; if `rhs` is an int, it represents a classical integer value.	required
`cond`	`int`	Optional control mask specifying which qubits to use as conditions for the operation. Defaults to 0, meaning no control conditions.	`0`
`qubrick_type`	`class or None`	Specifies a custom Qubrick type to perform the subtraction operation. Defaults to `None`, which uses the adder specified by QPU for "-=" operator.	`None`
`condition_mask`	`int`	Deprecated and will be removed in WB 5.0.0. Use cond instead.	`0`

Example

qreg.subtract(2)  # Subtracts 2 from the quantum register.
qreg.subtract(other_qreg, cond=0b100)  # Conditionally subtracts another register from `qreg`.

add_squared ¶

add_squared(rhs, cond=0, reverse_to_subtract=False, condition_mask=0)

Add the square of a specified value to the qubit register with optional control conditions.

Deprecated and will be removed in WB 5.0.0. Use += and Square Qubricks instead.

This method calculates the square of rhs and then adds (or subtracts, if specified) it to the qubit register. The operation can be controlled by a condition mask, and it supports both quantum values and classical integers as input for rhs.

Parameters:

Name	Type	Description	Default
`rhs`	`Qubits \| int`	The value to square and add to the register. If `rhs` is a `Qubits` object, the square of its quantum value is added; if `rhs` is an int, the square of the integer is added.	required
`cond`	`int`	Optional control mask specifying which qubits to use as conditions for the operation. Defaults to 0, meaning no control conditions.	`0`
`reverse_to_subtract`	`bool`	If `True`, the squared value of `rhs` is subtracted from the register. Defaults to `False`.	`False`
`condition_mask`	`int`	Deprecated and will be removed in WB 5.0.0. Use cond instead.	`0`

Example

qreg.add_squared(3)  # Adds 9 (3^2) to the quantum register
qreg.add_squared(other_qreg, cond=0b11)  # Conditional add

addSquared ¶

addSquared(rhs, cond=0, reverse_to_subtract=False, condition_mask=0)

Same as add_squared, provided for backward compatibility. Deprecated and will be removed in WB 5.0.0. Use += and Square Qubricks instead.

ppr ¶

ppr(theta: float | RotationAngle | tuple[int, int], x_mask: int, z_mask: int, cond: int = 0, error_param=0)

Apply a Pauli Product Rotation (PPR) on the qubit register.

The applied unitary operator is as follows:

\[ \text{PPR}(\theta) = \cos(\theta)I - i\sin(\theta) \left(\bigotimes_{j \in \text{x_mask}} X_j \right) \left(\bigotimes_{k \in \text{z_mask}} Z_k \right) \]

Here:

\(\theta\) is the rotation angle in degrees, radians, or fractions of \(\pi\).
\(X_j\) represents a Pauli-X operation on qubit j.
\(Z_k\) represents a Pauli-Z operation on qubit k.

The x_mask and z_mask define the qubits on which the Pauli-X and Pauli-Z operations are applied, respectively.

Parameters:

Name	Type	Description	Default
`theta`	`float \| RotationAngle \| tuple[int, int]`	The rotation angle in degrees (or (theta * units.rad) for radians, or (num,denom) for fraction of pi).	required
`x_mask`	`int`	The bitmask specifying the qubits for Pauli-X operations.	required
`z_mask`	`int`	The bitmask specifying the qubits for Pauli-Z operations.	required
`cond`	`int`	Condition bit(s) for controlled execution. Defaults to 0 (unconditional).	`0`

ppm ¶

ppm(sign: int, x_mask: int, z_mask: int) -> int

Apply a Pauli Product Measurement (PPM) on the qubit register.

The Pauli Product Measurement (PPM) measures the observable associated with the operator:

\[ M = \left(\bigotimes_{j \in \text{x_mask}} X_j \right) \left(\bigotimes_{k \in \text{z_mask}} Z_k \right) \]

Here:

\(X_j\) is the Pauli-X operator acting on qubit j.
\(Z_k\) is the Pauli-Z operator acting on qubit k.

Parameters:

Name	Type	Description	Default
`sign`	`int`	The sign of the operator measured. If `-1`, the eigenvalue measurement result is flipped.	required
`x_mask`	`int`	Mask for Pauli-X on specific qubits.	required
`z_mask`	`int`	Mask for Pauli-Z on specific qubits.	required

Returns:

Type	Description
`int`	The result of the Pauli product measurement: either `0` (for +1 eigenvalue) or `1` (for -1 eigenvalue).

peek_ppm_probability ¶

peek_ppm_probability(x_mask, z_mask, flush=True)

Peek at the probability result of a Pauli Product Measurement (PPM) for specified qubits.

This function computes the probability of a given PPM without collapsing the state, allowing you to inspect the likelihood of the specified measurement outcome. It works in a non-destructive manner, suitable only for simulation environments.

Parameters:

Name	Type	Description	Default
`x_mask`	`int or list`	Mask to specify qubits for X-basis measurements. This can be a bitfield, list of qubit indices, or another suitable format.	required
`z_mask`	`int or list`	Mask to specify qubits for Z-basis measurements. This can be a bitfield, list of qubit indices, or another suitable format.	required
`flush`	`bool`	If True, flushes the pipeline before reading the probabilities. Defaults to True.	`True`

Returns:

Type	Description
`float`	The probability of the specified Pauli product measurement returning 0.

ppm_async ¶

ppm_async(sign, x_mask, z_mask)

Perform an asynchronous Pauli Product Measurement (PPM) on specified qubits.

This function initiates a PPM and returns a placeholder for the result, allowing other operations to proceed without waiting for the measurement outcome. The PPM checks a specified Pauli product outcome over the specified qubits.

Parameters:

Name	Type	Description	Default
`sign`	`int`	The expected outcome sign of the measurement (+1 or -1).	required
`x_mask`	`int or list`	Mask to specify qubits for X-basis measurements. This can be a bitfield, list of qubit indices, or another suitable format.	required
`z_mask`	`int or list`	Mask to specify qubits for Z-basis measurements. This can be a bitfield, list of qubit indices, or another suitable format.	required

Returns:

Type	Description
`AsyncReadResult`	Placeholder for the result of the asynchronous PPM operation.

print_state_vector ¶

print_state_vector(line=-1, min_value_to_print=1e-10, max_num_values=1000, show_entangled=True, with_qreg_types=True, flush=True)

Print the state vector of the qubit register.

This function displays the state vector of the qubits, filtering out entries based on the minimum amplitude threshold (min_value_to_print) and limiting the number of entries displayed (max_num_values). This method is primarily for debugging and analysis, and it is only supported in simulation.

Parameters:

Name	Type	Description	Default
`line`	`int`	Deprecated and will be removed in WB 5.0.0. To get probability of a single basis state, use peek_read_probability instead.	`-1`
`min_value_to_print`	`float`	Minimum amplitude magnitude to display. States with amplitudes below this threshold are not shown. Defaults to 1e-10.	`1e-10`
`max_num_values`	`int`	Maximum number of states to display. Defaults to 1000.	`1000`
`show_entangled`	`bool`	Whether to show qubits that are not included in the register, but are entangled with the register, in the state vector. Default is True.	`True`
`with_qreg_types`	`bool`	Whether to show the state vector with the actual value of the register type, or only as an integer value representation, default is True.	`True`
`flush`	`bool`	If True, flushes the pipeline before reading the state vector. Defaults to True.	`True`

print_probabilities ¶

print_probabilities(line=-1, min_value_to_print=1e-10, max_num_values=1000, show_entangled=True, with_qreg_types=True, flush=True)

Print the probabilities of each of the basis states in the state vector of the qubit register.

This function displays the probabilities of each of the basis states in the state vector of the qubit register, filtering out entries based on the minimum amplitude threshold (min_value_to_print) and limiting the number of entries displayed (max_num_values). This method is primarily for debugging and analysis, and it is only supported in simulation.

Parameters:

Name	Type	Description	Default
`line`	`int`	Deprecated and will be removed in WB 5.0.0. To get probability of a single basis state, use peek_read_probability instead.	`-1`
`min_value_to_print`	`float`	Minimum amplitude magnitude to display. States with amplitudes below this threshold are not shown. Defaults to 1e-10.	`1e-10`
`max_num_values`	`int`	Maximum number of states to display. Defaults to 1000.	`1000`
`show_entangled`	`bool`	Whether to show qubits that are not included in the register, but are entangled with the register, in the probabilities of the basis states. Default is True.	`True`
`with_qreg_types`	`bool`	Whether to show the state vector with the actual value of the register type, or only as an integer value representation, default is True.	`True`
`flush`	`bool`	If True, flushes the pipeline before reading the state vector. Defaults to True.	`True`

QUInt Class¶

psiqworkbench.QUInt ¶

QUInt(num_qubits=None, name=None, qpu=None)

Bases: Qubits

Represents an unsigned integer stored in a quantum register.

The QUInt class configures a quantum register to store non-negative integers using a specified number of qubits. Each qubit corresponds to a binary bit in the unsigned integer representation.

\[ b_{n-1} \cdots b_2 b_1 b_0 = b_{n-1} \cdot 2^{n-1} + b_{n-2} \cdot 2^{n-2} + \cdots + b_1 \cdot 2^1 + b_0 \cdot 2^0 \]

Here:

\(b_{n-1}\) is the most significant bit (MSB).
\(b_0\) is the least significant bit (LSB).

Features:

Unsigned Representation: All values are treated as non-negative integers.
Bit Masking: Supports bitwise masking for more flexible control over quantum operations.
Value Range:
Max Value: \(2^{n} - 1\), where \(n\) is the number of qubits.
Min Value: 0.

Attributes:

Name	Type	Description
`num_qubits`	`int`	Number of qubits in the register.
`name`	`str`	Human-readable identifier for the register.
`qpu`	`QPU`	The quantum processor instance where this register resides.

Example

from psiqworkbench import QPU, QUInt

qc = QPU(num_qubits=4)

# Initialize a 4-qubit unsigned integer register
uint_reg = QUInt(4, name="uint_4", qpu=qc)
uint_reg.write(7)            # Stores the value 7
print(uint_reg.read())       # Output: 7

# Check max and min values for a 4-bit unsigned integer
print(uint_reg.max_value())  # Output: 15
print(uint_reg.min_value())  # Output: 0

# Example of bitwise operations
masked_value = uint_reg.mask(0b1010)  # Apply a bit mask
print(masked_value)  # Output will depend on the current state of the register

Notes

The value range for a QUInt register is determined by the number of qubits: \([0, 2^n - 1]\).
Use the mask method for bitwise operations such as ANDing specific bits.

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Number of qubits allocated to the register.	`None`
`name`	`str`	Identifier name for the register.	`None`
`qpu`	`QPU`	The quantum processing unit to allocate the register on.	`None`

QInt Class¶

psiqworkbench.QInt ¶

QInt(num_qubits=None, name=None, qpu=None)

Bases: Qubits

Represents a signed integer stored in a quantum register.

The QInt class provides a quantum register configured to store signed integers, using the specified number of qubits. The most significant bit (MSB) acts as the sign bit, following the two's complement convention for signed integer representation.

\[ b_{n-1} \cdots b_2 b_1 b_0 = - b_{n-1} \cdot 2^{n-1} + b_{n-2} \cdot 2^{n-2} + \cdots + b_1 \cdot 2^1 + b_0 \cdot 2^0 \]

Here:

\(b_{n-1}\) is the most significant bit (MSB), representing the sign.
\(b_0\) is the least significant bit (LSB).

Features:

Two's Complement Representation: Enables representation of both positive and negative values.
Value Range:
Max Value: \(2^{n-1} - 1\), where \(n\) is the number of qubits.
Min Value: \(-2^{n-1}\).

Attributes:

Name	Type	Description
`num_qubits`	`int`	Number of qubits in the register.
`name`	`str`	Human-readable identifier for the register.
`qpu`	`QPU`	The quantum processor instance where this register resides.

Example

from psiqworkbench import QPU, QInt

qc = QPU(num_qubits=3)

# Initialize a 3-qubit signed integer register
int_reg = QInt(3, name="int_3", qpu=qc)
int_reg.write(-2)           # Stores the value -2
print(int_reg.read())       # Output: -2

# Check maximum and minimum values for a 3-bit signed integer
print(int_reg.max_value())  # Output: 3
print(int_reg.min_value())  # Output: -4

Note

The most significant bit (MSB) serves as the sign bit:

0 indicates positive numbers.
1 indicates negative numbers.

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Number of qubits allocated to the register.	`None`
`name`	`str`	Identifier name for the register.	`None`
`qpu`	`QPU`	The quantum processing unit to allocate the register on.	`None`

max_value ¶

max_value() -> int

Calculates the maximum representable value for the current number of qubits.

Returns:

Type	Description
`int`	The maximum value representable by the register.

min_value ¶

min_value() -> int

Calculates the minimum representable value for the current number of qubits.

Returns:

Type	Description
`int`	The minimum value representable by the register.

read ¶

read(target_mask=~0) -> int

Reads the current value stored in the register, converting from signed integer format.

Parameters:

Name	Type	Description	Default
`target_mask`	`int`	Mask to specify which qubits to read. Defaults to all qubits.	`~0`

Returns:

Type	Description
`int`	The signed integer value stored in the register.

addSquared ¶

addSquared(rhs, cond=0, reverse_to_subtract=False, condition_mask=0)

Adds the square of the given register rhs to the current register.

Deprecated and will be removed in WB 5.0.0. Use += and Square Qubricks instead.

Parameters:

Name	Type	Description	Default
`rhs`	`QInt`	The register to square and add.	required
`cond`	`int`	Mask specifying the control qubits.	`0`
`reverse_to_subtract`	`bool`	If True, subtracts the square of `rhs` instead of adding.	`False`
`condition_mask`	`int`	Deprecated and will be removed in WB 5.0.0. Use cond instead.	`0`

QUFixed Class¶

psiqworkbench.QUFixed ¶

QUFixed(num_qubits=None, radix=None, name=None, qpu=None)

Bases: Qubits

Represents an unsigned fixed-point number stored in a quantum register.

This class allows for the representation of non-integer values in a quantum register by specifying a radix, which determines the boundary between the integer and fractional parts of the fixed-point representation.

An unsigned fixed-point number with a radix \(r\) is given by:

\[ b_{n-1}b_{n-2} \cdots b_2b_1b_0 = b_{n-1} \cdot 2^{n-1-r} + b_{n-2} \cdot 2^{n-2-r} + \cdots + b_1 \cdot 2^{1-r} + b_0 \cdot 2^{-r} \]

Here:

\(b_{n-1}\) is the most significant bit (MSB).
\(b_0\) is the least significant bit (LSB).
The radix determines how many bits are allocated to the fractional part.

Features:

Radix: Controls the boundary between the integer and fractional parts:
- A radix of 0 means all qubits are used for the integer part.
- Higher values of radix dedicate qubits to fractional precision.
Value Range: The maximum and minimum values depend on num_qubits and radix.

Attributes:

Name	Type	Description
`num_qubits`	`int`	Number of qubits to allocate for the register.
`radix`	`int`	Specifies the number of qubits used for the fractional part.
`name`	`str`	Identifier name for the register.
`qpu`	`QPU`	QPU to allocate the register on.

Example

from psiqworkbench import QPU, QUFixed

qc = QPU(num_qubits=4)

# Example with radix = 2
ufixed_reg = QUFixed(4, radix=2, name="ufixed_2", qpu=qc)
ufixed_reg.write(2.75)         # Stores the value 2.75
print(ufixed_reg.read())       # Output: 2.75

# Check max and min values
print(ufixed_reg.max_value())  # Output: 3.75
print(ufixed_reg.min_value())  # Output: 0.0

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Total number of qubits allocated to the register.	`None`
`radix`	`int`	Number of qubits used to represent the fractional part.	`None`
`name`	`str`	Identifier name for the register.	`None`
`qpu`	`QPU`	The quantum processing unit to allocate the register on.	`None`

Raises:

Type	Description
`ValueError`	If the radix is not provided or is invalid (negative or exceeding qubit count).

max_value ¶

max_value() -> float

Calculates the maximum representable value for the current number of qubits and radix.

Returns:

Type	Description
`float`	The maximum value representable by the register.

min_value ¶

min_value() -> float

Calculates the minimum representable value for the current number of qubits and radix.

Returns:

Type	Description
`float`	The minimum value representable by the register, which is always 0 for unsigned types.

step_value ¶

step_value() -> float

Determines the smallest representable step value in the register.

Returns:

Type	Description
`float`	The step size between two consecutive representable values.

read ¶

read() -> float

Reads the current value stored in the register, converting from fixed-point format.

Returns:

Type	Description
`float`	The value stored in the register, as a fixed-point number.

write ¶

write(value: int | float, warn_on_rounding: bool = False) -> None

Write a classical value into the computational basis.

Parameters:

Name	Type	Description	Default
`value`	`int or float`	The value to write (must be >= 0).	required
`warn_on_rounding`	`bool`	Warn if radix is too small to represent value exactly.	`False`

Note

The value -1 is allowed as a special case, to accommodate the common expression ~0 (all bits on).

Raises:

Type	Description
`UserWarning`	If rounding occurs due to limited radix.

QFixed Class¶

psiqworkbench.QFixed ¶

QFixed(num_qubits=None, radix=None, name=None, qpu=None)

Bases: Qubits

Represents a signed fixed-point number stored in a quantum register.

This class extends the fixed-point representation to include signed values. The most significant bit (MSB) is treated as a sign bit, enabling representation of both positive and negative values. The remaining bits encode the magnitude of the number using a fixed-point representation, where the radix specifies the boundary between the integer and fractional parts.

A signed fixed-point number with a radix \(r\) is given by:

\[ b_{n-1}b_{n-2} \cdots b_1b_0 = -b_{n-1} \cdot 2^{n-1-r} + b_{n-2} \cdot 2^{n-2-r} + \cdots + b_1 \cdot 2^{1-r} + b_0 \cdot 2^{-r} \]

Here:

\(b_{n-1}\) is the most significant bit (MSB), treated as the sign bit.
\(b_0\) is the least significant bit (LSB).
The radix determines the division of bits between integer and fractional parts.

Features:

Signed Representation: The MSB is treated as a sign bit:
- 0 indicates a positive number.
- 1 indicates a negative number.
Radix: Determines the boundary between integer and fractional parts.
Value Range: Depends on num_qubits and radix.

Attributes:

Name	Type	Description
`num_qubits`	`int`	Number of qubits to allocate for the register.
`radix`	`int`	Specifies the number of qubits used for the fractional part.
`name`	`str`	Identifier name for the register.
`qpu`	`QPU`	QPU to allocate the register on.

Example

from psiqworkbench import QPU, QFixed

qc = QPU(num_qubits=4)

# Example with radix = 2
fixed_reg = QFixed(4, radix=2, name="fixed_2", qpu=qc)
fixed_reg.write(-1.25)        # Stores the value -1.25
print(fixed_reg.read())       # Output: -1.25

# Check max and min values
print(fixed_reg.max_value())  # Output: 1.75
print(fixed_reg.min_value())  # Output: -2.0

Note

Signed fixed-point numbers are useful for representing positive and negative non-integer values without the overhead of floating-point representations.

Parameters:

Name	Type	Description	Default
`num_qubits`	`int`	Total number of qubits allocated to the register.	`None`
`radix`	`int`	Number of qubits used to represent the fractional part.	`None`
`name`	`str`	Identifier name for the register.	`None`
`qpu`	`QPU`	The quantum processing unit to allocate the register on.	`None`

Raises:

Type	Description
`ValueError`	If the radix is not provided.

max_value ¶

max_value() -> float

Calculates the maximum representable value for the current number of qubits and radix.

Returns:

Type	Description
`float`	The maximum value representable by the register.

min_value ¶

min_value() -> float

Calculates the minimum representable value for the current number of qubits and radix.

Returns:

Type	Description
`float`	The minimum value representable by the register.

step_value ¶

step_value() -> float

Determines the smallest representable step value in the register.

Returns:

Type	Description
`float`	The step size between two consecutive representable values.

read ¶

read() -> float

Reads the current value stored in the register, converting from fixed-point format.

Returns:

Type	Description
`float`	The value stored in the register, as a fixed-point number.

write ¶

write(value: int | float, warn_on_rounding: bool = False)

Writes a classical value to the qubits register, applying fixed-point conversion.

Parameters:

Name	Type	Description	Default
`value`	`int or float`	The value to write into the qubit register.	required
`warn_on_rounding`	`bool`	Warns if the radix is too small for exact representation. Defaults to False.	`False`

Raises:

Type	Description
`UserWarning`	If rounding occurs due to limited radix.

CompositeRegister Class¶

psiqworkbench.CompositeRegister `dataclass` ¶

CompositeRegister()

Bases: Qubits, ABC

Base class for handling registers consisting of a fixed set of named Qubits objects.

CompositeRegister is a flexible way to group multiple quantum registers into a composite structure. Each component of the CompositeRegister is accessed by its defined name. This makes it ideal for application-specific designs where different sub-registers represent distinct aspects of a problem.

Key Features:

Acts like a dictionary for its constituent registers, which can be accessed by name.
Supports custom initialization via the initialize method, tailored to specific problem domains.
Prevents slicing to ensure that the intended structure is preserved.

Defining a CompositeRegister

Users need to subclass CompositeRegister, define the component registers as fields, and implement the initialize method that allocates the required registers. For example:

@dataclass(eq=False)
class MyCompositeRegister(CompositeRegister):
    qbts1: Qubits
    qbts2: Qubits
    qbts3: Qubits
    name: str

    @classmethod
    def initialize(cls, qc, name, param_1, param_2):
        qbts1 = Qubits(int(np.ceil(np.log2(param_1))), "qbts1", qc)
        qbts2 = Qubits(int(np.ceil(np.log2(param_2))), "qbts2", qc)
        qbts3 = Qubits(int(param_1 + param_2), "qbts3", qc)
        return cls(qbts1, qbts2, qbts3, name)

Optional Registers

Composite registers can include optional sub-registers, which may be initialized later:

@dataclass(eq=False)
class MyCompositeRegister(CompositeRegister):
    a: Qubits
    b: Qubits
    c: Optional[Qubits] = None

    @classmethod
    def initialize(cls, qc, name, num_a, num_b):
        a = Qubits(num_a, "a", qc)
        b = Qubits(num_b, "b", qc)
        return cls(a, b, name=name)

Example of using the optional register:

comp_reg = MyCompositeRegister.initialize(qc, "example", param_1, param_2)
comp_reg.c = Qubits(param_3, "c", qc)

Example Usage

CompositeRegisters behave like dictionaries, where sub-registers are accessed by their names:

qc = QPU()
qc.reset(9)

my_register = MyCompositeRegister.initialize(qc, "example", 3, 2)

# Access the whole register
my_register.x()
my_register.qbts1.x()
my_register.qbts1.y(ctrl)

For more details, see Quantum Arithmetic Data Types tutorial.

release ¶

release(clear_to_zero=False)

Releases every psiqworkbench.Qubits object in the composite register.

initialize `abstractmethod` `classmethod` ¶

initialize(qc, *args, **kwargs)

Method to construct a CompositeRegister instance.

You need to implement this method when defining your subclass to be able to use it!

VectorRegister Class¶

psiqworkbench.qubits.base_qubits.VectorRegister ¶

VectorRegister(name: str, registers: Sequence[T], owns_alloc: bool = False)

Bases: Generic[T, TQPU], BaseQubits[TQPU]

Base class for handling an array of qubits registers.

A VectorRegister simplifies implementation of an array-like structure of quantum registers. Each element of the vector is a qubit register, and the vector supports operations like arithmetic and slicing.

Note

Do not instantiate VectorRegister class directly! Use vector_register method instead. For more details, see Quantum Arithmetic Data Types tutorial.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the vector register.	required
`registers`	`Sequence[T]`	List of qubit registers.	required

num_qubits `property` ¶

num_qubits

Total number of qubits in the vector.

composite_reg `property` ¶

composite_reg: T

A single register containing all the registers in the vector.

write ¶

write(value: int | float | list | ndarray, target_mask: int | list[int] = ~0)

Write values into the vector register.

This method writes classical values into the computational basis of each element in the vector register. It can either write a single value across all registers or different values to each register in the vector.

Parameters:

Name	Type	Description	Default
`value`	`int \| float \| list \| ndarray`	The value to write. If an integer or float, applies the value to all registers in the vector. If a list or array, each entry is written to a corresponding register.	required
`target_mask`	`int or list[int]`	The mask(s) to apply for each write. If an integer, applies the same mask to all registers. If a list, each entry specifies a mask for a corresponding register.	`~0`

Raises:

Type	Description
`ValueError`	If `value` is a list but its length does not match the vector length.

release ¶

release()

Release all the qubits in the vector.

Reference: Qubits Classes¶

Contents¶

Qubits Class¶

psiqworkbench.Qubits ¶

identifier property ¶

x ¶

cnot ¶

lelbow ¶

relbow ¶

y ¶

z ¶

identity ¶

s ¶

t ¶

s_inv ¶

t_inv ¶

reflect ¶

QFT ¶

rx ¶

ry ¶

rz ¶

phase ¶

cphase ¶

had ¶

rootx ¶

rootx_inv ¶

rooty ¶

rooty_inv ¶

check_value_fits_in_type ¶

coerce_value ¶

qubit_indices ¶

pull_state ¶

is_allocated ¶

allocate ¶

release ¶

set_random ¶

push_state ¶

nop ¶

mask ¶

box ¶

box_open ¶

box_close ¶

swap ¶

peek_probability ¶

peek_read_probability ¶

peek_max_value ¶

peek_min_value ¶

postselect ¶

max_value ¶

min_value ¶

step_value ¶

read_async ¶

read ¶

write ¶

add ¶

subtract ¶

add_squared ¶

addSquared ¶

ppr ¶

ppm ¶

peek_ppm_probability ¶

ppm_async ¶

print_state_vector ¶

print_probabilities ¶

QUInt Class¶

psiqworkbench.QUInt ¶

QInt Class¶

psiqworkbench.QInt ¶

max_value ¶

min_value ¶

read ¶

addSquared ¶

QUFixed Class¶

psiqworkbench.QUFixed ¶

max_value ¶

min_value ¶

step_value ¶

read ¶

write ¶

QFixed Class¶

identifier `property` ¶

psiqworkbench.CompositeRegister `dataclass` ¶

initialize `abstractmethod` `classmethod` ¶

num_qubits `property` ¶

composite_reg `property` ¶