Skip to content
Open
Show file tree
Hide file tree
Changes from 17 commits
Commits
Show all changes
76 commits
Select commit Hold shift + click to select a range
7553264
Name all decomp rules
comp-phys-marc Nov 9, 2026
e42408b
Update missed tables
comp-phys-marc Nov 9, 2026
b440a4f
Update tests
comp-phys-marc Nov 9, 2026
4a61a2d
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 9, 2026
893014a
Update doc
comp-phys-marc Nov 9, 2026
367d3a8
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 9, 2026
4a5903c
Update doc, test
comp-phys-marc Nov 9, 2026
7460523
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 9, 2026
48b57b4
coverage, pylint
comp-phys-marc Nov 9, 2026
417e1b9
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 9, 2026
ed31a5a
Fix naming collision
comp-phys-marc Nov 9, 2026
d0b7581
@register_name
comp-phys-marc Nov 11, 2026
43171ea
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 12, 2026
0d8b80f
Imports
comp-phys-marc Nov 12, 2026
d3e07ee
Imports
comp-phys-marc Nov 12, 2026
a8e5a4b
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 13, 2026
bfe891b
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 16, 2026
d878c22
fix file path
comp-phys-marc Nov 16, 2026
3a3c665
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 16, 2026
2400440
Replace _impl
comp-phys-marc Nov 16, 2026
b3200dc
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 16, 2026
c93a0a6
Replace Select decomp names
comp-phys-marc Nov 16, 2026
ed070f8
Replace ambiguous names
comp-phys-marc Nov 16, 2026
1633380
Update decomp inspector
comp-phys-marc Nov 16, 2026
f3d269b
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 16, 2026
0b05696
Update docs
comp-phys-marc Nov 16, 2026
5c4d60f
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 16, 2026
477fad0
xfail
comp-phys-marc Nov 17, 2026
f8654ed
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 17, 2026
277c319
CS names
comp-phys-marc Nov 17, 2026
802e0cf
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 17, 2026
dd03b32
Update CS docs
comp-phys-marc Nov 17, 2026
d3da43f
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 17, 2026
1e8bb26
Rename to_ppr -> to_paulirot
comp-phys-marc Nov 17, 2026
d400b84
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 17, 2026
13300e6
Update name
comp-phys-marc Nov 17, 2026
db07be4
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 17, 2026
394d4cc
Format, pylint, etc.
comp-phys-marc Nov 17, 2026
ad729f2
Format, pylint, etc.
comp-phys-marc Nov 17, 2026
e151dab
Fix rule names in docs
comp-phys-marc Nov 17, 2026
b1efc17
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 17, 2026
58b29a8
Add handling for renaming registered rules
comp-phys-marc Nov 17, 2026
cadc4a8
Fix rule names in docs
comp-phys-marc Nov 17, 2026
7aa2f4a
Docs
comp-phys-marc Nov 18, 2026
2ac2260
Update warning
comp-phys-marc Nov 18, 2026
3e5c79e
Assertions
comp-phys-marc Nov 18, 2026
237fd65
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 18, 2026
3cbe317
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 18, 2026
6260298
Update test
comp-phys-marc Nov 18, 2026
2fac516
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 18, 2026
63396f1
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 18, 2026
535e99d
Revert changelog
comp-phys-marc Nov 18, 2026
6bc01de
Revert "Revert changelog"
comp-phys-marc Nov 18, 2026
40032c0
Combine decorators
comp-phys-marc Nov 19, 2026
dfcbdd8
Revert "Combine decorators"
comp-phys-marc Nov 19, 2026
bb25bb2
Go back to the original approach
comp-phys-marc Nov 19, 2026
cc135e3
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 19, 2026
69e51a6
Format
comp-phys-marc Nov 19, 2026
5828d20
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 19, 2026
dbc76fe
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 19, 2026
f052ae6
Docs wording
comp-phys-marc Nov 19, 2026
219d8d0
Rename rules workers -> work_wires
comp-phys-marc Nov 20, 2026
e9c07d2
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 20, 2026
a22b43a
Remove outdated docs
comp-phys-marc Nov 20, 2026
7c2daea
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 20, 2026
dff9317
Fix bug
comp-phys-marc Nov 20, 2026
db0e25f
List available names
comp-phys-marc Nov 20, 2026
b84247e
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 20, 2026
c037a12
Import
comp-phys-marc Nov 20, 2026
4b3f19a
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 20, 2026
34cb059
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 20, 2026
ace01d7
Update tests
comp-phys-marc Nov 20, 2026
4f6d329
Merge remote-tracking branch 'origin/chore/names_on_decomp_rules' int…
comp-phys-marc Nov 20, 2026
4b69baf
Update tests
comp-phys-marc Nov 20, 2026
8f2d69c
pylint
comp-phys-marc Nov 20, 2026
cbfa881
Merge branch 'main' into chore/names_on_decomp_rules
comp-phys-marc Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/_ext/decomposition_table.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
:symbols: :math:`K` operators, :math:`c` control wires
:example: :math:`K=4`, :math:`c=2`

.. decomposition-rule:: _select_decomp_unary
.. decomposition-rule:: unary
:image: /_static/decomposition_thumbnails/select_unary.svg
:requires: :math:`c - 1` work wires
:where: :math:`N = c + K - 2`
Expand Down
1 change: 1 addition & 0 deletions doc/development/plugins.rst
Original file line number Diff line number Diff line change
Expand Up @@ -297,6 +297,7 @@ registered with ``qp.add_decomps``:

.. code-block:: python

@qp.register_name("decompose_cnot")
@qp.register_resources({qp.RY: 3, qp.RX: 1, qp.IsingXX: 1})
def decompose_cnot(wires, **_):
qp.RY(np.pi/2, wires=wires[0])
Expand Down
4 changes: 4 additions & 0 deletions doc/introduction/compiling_circuits.rst
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,7 @@ to a device:

.. code-block:: python3

@qp.decomposition.register_name("custom_cnot_decomposition")
@qp.decomposition.register_resources({
qp.H: 2,
qp.CZ: 1
Expand Down Expand Up @@ -348,6 +349,7 @@ Consider this example where we add a fixed decomposition to ``CNOT`` gates:

qp.decomposition.enable_graph()

@qp.register_name("my_cnot")
@qp.register_resources({qp.H: 2, qp.CZ: 1})
def my_cnot(wires, **__):
qp.H(wires=wires[1])
Expand Down Expand Up @@ -378,12 +380,14 @@ type:

.. code-block:: python

@qp.register_name("my_cnot1")
@qp.register_resources({qp.H: 2, qp.CZ: 1})
def my_cnot1(wires, **__):
qp.H(wires=wires[1])
qp.CZ(wires=wires)
qp.H(wires=wires[1])

@qp.register_name("my_cnot2")
@qp.register_resources({qp.RY: 2, qp.CZ: 1, qp.Z: 2})
def my_cnot2(wires, **__):
qp.RY(np.pi/2, wires[1])
Expand Down
3 changes: 2 additions & 1 deletion doc/releases/changelog-0.45.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,8 @@ understand how PennyLane decomposed a circuit, why specific rules where chosen o

qp.decomposition.enable_graph()

@qp.register_resources({qp.CNOT: 1, qp.H: 2}, name='my_cz_rule')
@qp.register_name('my_cz_rule')
@qp.register_resources({qp.CNOT: 1, qp.H: 2})
def cz_to_h_cnot(wires):
qp.H(wires[1])
qp.CNOT(wires)
Expand Down
18 changes: 13 additions & 5 deletions doc/releases/changelog-dev.rst
Original file line number Diff line number Diff line change
Expand Up @@ -246,6 +246,7 @@
.. code-block:: python

@qp.subcircuit(dynamic_argnames=("phi",), wire_argnames=("wires",))
@qp.register_name("MyOp")
@qp.register_resources({qp.H: 1, qp.RZ: 1})
def MyOp(phi, wires):
"""My custom operator created using qp.subcircuit."""
Expand All @@ -260,7 +261,7 @@
>>> isinstance(op, qp.core.Operator2)
True
>>> qp.inspect_decomps(op)
Decomposition 0 (name: MyOp_decomp)
Decomposition 0 (name: MyOpdecomp)
0: ──H──RZ(0.50)─┤
Gate Count: {Hadamard: 1, RZ: 1}

Expand Down Expand Up @@ -965,7 +966,7 @@
The original decomposition is used when fewer work wires are supplied.
`(#10380) <https://github.com/PennyLaneAI/pennylane/pull/10380>`__

* Added a new decomposition rule, ``_single_excitation_ppr_crz``, to :class:`~.SingleExcitation`, that
* Added a new decomposition rule, ``_single_excitation_to_ppr_crz``, to :class:`~.SingleExcitation`, that
realizes the Givens rotation with a single arbitrary-angle ``CRZ`` gate and four Clifford operations.
`(#10358) <https://github.com/PennyLaneAI/pennylane/pull/10358>`__

Expand Down Expand Up @@ -1014,7 +1015,7 @@
installed Catalyst is older.
`(#10369) <https://github.com/PennyLaneAI/pennylane/pull/10369>`__

* The ``decompose_mcx_with_no_worker`` decomposition rule for :class:`~.MultiControlledX` now only
* The ``_mcx_no_work_wires`` decomposition rule for :class:`~.MultiControlledX` now only
applies when no work wires are provided, matching ``MultiControlledX.compute_decomposition``.
This removes controlled ``GlobalPhase`` and ``PhaseShift`` rules from the decomposition graph and
greatly reduces ``qp.qjit(capture=True)`` compile time for multi-controlled X gates with work wires.
Expand Down Expand Up @@ -1535,6 +1536,13 @@
Breaking changes 💔
~~~~~~~~~~~~~~~~~~~

* Decomposition rule names are registered with :func:`~.register_name` instead of the

Check warning on line 1539 in doc/releases/changelog-dev.rst

View workflow job for this annotation

GitHub Actions / sphinx

more than one target found for cross-reference 'register_resources': pennylane.decomposition.register_resources, pennylane.register_resources [ref.python]

Check warning on line 1539 in doc/releases/changelog-dev.rst

View workflow job for this annotation

GitHub Actions / sphinx

more than one target found for cross-reference 'register_name': pennylane.decomposition.register_name, pennylane.register_name [ref.python]
``name`` argument of :func:`~.register_resources` and cannot start with an underscore.
Built-in decomposition rules use short strategy names, such as
``"to_cnot"`` for ``SWAP``, available through
``qp.list_decomps(qp.SWAP)["to_cnot"]`` and ``fixed_decomps={qp.SWAP: "to_cnot"}``.
`(#10492) <https://github.com/PennyLaneAI/pennylane/pull/10492>`__

* :func:`~.workflow.get_compile_pipeline` now returns the compile pipeline(s) directly: use
``get_compile_pipeline(qnode, level)`` instead of
``get_compile_pipeline(qnode, level)(*args, **kwargs)``. The device preprocessing transforms
Expand Down Expand Up @@ -1939,7 +1947,7 @@
* Update ``tach`` to ``0.35.1``.
`(#10147 ) <https://github.com/PennyLaneAI/pennylane/pull/10147>`__

* The ``_prepselprep_decomp`` decomposition rule of :class:`~.PrepSelPrep` now applies the linear-combination
* The ``_prepselprep_standard`` decomposition rule of :class:`~.PrepSelPrep` now applies the linear-combination
unitaries and their global phases as two separate :class:`~.Select` operators instead of a single ``Select``
of products.
`(#10020) <https://github.com/PennyLaneAI/pennylane/pull/10020>`__
Expand Down Expand Up @@ -2700,7 +2708,7 @@
decomposition path from being traced with abstract arrays only checked
``capture.enabled()``, missing the ``qjit`` context where
``compiler.active()`` is ``True``. Both ``two_qubit_decomposition`` and
``two_qubit_decomp_rule`` are fixed.
``_qubit_unitary_two_qubit`` are fixed.
`(#9520) <https://github.com/PennyLaneAI/pennylane/pull/9520>`__

* Fixed a bug in the :mod:`~.pennylane.qchem.vibrational` submodule to properly account for the number of modes.
Expand Down
1 change: 1 addition & 0 deletions pennylane/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
from pennylane.allocation import allocate, deallocate
from pennylane import decomposition
from pennylane.decomposition import (
register_name,
register_resources,
register_condition,
add_decomps,
Expand Down
3 changes: 2 additions & 1 deletion pennylane/core/operator/operator2.py
Original file line number Diff line number Diff line change
Expand Up @@ -233,6 +233,7 @@ def _my_op_resources(pauli_string, angle_array, wires, rot_wire):
resources[qp.Rot] = 1
return resources

@qp.register_name("my_op_decomp")
@qp.register_resources(_my_op_resources)
def _my_op_decomp(pauli_string, angle_array, wires, rot_wire):
wire_map = {wires[i]: i for i in range(len(wires))}
Expand All @@ -258,7 +259,7 @@ def f():
>>> qp.decomposition.enable_graph()
>>> inspector = qp.decomp_inspector(f)()
>>> inspector.inspect_decomps(MyOp("XYY", jnp.array([0.1, 0.2, 0.3]), wires=(0, 1, 2), rot_wire=(3,)))
CHOSEN: Decomposition 0 (name: _my_op_decomp)
CHOSEN: Decomposition 0 (name: my_op_decomp)
0: ──X───────────────────┤
1: ──Y───────────────────┤
2: ──Y───────────────────┤
Expand Down
6 changes: 6 additions & 0 deletions pennylane/decomposition/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@
:toctree: api

~register_resources
~register_name
~register_condition
~resource_rep
~controlled_resource_rep
Expand All @@ -74,6 +75,7 @@

.. code-block:: python

@qp.register_name("my_cnot")
@qp.register_resources({qp.H: 2, qp.CZ: 1})
def my_cnot(wires):
qp.H(wires=wires[1])
Expand Down Expand Up @@ -147,18 +149,21 @@ def my_cnot(wires):

qp.decomposition.enable_graph()

@qp.register_name("isingxx_decomp")
@qp.register_resources({qp.CNOT: 2, qp.RX: 1})
def isingxx_decomp(phi, wires, **__):
qp.CNOT(wires=wires)
qp.RX(phi, wires=[wires[0]])
qp.CNOT(wires=wires)

@qp.register_name("my_cnot1")
@qp.register_resources({qp.H: 2, qp.CZ: 1})
def my_cnot1(wires, **__):
qp.H(wires=wires[1])
qp.CZ(wires=wires)
qp.H(wires=wires[1])

@qp.register_name("my_cnot2")
@qp.register_resources({qp.RY: 2, qp.CZ: 1, qp.Z: 2})
def my_cnot2(wires, **__):
qp.RY(np.pi/2, wires[1])
Expand Down Expand Up @@ -251,6 +256,7 @@ def circuit():
change_op_basis_resource_rep,
)
from .decomposition_rule import (
register_name,
register_resources,
register_condition,
DecompositionRule,
Expand Down
10 changes: 5 additions & 5 deletions pennylane/decomposition/all_decomps.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,11 +54,11 @@ def all_decomps(
>>> len(rules_map)
66
>>> rules_map[qp.RX(Float, Wire[1])]
[DecompositionRule(name=_rx_to_rot),
DecompositionRule(name=_rx_to_rz_ry),
DecompositionRule(name=_rx_to_ppr),
DecompositionRule(name=_rx_to_ry_cliff),
DecompositionRule(name=_rx_to_rz_cliff)]
[DecompositionRule(name=to_rot),
DecompositionRule(name=to_rz_ry),
DecompositionRule(name=to_ppr),
DecompositionRule(name=to_ry_cliff),
DecompositionRule(name=to_rz_cliff)]

The keys from a rule map can be reused on successive calls to avoid recollecting the same nodes.
Note that if an op is skipped, it's children will also not be added.
Expand Down
43 changes: 24 additions & 19 deletions pennylane/decomposition/decomposition_graph.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,18 +51,18 @@
)
from .resources import AbstractOperatorLike, CompressedResourceOp, Resources, resource_rep
from .symbolic_decomposition import (
adjoint_rotation,
cancel_adjoint,
_adjoint_cancel,
_adjoint_negate_angle,
_controlled_flip_adjoint,
_controlled_to_unitary,
_operator1_to_base,
_pow_flip_adjoint,
_pow_merge_powers,
_pow_repeat_base,
ctrl_single_work_wire,
decompose_to_base_legacy,
flip_control_adjoint,
flip_pow_adjoint,
make_adjoint_decomp,
make_controlled_decomp,
merge_powers,
repeat_pow_base,
self_adjoint_legacy,
to_controlled_qubit_unitary,
)
from .utils import to_name

Expand Down Expand Up @@ -215,6 +215,7 @@ class DecompositionGraph: # pylint: disable=too-many-instance-attributes,too-fe

import pennylane as qp

@qp.register_name("my_cz")
@qp.register_resources({qp.H: 2, qp.CNOT: 1})
def my_cz(wires):
qp.H(wires=wires[1])
Expand All @@ -235,7 +236,8 @@ def my_cz(wires):
operations (list[Operator or CompressedResourceOp]): The list of operations to decompose.
gate_set (Set | Mapping | GateSet): A set of gates in the target gate set or a dictionary
mapping gates in the target gate set to their respective weights. All weights must be positive.
fixed_decomps (dict): A dictionary mapping operator names to fixed decompositions.
fixed_decomps (dict): A dictionary mapping operator types or names to fixed decompositions.
Values can be decomposition rules or public names from :func:`~pennylane.list_decomps`.
alt_decomps (dict): A dictionary mapping operator names to alternative decompositions.
strict (bool): If ``False``, treat operators that do not define a decomposition as supported.
Defaults to ``True``.
Expand Down Expand Up @@ -301,7 +303,10 @@ def __init__(
# Stores the library of custom decomposition rules
fixed_decomps = fixed_decomps or {}
alt_decomps = alt_decomps or {}
self._fixed_decomps = {to_name(k): _validate_rule(v) for k, v in fixed_decomps.items()}
self._fixed_decomps = {
to_name(k): _validate_rule(list_decomps(k)[v] if isinstance(v, str) else v)
for k, v in fixed_decomps.items()
}
self._alt_decomps = {to_name(k): _validate_rule(v) for k, v in alt_decomps.items()}

# Initializes the graph.
Expand Down Expand Up @@ -613,12 +618,12 @@ def _get_decompositions(self, op: AbstractOperatorLike) -> Iterable[Decompositio
if (
issubclass(op.op_type, qp.ops.Adjoint)
and self_adjoint_legacy not in decomps
and adjoint_rotation not in decomps
and _adjoint_negate_angle not in decomps
):
# In general, we decompose the adjoint of an operator by applying adjoint to the
# decompositions of the operator. However, this is not necessary if the operator
# is self-adjoint or if it has a single rotation angle which can be trivially
# inverted to obtain its adjoint. In this case, `self_adjoint` or `adjoint_rotation`
# inverted to obtain its adjoint. In this case, `self_adjoint` or `_adjoint_negate_angle`
# would've already been retrieved as a potential decomposition rule for this
# operator, so there is no need to consider the general case.
decomps.extend(self._get_adjoint_decompositions(op))
Expand All @@ -640,7 +645,7 @@ def _get_adjoint_decompositions(self, op: CompressedResourceOp) -> list[Decompos

# Special case: adjoint of an adjoint cancels out
if issubclass(base_class, qp.ops.Adjoint):
return [cancel_adjoint]
return [_adjoint_cancel]

# General case: apply adjoint to each of the base op's decomposition rules.
base = resource_rep(base_class, **base_params)
Expand All @@ -660,18 +665,18 @@ def _get_pow_decompositions(op: CompressedResourceOp) -> list[DecompositionRule]
return [null_decomp]

if op.params["z"] == 1:
return [decompose_to_base_legacy]
return [_operator1_to_base]

# Special case: power of a power
if issubclass(op.params["base_class"], qp.ops.Pow):
return [merge_powers]
return [_pow_merge_powers]

# Special case: power of an adjoint
if issubclass(op.params["base_class"], qp.ops.Adjoint):
return [flip_pow_adjoint]
return [_pow_flip_adjoint]

# General case: repeat the operator z times
return [repeat_pow_base]
return [_pow_repeat_base]

def _get_controlled_decompositions(self, op: CompressedResourceOp) -> list[DecompositionRule]:
"""Adds a controlled decomposition node to the graph."""
Expand All @@ -680,7 +685,7 @@ def _get_controlled_decompositions(self, op: CompressedResourceOp) -> list[Decom

# Special case: control of an adjoint
if issubclass(base_class, qp.ops.Adjoint):
return [flip_control_adjoint]
return [_controlled_flip_adjoint]

# Special case: when the base is GlobalPhase, none of the following automatically
# generated decomposition rules apply. Also, controlled ChangeOpBasis defines its
Expand All @@ -699,7 +704,7 @@ def _get_controlled_decompositions(self, op: CompressedResourceOp) -> list[Decom

# There's always the option of turning the controlled operator into a controlled
# qubit unitary if the base operator has a matrix form.
rules.append(to_controlled_qubit_unitary)
rules.append(_controlled_to_unitary)

# There's always Lemma 7.11 from https://arxiv.org/abs/quant-ph/9503016.
rules.append(ctrl_single_work_wire)
Expand Down
Loading
Loading