# 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"""
This module contains ``qp.subcircuit``, a factory function to create operators
using quantum functions.
"""
from collections.abc import Callable
from inspect import Parameter, Signature, signature
from pennylane.core import Operator2
from pennylane.decomposition import DecompositionRule, add_decomps
def _subcircuit(qfunc: DecompositionRule, **cls_attrs) -> type[Operator2]:
"""Implementation of ``subcircuit``."""
# pylint: disable=protected-access
if not isinstance(qfunc, DecompositionRule):
raise TypeError(
"The provided quantum function must register resources using 'qp.register_resources'."
)
# 'self' shouldn't be in signature(OpClass), but it should be in
# signature(OpClass.__init__)
s = signature(qfunc._impl)
self_p = Parameter("self", kind=Parameter.POSITIONAL_OR_KEYWORD)
init_sig = Signature((self_p, *s.parameters.values()))
def _init(self, *args, **kwargs):
Operator2.__init__(self, *args, **kwargs)
_init.__signature__ = init_sig
# sets up various class properties
attrs = dict(cls_attrs)
attrs["__init__"] = _init
attrs["__doc__"] = qfunc._impl.__doc__
attrs["__module__"] = qfunc._impl.__module__
attrs["__qualname__"] = qfunc._impl.__qualname__
# creates a new class
new_operator = type(qfunc.name, (Operator2,), attrs)
# registers the decomposition
decomp_name = qfunc.name + "_decomp"
decomp_rule = DecompositionRule(
qfunc._impl,
resources=qfunc._compute_resources,
work_wires=qfunc._work_wire_spec,
exact_resources=qfunc.exact_resources,
name=decomp_name,
)
add_decomps(new_operator, decomp_rule)
return new_operator
[docs]
def subcircuit( # pylint: disable=too-many-arguments
qfunc: DecompositionRule | None = None,
dynamic_argnames=(),
wire_argnames=("wires",),
compilable_argnames=(),
hybrid_argnames=(),
static_argnames=(),
**cls_attrs,
) -> Callable | type[Operator2]:
r"""A decorator for turning a quantum function with registered resources into an
:class:`~.Operator2` subclass.
The quantum function decorated with `subcircuit` can be any valid quantum
function, provided that nothing is returned from it (e.g., terminal measurements are
not allowed) and that it has resources registered to it via :func:`~pennylane.register_resources`.
The decorated quantum function will automatically be registered as an :class:`~.Operator2`
subclass with a single decomposition rule that corresponds to the quantum function body.
Args:
qfunc (DecompositionRule): a quantum function whose resources have been registered with
:func:`~pennylane.register_resources`
Keyword Args:
dynamic_argnames (Sequence[str]): names of the arguments that are dynamic data of the
operator. For more details, see :attr:`~.Operator2.dynamic_argnames`
wire_argnames (Sequence[str]): names of the arguments that are wires. Defaults to
``("wires",)``. For more details, see :attr:`~.Operator2.wire_argnames`
compilable_argnames (Sequence[str]): names of arguments that are static **and compilable**
data of the operator. For more details, see :attr:`~.Operator2.compilable_argnames`
hybrid_argnames (Sequence[str]): names of arguments that are dynamic data wrapped in static
data structures (pytrees). For more details, see :attr:`~.Operator2.hybrid_argnames`
static_argnames (Sequence[str]): names of arguments that are static but **not compilable**.
For more details, see :attr:`~.Operator2.static_argnames`
**cls_attrs: additional class attributes to set on the created operator class
Returns:
type[~.Operator2]: a new operator class named after the quantum function
.. note::
Every parameter of the quantum function must be classified into one of ``dynamic_argnames``,
``wire_argnames``, ``compilable_argnames``, ``hybrid_argnames`` or ``static_argnames``.
See :class:`~.Operator2` for details on how arguments are classified.
.. seealso:: :class:`~.Operator2`, :func:`~pennylane.register_resources`
**Example**
An operator can be created by decorating a quantum function that has registered resources. Its
parameters are classified using the ``*_argnames`` keyword arguments; here
``phi`` is dynamic data and ``wires`` are (by default) the wires:
.. code-block:: python
@qp.subcircuit(dynamic_argnames=("phi",))
@qp.register_resources({qp.H: 1, qp.RZ: 1}, name="MyOp")
def MyOp(phi, wires):
qp.H(wires)
qp.RZ(phi, wires)
The returned object is an :class:`~.Operator2` subclass named after the quantum function, and
is instantiated and used like any other operator:
>>> op = MyOp(0.5, wires=0)
>>> op
MyOp(0.5, wires=[0])
>>> isinstance(op, qp.core.Operator2)
True
The body of the quantum function is registered as its decomposition rule:
>>> qp.inspect_decomps(op)
Decomposition 0 (name: MyOp_decomp)
0: ──H──RZ(0.50)─┤
Gate Count: {Hadamard: 1, RZ: 1}
"""
if qfunc is not None:
return _subcircuit(
qfunc,
dynamic_argnames=dynamic_argnames,
wire_argnames=wire_argnames,
compilable_argnames=compilable_argnames,
hybrid_argnames=hybrid_argnames,
static_argnames=static_argnames,
**cls_attrs,
)
def wrapper(qfunc_):
return _subcircuit(
qfunc_,
dynamic_argnames=dynamic_argnames,
wire_argnames=wire_argnames,
compilable_argnames=compilable_argnames,
hybrid_argnames=hybrid_argnames,
static_argnames=static_argnames,
**cls_attrs,
)
return wrapper