guppyalgos.primitives.rotations

init file for rotations package.

Functions

comparator_based_rz_cascade(epsilon)

Build a comparator-based Rz using the cascade comparator.

dummy_theta_resource_state(q, theta)

Prepare |0> + exp(-i * theta)|1> using Rz and H gates.

givens_rotation(q0, q1, theta)

Apply the configured two-mode Givens rotation.

givens_with_custom_rz(rz_method)

Build a two-mode Givens rotation with a supplied RZ implementation.

n_comparator_based_rz_cascade_ancillas(epsilon)

Return total RUS and cascade-comparator ancillas for epsilon.

n_constant_comparator_cascade_ancillas(n)

Return the workspace qubits required by the cascade comparator.

qrom_identity(index_regs, target_regs)

Leave QROM index and target registers unchanged.

repeat_until_success_rz(theta_state_method)

Repeat-until-success Rz rotation on qubit q by angle theta using ancilla qubits.

Classes

ComparatorBasedRz()

Apply an approximate $R_z$ rotation using comparator-based RUS.

ConstantComparator()

A constant comparison acting on RUS and workspace registers.

ConstantComparatorCascade()

Constant comparator configured with its AND operations and direction.

GivensCascadePhaseGradient()

Apply a sequence of positive phase-gradient Givens rotations.

GivensRotationPhaseGradient()

Build a positive two-target Givens rotation by phase kickback.

GivensRotationRegisterIncremented()

Build a positive two-target Givens rotation from data-register bits.

QROMRotations()

Composable QROM rotation gadget.

RotationAxis()

Guppy object providing basis changes for a single-qubit rotation axis.

RotationAxisX()

Guppy axis object realizing Rx through an Rz basis change.

RotationAxisY()

Guppy axis object realizing Ry through an Rz basis change.

RotationAxisZ()

Guppy axis object leaving the underlying Rz rotation unchanged.

RotationPhaseGradient()

Build positive phase-gradient rotations via a controlled Gidney adder.

RotationRegisterIncremented()

Build a positive register-controlled rotation from data-register bits.

Rotator()

Operation that turns a loaded QROM word into a target rotation.
class guppyalgos.primitives.rotations.ComparatorBasedRz

Apply an approximate \(R_z\) rotation using comparator-based RUS.

Implements Algorithm 1 from arXiv:2404.05618, “Single-qubit rotation algorithm with logarithmic Toffoli count and gate depth”. The algorithm uses a repeat-until-success approach to approximate \(R_z(\theta)\) within error \(\varepsilon\). Its success probability is greater than \(1/2\).

Algorithm:

  1. Compute \(n = 1 + \lceil \log_2(1/\varepsilon) \rceil\) and \(k = 2^{n-1} + \lfloor 2^{n-1} \tan(\theta/2) + 1/2 \rfloor\).

  2. Prepare register \(a\) in superposition \(|+\rangle^{\otimes n}\).

  3. Perform the comparison \(a \geq k\) on the target qubit.

  4. Apply an \(S\) gate to the target qubit.

  5. Apply the inverse comparison to the target qubit.

  6. Measure register \(a\): if all results are zero, succeed; otherwise apply \(Z\) and retry.

This struct is generic over the comparator method: any concrete type that implements the ConstantComparator protocol can be used. The comparator owns the details of the constant comparison, while n_ancillas captures the workspace required by that implementation. The ConstantComparatorCascade implementation is the concrete cascade example from the paper and realizes the comparison with Clifford+Toffoli operations.

Variables:

  • comparator – Configured forward constant comparator.

  • inverse_comparator – Configured inverse constant comparator.

comparator: TypeVar(ComparatorType, ConstantComparator[TypeVar(n, bound= nat), TypeVar(n_ancillas, bound= nat)], Drop)
compose(target, theta)

Apply an approximate Rz rotation to target.

inverse_comparator: TypeVar(ComparatorType, ConstantComparator[TypeVar(n, bound= nat), TypeVar(n_ancillas, bound= nat)], Drop)
class guppyalgos.primitives.rotations.ConstantComparator

A constant comparison acting on RUS and workspace registers.

Type parameters:

n: Number of qubits in the input register being compared. n_ancillas: Number of workspace qubits required by the comparator.

compose(a, b, target, k)

Compare the input register against the classical constant k.

Parameters:

  • a – The n-qubit input register interpreted as an integer.

  • b – The n_ancillas-qubit workspace register used by the comparator implementation.

  • target – Qubit on which to accumulate the comparison result.

  • k – Classical integer against which a is compared.

class guppyalgos.primitives.rotations.ConstantComparatorCascade

Constant comparator configured with its AND operations and direction.

comp_and_op: Callable[[qubit, qubit, qubit], None]
compose(a, b, target, k)

Compare a against k.

dagger: bool
uncomp_and_op: Callable[[qubit, qubit, qubit], None]
class guppyalgos.primitives.rotations.GivensCascadePhaseGradient

Apply a sequence of positive phase-gradient Givens rotations.

Each little-endian register data_qregs[i] encodes an integer x_i and applies a Givens rotation with half-turn parameter theta_i = 2 * x_i / 2**n_data_q to target modes i and i + 1. The rotations are applied in increasing mode order.

The phase-gradient register is supplied as part of rotation_regs. It is borrowed and preserved, allowing one externally prepared resource to be reused by this cascade and a later inverse cascade.

compose(data_qregs, rotation_regs)

Apply the loaded nearest-neighbor Givens cascade.

Parameters:

  • data_qregs – Little-endian angle registers, one for each neighboring target pair in the cascade.

  • rotation_regs – Rotation targets and externally prepared phase-gradient resource. data_qregs[i] rotates target modes i and i + 1.

daggered(data_qregs, rotation_regs)

Undo the loaded nearest-neighbor Givens cascade.

Parameters:

  • data_qregs – Little-endian angle registers, one for each neighboring target pair in the forward cascade.

  • rotation_regs – Rotation targets and externally prepared phase-gradient resource. data_qregs[i] inversely rotates target modes i and i + 1.

phase_gradient: array[qubit, TypeVar(n_data_q, bound= nat)]
class guppyalgos.primitives.rotations.GivensRotationPhaseGradient

Build a positive two-target Givens rotation by phase kickback.

The little-endian data register encodes the integer x = sum_j 2**j * data_qreg[j] and the half-turn parameter theta = 2 * x / 2**n_data_q. The rotator diagonalizes the two-qubit Givens rotation with an XX basis change, uses controlled Gidney addition to kick back the encoded angle, and then restores the original basis.

phase_gradient must be prepared externally in the standard little-endian phase-gradient state, for example with guppyalgos.primitives.state_preparation.phase_gradient.phase_gradient() using Convention.Standard. The kickback circuit preserves it, so one rotator can be reused for multiple target pairs. The caller remains responsible for discarding the resource register after its final use.

Parameters:

phase_gradient – Externally prepared standard little-endian phase-gradient register. The rotator owns and preserves this register.

compose(data_qreg, rotation_regs)

Apply the phase-gradient Givens rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register encoding the integer rotation value x. It has the same width as phase_gradient.

  • rotation_regs – Pair of target qubits receiving the Givens rotation with half-turn parameter 2 * x / 2**n_data_q.

daggered(data_qreg, rotation_regs)

Undo the phase-gradient Givens rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register encoding the integer rotation value x. It has the same width as phase_gradient.

  • rotation_regs – Pair of target qubits receiving the inverse Givens rotation with half-turn parameter -2 * x / 2**n_data_q.

phase_gradient: array[qubit, TypeVar(n_data_q, bound= nat)]
class guppyalgos.primitives.rotations.GivensRotationRegisterIncremented

Build a positive two-target Givens rotation from data-register bits.

The little-endian data register encodes the integer x = sum_j 2**j * data_qreg[j] and the half-turn parameter theta = 2 * x / 2**n_data_q, matching RotationRegisterIncremented. The rotator diagonalizes the two-qubit Givens rotation with an XX basis change, applies opposite-sign register-controlled Z rotations, and then restores the original basis. It has no private quantum resource and applies no scaling factor.

compose(data_qreg, rotation_regs)

Apply the register-incremented Givens rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register whose bits control the fixed-point Givens-angle increments.

  • rotation_regs – Pair of target qubits receiving the Givens rotation.

daggered(data_qreg, rotation_regs)

Report that the inverse register-incremented rotation is unavailable.

class guppyalgos.primitives.rotations.QROMRotations

Composable QROM rotation gadget.

A QROM rotation takes a set of rotation parameters indexed on an index register, stored in one or more QROM target registers, applies a rotation controlled on those rotation increments in superposition, and then uncomputes the target registers.

The struct factors an indexed rotation into three pieces:

  1. a QROM compute callable that maps (index_qreg, data_qreg) to the selected target data,

  2. a rotator object that applies the loaded word to its target registers, and

  3. a matching QROM uncompute callable that restores data_qreg after the rotation has been applied.

IndexRegs describes the QROM index-register shape, while TargetRegs describes the QROM-loaded register shape. Future QROM implementations may use structs containing multiple index or target registers. Current implementations bind each to one array[qubit, n]. RotationRegs similarly describes the register shape receiving the rotation; current implementations use a single qubit for single-qubit rotations or tuple[qubit, qubit] for Givens rotation variants.

Supported rotation cases:

Register-incremented rotators have no stored quantum resource. Phase-gradient rotators instead own an externally prepared phase-gradient register, which remains reusable across calls to compose().

Parameters:

  • qrom_compute – Callable that loads the indexed rotation data into the QROM target registers.

  • rotation_box – Rotator struct that converts the loaded data into the requested target rotation.

  • qrom_uncompute – Callable that restores the QROM target registers after the rotation.

compose(index_qreg, data_qreg, rotation_regs)

Apply QROM compute, rotation, and QROM uncompute.

Parameters:

  • index_qreg – The QROM index register or register bundle.

  • data_qreg – The QROM target register or register bundle.

  • rotation_regs – Target register shape expected by the chosen rotator.

daggered(index_qreg, data_qreg, rotation_regs)

Apply the inverse QROM rotation in reverse operation order.

Parameters:

  • index_qreg – The QROM index register or register bundle.

  • data_qreg – The QROM target register or register bundle.

  • rotation_regs – Target register shape expected by the chosen rotator.

qrom_compute: Callable[[TypeVar(IndexRegs), TypeVar(TargetRegs)], None]
qrom_uncompute: Callable[[TypeVar(IndexRegs), TypeVar(TargetRegs)], None]
rotation_box: TypeVar(RotBox, bound= Rotator[TypeVar(TargetRegs), TypeVar(RotationRegs)])
class guppyalgos.primitives.rotations.RotationAxis

Guppy object providing basis changes for a single-qubit rotation axis.

prepare_basis(target_q)

Change basis before applying the underlying Rz rotation.

Return type:

None

restore_basis(target_q)

Undo the basis change after applying the underlying Rz rotation.

Return type:

None

class guppyalgos.primitives.rotations.RotationAxisX

Guppy axis object realizing Rx through an Rz basis change.

prepare_basis(target_q)

Rotate the target from the Z basis into the X basis.

Return type:

None

restore_basis(target_q)

Return the target from the X basis to the Z basis.

Return type:

None

class guppyalgos.primitives.rotations.RotationAxisY

Guppy axis object realizing Ry through an Rz basis change.

prepare_basis(target_q)

Rotate the target from the Z basis into the Y basis.

Return type:

None

restore_basis(target_q)

Return the target from the Y basis to the Z basis.

Return type:

None

class guppyalgos.primitives.rotations.RotationAxisZ

Guppy axis object leaving the underlying Rz rotation unchanged.

prepare_basis(target_q)

Leave the target in the Z basis.

Return type:

None

restore_basis(target_q)

Leave the target in the Z basis.

Return type:

None

class guppyalgos.primitives.rotations.RotationPhaseGradient

Build positive phase-gradient rotations via a controlled Gidney adder.

The rotator uses the default positive convention: it conjugates the controlled adder by X gates on rotation_target so the binary value stored in data_qreg is added into the phase-gradient register on the target’s original |0> branch. Since the phase-gradient register is a Fourier eigenstate of addition, this branch-selective addition kicks back as a positive Rz phase on rotation_target up to a global phase.

Writing the standard little-endian integer encoded by data_qreg as

\[x = \sum_{j=0}^{d-1} 2^j x_j,\]

and the d-qubit phase-gradient register as

\[|F_d\rangle = \frac{1}{\sqrt{2^d}} \sum_{y=0}^{2^d-1} e^{-2\pi i y / 2^d} |y\rangle,\]

modular addition by x acts diagonally:

\[A_x |F_d\rangle = e^{-2\pi i x / 2^d} |F_d\rangle.\]

With the target-flip convention, the controlled adder maps

\[\frac{|0\rangle + |1\rangle}{\sqrt{2}} \otimes |F_d\rangle \mapsto \frac{e^{-2\pi i x / 2^d}|0\rangle + |1\rangle}{\sqrt{2}} \otimes |F_d\rangle,\]

which is equivalent, up to global phase, to a positive Rz on the target qubit with half-turn parameter theta = 2 * x / 2**d. The sign is positive because the negative addition eigenphase is applied to the original |0> branch rather than the original |1> branch.

The phase-gradient register must already be prepared in the standard little-endian phase-gradient state, for example with guppyalgos.primitives.state_preparation.phase_gradient.phase_gradient() using Convention.Standard. Its qubit ordering then matches the arithmetic convention of cntrl_adder_ripple_gidney_mod. The kickback circuit preserves this resource eigenstate, allowing the same rotator to be applied to multiple target qubits. The caller remains responsible for discarding it after its final use.

Parameters:

  • phase_gradient – Externally prepared standard little-endian phase-gradient register. The rotator owns and preserves this register.

  • axis – Guppy basis-change object that realizes the kicked-back positive rotation around the X, Y, or Z axis.

axis: TypeVar(Axis, bound= RotationAxis)
compose(data_qreg, rotation_target)

Apply the phase-gradient rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register encoding the integer rotation value x. It has the same width as phase_gradient.

  • rotation_target – Qubit receiving the positive axis rotation with half-turn parameter 2 * x / 2**n_data_q.

daggered(data_qreg, rotation_target)

Apply the phase-gradient rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register encoding the integer rotation value x. It has the same width as phase_gradient.

  • rotation_target – Qubit receiving the positive axis rotation with half-turn parameter 2 * x / 2**n_data_q.

phase_gradient: array[qubit, TypeVar(n_data_q, bound= nat)]
class guppyalgos.primitives.rotations.RotationRegisterIncremented

Build a positive register-controlled rotation from data-register bits.

The little-endian data register encodes the integer x = sum_j 2**j * data_qreg[j]. This rotator applies a controlled rotation for each bit, with half-turn angle 2**(j + 1 - n_data_q) for bit j. The resulting total half-turn parameter is therefore theta = 2 * x / 2**n_data_q, matching the positive phase-gradient rotation convention without a scaling factor.

Unlike RotationPhaseGradient, this rotator has no private quantum resource. It applies the unscaled fixed-point angle schedule directly.

Parameters:

axis – Guppy basis-change object that realizes the positive rotation around the X, Y, or Z axis.

axis: TypeVar(Axis, bound= RotationAxis)
compose(data_qreg, rotation_target)

Apply the register-incremented rotation encoded by data_qreg.

Parameters:

  • data_qreg – Little-endian register whose bits control the fixed-point rotation increments.

  • rotation_target – Qubit receiving the resulting positive axis rotation.

daggered(data_qreg, rotation_target)

Report that the inverse register-incremented rotation is unavailable.

class guppyalgos.primitives.rotations.Rotator

Operation that turns a loaded QROM word into a target rotation.

compose(data_qreg, rotation_regs)

Apply a rotation encoded in data_qreg to rotation_regs.

daggered(data_qreg, rotation_regs)

Apply dagger of a rotation encoded in data_qreg to rotation_regs.

guppyalgos.primitives.rotations.comparator_based_rz_cascade(epsilon)

Build a comparator-based Rz using the cascade comparator.

This is a convenience function that constructs a ComparatorBasedRz using the ConstantComparatorCascade implementation. The returned function uses temporary AND compute and uncompute operations.

Parameters:

epsilon (float) – Approximation error bound in operator norm.

Return type:

GuppyFunctionDefinition[(qubit, angle), None]

Returns:

A Guppy function with signature (target: qubit, theta: angle) -> None. The returned function uses temporary AND compute and uncompute operations.

guppyalgos.primitives.rotations.dummy_theta_resource_state(q, theta)

Prepare |0> + exp(-i * theta)|1> using Rz and H gates.

This is a placeholder for a more efficient state preparation method. such as phase gradient addition etc

Parameters:

  • q (qubit) – The qubit to prepare.

  • theta (angle) – The angle for the Rz rotation.

guppyalgos.primitives.rotations.givens_rotation(q0, q1, theta)

Apply the configured two-mode Givens rotation.

Return type:

None

guppyalgos.primitives.rotations.givens_with_custom_rz(rz_method)

Build a two-mode Givens rotation with a supplied RZ implementation.

The returned callable has signature (qubit, qubit, angle) -> None and uses Guppy’s half-turn angle convention.

Return type:

GuppyFunctionDefinition[(qubit, qubit, angle), None]

guppyalgos.primitives.rotations.n_comparator_based_rz_cascade_ancillas(epsilon)

Return total RUS and cascade-comparator ancillas for epsilon.

Return type:

int

guppyalgos.primitives.rotations.n_constant_comparator_cascade_ancillas(n)

Return the workspace qubits required by the cascade comparator.

Return type:

int

guppyalgos.primitives.rotations.qrom_identity(index_regs, target_regs)

Leave QROM index and target registers unchanged.

guppyalgos.primitives.rotations.repeat_until_success_rz(theta_state_method)

Repeat-until-success Rz rotation on qubit q by angle theta using ancilla qubits.

This function applies a repeat-until-success strategy to implement an Rz rotation on the target qubit q by the specified angle theta. It uses an ancilla qubit prepared in a resource state determined by the theta_state_method function. The process is repeated until the measurement of the ancilla qubit indicates success. Ie 2 fauls and 1 success for each attempt Rz(-theta), Rz(-2theta), Rz(4theta) respectively.

This should be used with a theta_state_method that can prepare arbitrary angles much more efficiently than direct Rz rotations synthesis.

Parameters:

theta_state_method (Callable[[qubit, float], None]) – A function that prepares the ancilla qubit in the required resource state for the given angle.

Returns:

A guppy function that performs

the repeat-until-success Rz rotation on the target qubit q by angle theta.

Return type:

GuppyFunctionDefinition[[qubit, float], None]