# Copyright 2026 Xanadu Quantum Technologies Inc.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
r"""
Decomposition rule for RZ in terms of `phase gradient states <https://pennylane.ai/compilation/phase-gradient/b-rotations>`__
"""
from collections import Counter
from functools import partial
import numpy as np
import pennylane as qp
from pennylane.ops.op_math.change_op_basis2 import ChangeOpBasis2
from pennylane.transforms.rz_phase_gradient import _rz_phase_gradient
from pennylane.typing import Bool, Wire
from pennylane.wires import WireError, Wires
def validate_phase_gradient_wires(angle_wires, phase_grad_wires, work_wires):
"""Validate three wire registers to be valid for phase gradient decompositions.
Args:
angle_wires (Wires): wires that encode the binary representation of the rotation angle
phase_grad_wires (Wires): wires that carry a phase gradient state.
work_wires (Wires): work wires for :class:`~.SemiAdder` (and possibly :class:`~.QROM`)
decomposition.
"""
angle_wires = Wires(angle_wires)
phase_grad_wires = Wires(phase_grad_wires)
work_wires = Wires(work_wires)
if len(angle_wires) != len(phase_grad_wires):
raise WireError(
"angle_wires and phase_grad wires must be of same size, but received "
f"{len(angle_wires)} angle_wires and {len(phase_grad_wires)} phase_grad_wires."
)
if len(phase_grad_wires) - 1 > len(work_wires):
raise WireError(
f"work_wires need to be at least of size len(phase_grad_wires) - 1, but received "
f"{len(work_wires)} work_wires and {len(phase_grad_wires)-1=}"
)
return angle_wires, phase_grad_wires, work_wires
# Units of the angles in the phase gradient decomposition of each operator type,
# see ``qp.math.binary_decimals``
_ANGLE_UNITS = {"RZ": 2 * np.pi, "CRZ": 4 * np.pi, "SelectPauliRot": 4 * np.pi}
def _angle_unit(op_type):
"""Unit of the angles in the phase gradient decomposition of ``op_type``, which may be an
operator class or its name."""
name = getattr(op_type, "__name__", op_type)
if name not in _ANGLE_UNITS:
raise ValueError(
f"op_type must be one of {list(_ANGLE_UNITS)} or the corresponding class, but got "
f"{op_type}."
)
return _ANGLE_UNITS[name]
def _required_precision(binary_int):
"""Position of the last set bit across all binary representations in ``binary_int``, with
the precision along the last axis. This is the number of bits required to represent all of
them exactly."""
return qp.math.max(binary_int * qp.math.arange(1, qp.math.shape(binary_int)[-1] + 1))
[docs]
def phase_gradient_precision_stats(angles, precision, op_type):
r"""Compute the ``precision_stats`` argument of the phase gradient decomposition rule
factories from the rotation angles of the operators that a rule will decompose.
A phase gradient decomposition with ``precision`` angle wires represents an angle
:math:`\phi` by the ``precision`` leading binary decimals of :math:`\phi/u` (rounded to
nearest), where the unit is :math:`u=2\pi` for :class:`~.RZ` and :math:`u=4\pi` for
:class:`~.CRZ` and :class:`~.SelectPauliRot`. If the trailing decimals are zero, the rotation
can be realized with fewer bits, i.e., with a smaller :class:`~.SemiAdder` and less data
loading.
This function counts how many operators require each number of bits. Passing the result as
``precision_stats`` to :func:`~.make_rz_to_phase_gradient_decomp`,
:func:`~.make_crz_to_phase_gradient_decomp` or
:func:`~.make_selectpaulirot_to_phase_gradient_decomp` makes the produced rule apply each of
these operators at exactly the number of bits it requires, and hints the conditional
branches with the observed frequencies.
Args:
angles (Sequence[TensorLike]): The angle(s) of each operator. For operators with
multiple angles, such as :class:`~.SelectPauliRot`, the bits required by the operator
are the maximum over all of its angles. The angles must be concrete.
precision (int): The full precision of the decomposition rule, i.e., the number of angle
wires.
op_type (type | str): The type of the operators, i.e., :class:`~.RZ`, :class:`~.CRZ`
or :class:`~.SelectPauliRot`, or its name. It determines the unit of the angles in
the respective decomposition rule.
Returns:
dict[int, int]: The number of operators requiring each number of bits, sorted by the
number of bits.
.. seealso:: :func:`~.make_rz_to_phase_gradient_decomp`,
:func:`~.make_crz_to_phase_gradient_decomp`,
:func:`~.make_selectpaulirot_to_phase_gradient_decomp`
**Example**
Consider four :class:`~.RZ` rotations that we want to decompose with four angle wires. The
first angle, :math:`\tfrac{1}{2}\cdot 2\pi`, has the binary representation :math:`(0.1000)_2`
and thus only requires one bit, whereas :math:`0.1 \cdot 2\pi` is rounded to
:math:`(0.0010)_2`, requiring three bits:
>>> from pennylane.transforms.decompositions import phase_gradient_precision_stats
>>> angles = np.array([1 / 2, 1 / 4, 3 / 8, 0.1]) * 2 * np.pi
>>> phase_gradient_precision_stats(angles, precision=4, op_type=qp.RZ)
{1: 1, 2: 1, 3: 2}
See :func:`~.make_rz_to_phase_gradient_decomp` for an example that uses these statistics
in a decomposition rule.
For :class:`~.SelectPauliRot`, we pass the angles of each operator. The operator type may
also be specified by its name:
>>> ops = [
... qp.SelectPauliRot(np.array([1 / 2, 1 / 4]) * 4 * np.pi, control_wires=[0], target_wire=1),
... qp.SelectPauliRot(np.array([1 / 2, 0]) * 4 * np.pi, control_wires=[0], target_wire=1),
... ]
>>> angles = [op.data[0] for op in ops]
>>> phase_gradient_precision_stats(angles, precision=4, op_type="SelectPauliRot")
{1: 1, 2: 1}
.. note::
A :class:`~.SelectPauliRot` without control wires is decomposed into a plain
:class:`~.RX`, :class:`~.RY` or :class:`~.RZ` rotation by
:func:`~.make_selectpaulirot_to_phase_gradient_decomp`. If the resulting :class:`~.RZ`
rotations are decomposed by a rule from :func:`~.make_rz_to_phase_gradient_decomp`,
include their angles in the statistics for ``op_type=qp.RZ``, which uses the unit
:math:`2\pi` instead of :math:`4\pi`.
"""
unit = _angle_unit(op_type)
required = (
int(_required_precision(qp.math.binary_decimals(a, precision, unit=unit))) for a in angles
)
return dict(sorted(Counter(required).items()))
def _precision_dispatcher(precision_stats, precision, op_type):
"""Validate ``precision_stats`` and create a function that applies a phase gradient circuit
at the smallest precision in ``precision_stats`` that suffices for the given angle(s).
Args:
precision_stats (dict[int, int] | None): number of rotations for each required precision.
Zero counts are ignored. Without non-zero counts, the full ``precision`` is always
applied.
precision (int): full precision, i.e., the number of angle wires.
op_type (type | str): type of the decomposed operators, determining the angle unit.
Returns:
tuple[set[int], Callable]: The precisions that may be applied, including the full
``precision``, and a function ``dispatch(angles, apply_fn)``, where ``apply_fn(p)``
applies the full-precision circuit to the leading ``p`` angle and phase gradient wires.
No conditional is used if the full ``precision`` is the only precision. ``angles`` may
be traced if program capture is enabled.
"""
precision_stats = {p: c for p, c in (precision_stats or {}).items() if c} or {precision: 1}
if any(not 0 <= p <= precision for p in precision_stats):
raise ValueError(
f"precision_stats keys must be between 0 and {precision}, but got "
f"{sorted(precision_stats)}."
)
total = sum(precision_stats.values())
probs = {p: precision_stats[p] / total for p in sorted(precision_stats)}
precisions = {precision, *probs}
unit = _angle_unit(op_type)
def dispatch(angles, apply_fn):
def _branch(p):
if p:
apply_fn(p)
# If only a single precision or no precision_stats was provided, we just call the branch
# function for that single precision, without cond branching.
if precisions == {precision}:
_branch(precision)
return
# The circuit at precision p reproduces the bits of the angles exactly if p >= required,
# because the bits beyond p are zero, so that rounding at precision p yields the same
# bits as rounding at the full precision.
required = _required_precision(qp.math.binary_decimals(angles, precision, unit=unit))
branches = [
(required <= p, qp.hint(partial(_branch, p), {"branch-prob": prob}))
for p, prob in probs.items()
]
# Without full precision in ``precision_stats``, the fallback is unhinted (probability 0)
otherwise = branches.pop()[1] if precision in probs else partial(_branch, precision)
(pred, true_fn), *elifs = branches
qp.cond(pred, true_fn, otherwise, elifs=elifs)()
return precisions, dispatch
[docs]
def make_rz_to_phase_gradient_decomp(
angle_wires, phase_grad_wires, work_wires, precision_stats=None
):
r"""
Create a custom decomposition rule for :class:`~.RZ` gates.
Here, the necessary auxiliary wires for the `phase gradient decomposition of RZ
<https://pennylane.ai/compilation/phase-gradient/b-rotations>`__ are taken as inputs and
bound into the created decomposition rule.
This way, this function can be used in a workflow context that explicitly uses those wires
to generate this decomposition rule, which can then be registered with
:func:`~pennylane.decomposition.add_decomps`.
Parameters:
angle_wires (Wires): wires that encode the binary representation of the rotation angle
phase_grad_wires (Wires): wires that carry a phase gradient state
work_wires (Wires): additional work wires for :class:`~.SemiAdder` decomposition
precision_stats (dict[int, int] | None): Optional statistics of the number of bits
required by the rotation angles, mapping a number of bits to the number of rotations
requiring that many bits. Defaults to ``None``.
Returns:
qp.decomposition.DecompositionRule: decomposition rule to be used within :func:`~.pennylane.decompose`.
.. seealso:: :func:`~.make_selectpaulirot_to_phase_gradient_decomp`,
:func:`~.phase_gradient_precision_stats`
**Example**
In this example we decompose a circuit containing only a single :class:`~.RZ` gate using the custom decomposition rule
that we generate from within the context of the example, where all auxiliary wires exist.
.. code-block:: python
import pennylane as qp
from pennylane.transforms.decompositions import make_rz_to_phase_gradient_decomp
import numpy as np
prec = 3
phi = (1/2 + 1/4 + 1/8) * 2 * np.pi # binary rep is (111)
angle_wires = qp.wires.Wires([f"aux_{i}" for i in range(prec)])
phase_grad_wires = qp.wires.Wires([f"phg_{i}" for i in range(prec)])
work_wires = qp.wires.Wires([f"work_{i}" for i in range(prec - 1)])
custom_decomp = make_rz_to_phase_gradient_decomp(
angle_wires, phase_grad_wires, work_wires
)
gate_set = {"CNOT", "SemiAdder", "GlobalPhase", "PauliX"}
@qp.transforms._tape_decompose(gate_set=gate_set, fixed_decomps={qp.RZ: custom_decomp})
@qp.qnode(qp.device("null.qubit"))
def circuit():
qp.RZ(phi, 0)
return qp.state()
The resulting circuit corresponds to the `phase gradient decomposition <https://pennylane.ai/compilation/phase-gradient/b-rotations>`__ of RZ,
containing two CNOT fanouts corresponding to the binary representation of the angle (111 in this case), the :class:`~SemiAdder`, and a :class:`~GlobalPhase`.
>>> print(qp.draw(circuit)())
0: ─╭GlobalPhase(2.75)─╭●─╭●─╭●────────────╭●─╭●─╭●─┤ ╭State
aux_0: ─├GlobalPhase(2.75)─╰X─│──│──╭SemiAdder─╰X─│──│──┤ ├State
aux_1: ─├GlobalPhase(2.75)────╰X─│──├SemiAdder────╰X─│──┤ ├State
aux_2: ─├GlobalPhase(2.75)───────╰X─├SemiAdder───────╰X─┤ ├State
phg_0: ─├GlobalPhase(2.75)──────────├SemiAdder──────────┤ ├State
phg_1: ─├GlobalPhase(2.75)──────────├SemiAdder──────────┤ ├State
phg_2: ─├GlobalPhase(2.75)──────────├SemiAdder──────────┤ ├State
work_0: ─├GlobalPhase(2.75)──────────├SemiAdder──────────┤ ├State
work_1: ─╰GlobalPhase(2.75)──────────╰SemiAdder──────────┤ ╰State
.. details::
:title: Usage details
**Adaptive precision via ``precision_stats``**
For angles that do not require the full precision determined by the angle encoding and
phase gradient wires, we may use a smaller encoding and adder, reducing the cost of the
phase gradient rotation. However, as rotation angles are not known statically in general,
this adaptive precision is only supported if additional information about the distribution
of rotation angles is provided via ``precision_stats``, a dictionary mapping a number
of bits to the number of rotations requiring that many bits.
The bits required by an angle :math:`\phi` are the
position of the last set bit in ``qp.math.binary_decimals(phi, len(angle_wires),
unit=2 * np.pi)``, i.e., the precision without trailing zeros. If provided,
the data loading and the :class:`~.SemiAdder` are truncated to the smallest number of
bits in ``precision_stats`` that suffices for a given angle, using :func:`~.cond`
branches that are hinted with the corresponding probabilities via :func:`~.hint`.
If no number of bits in ``precision_stats`` suffices, the full precision is used.
Keys must lie between ``0`` and ``len(angle_wires)``. Zero counts are ignored, and
a dictionary without non-zero counts is treated like ``None``. Use
:func:`~.phase_gradient_precision_stats` to compute the statistics from the angles.
**Example**
.. code-block:: python
from pennylane.transforms.decompositions import phase_gradient_precision_stats
angles = np.array([1/2, 1/4 + 1/8, 1/2 + 1/4 + 1/8]) * 2 * np.pi # (100), (011), (111)
precision_stats = phase_gradient_precision_stats(angles, prec, qp.RZ)
truncating_decomp = make_rz_to_phase_gradient_decomp(
angle_wires, phase_grad_wires, work_wires, precision_stats=precision_stats
)
@qp.transforms._tape_decompose(
gate_set=gate_set, fixed_decomps={qp.RZ: truncating_decomp}
)
@qp.qnode(qp.device("null.qubit"))
def truncated_circuit(phi):
qp.RZ(phi, 0)
return qp.state()
One rotation requires a single bit and two rotations require all three bits. The branches
of the rule are hinted with these frequencies, and the rotation by the first angle only uses
a single angle wire and phase gradient wire:
>>> precision_stats
{1: 1, 3: 2}
>>> wire_order = [0] + angle_wires + phase_grad_wires + work_wires
>>> print(qp.draw(truncated_circuit, wire_order=wire_order)(angles[0]))
0: ─╭GlobalPhase(1.57)─╭●────────────╭●─┤ ╭State
aux_0: ─├GlobalPhase(1.57)─╰X─╭SemiAdder─╰X─┤ ├State
phg_0: ─├GlobalPhase(1.57)────├SemiAdder────┤ ├State
work_0: ─├GlobalPhase(1.57)────├SemiAdder────┤ ├State
work_1: ─╰GlobalPhase(1.57)────╰SemiAdder────┤ ╰State
>>> print(qp.draw(truncated_circuit, wire_order=wire_order)(angles[1]))
0: ─╭GlobalPhase(1.18)─╭●─╭●────────────╭●─╭●─┤ ╭State
aux_0: ─├GlobalPhase(1.18)─│──│──╭SemiAdder─│──│──┤ ├State
aux_1: ─├GlobalPhase(1.18)─╰X─│──├SemiAdder─╰X─│──┤ ├State
aux_2: ─├GlobalPhase(1.18)────╰X─├SemiAdder────╰X─┤ ├State
phg_0: ─├GlobalPhase(1.18)───────├SemiAdder───────┤ ├State
phg_1: ─├GlobalPhase(1.18)───────├SemiAdder───────┤ ├State
phg_2: ─├GlobalPhase(1.18)───────├SemiAdder───────┤ ├State
work_0: ─├GlobalPhase(1.18)───────├SemiAdder───────┤ ├State
work_1: ─╰GlobalPhase(1.18)───────╰SemiAdder───────┤ ╰State
Finally, keep the following in mind when using ``precision_stats``:
* The resource function of the rule adds up the cost of all supported precisions, so
that the graph-based decomposition system accounts for the operators in all
conditional branches. This over-reports the cost of the rule, so that the
decomposition graph may prefer another rule over this one when it is registered with
:func:`~pennylane.decomposition.add_decomps`. Use ``fixed_decomps`` to enforce this rule.
* Angles that require more bits than the largest key in ``precision_stats`` fall back
to the full precision. Unless ``len(angle_wires)`` is a key in ``precision_stats``,
this fallback branch is hinted with probability ``0``, so that resource estimates
based on the hints do not account for these angles.
"""
angle_wires, phase_grad_wires, work_wires = validate_phase_gradient_wires(
angle_wires, phase_grad_wires, work_wires
)
precisions, dispatch = _precision_dispatcher(precision_stats, len(angle_wires), "RZ")
def _rz_phase_gradient_standard_resources(phi, wires): # pylint: disable=unused-argument
# rz decomposition costs, using information about angle_wires etc from the outer scope.
# Each non-zero precision that may be applied is counted once.
resources = {qp.GlobalPhase: 1}
for p in precisions - {0}:
target_op = qp.SemiAdder(Wire[p], Wire[p], Wire[len(work_wires)])
fanout = qp.ctrl(qp.MultiX(Bool[p], Wire[p]), control=Wire[1])
resources[ChangeOpBasis2(fanout, target_op, fanout)] = 1
return resources
# MultiX only emits a gate per set bit, so the gate count depends on the concrete angle.
@qp.register_resources(
_rz_phase_gradient_standard_resources, exact=False, name="phase_gradient"
)
def _rz_phase_gradient_standard(phi, wires):
qp.GlobalPhase(phi / 2)
dispatch(
phi,
lambda p: _rz_phase_gradient(
phi, wires, angle_wires[:p], phase_grad_wires[:p], work_wires
),
)
return _rz_phase_gradient_standard