Source code for pennylane.core.operator.operator2

# 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 the abstract base classes for defining PennyLane
operations and observables.
TODO: [sc-120453] Fill docstring
"""

import warnings
from abc import abstractmethod
from collections.abc import Hashable, Iterable, Sequence
from copy import copy, deepcopy
from enum import Enum, StrEnum, auto
from functools import partial
from inspect import BoundArguments, Signature, signature
from numbers import Number
from types import NoneType
from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias

import numpy as np
from jax.core import ShapedArray
from scipy.sparse import issparse, spmatrix

import pennylane as qp
from pennylane import capture, math
from pennylane._class_property import classproperty
from pennylane.capture import pause, symbolic_array
from pennylane.capture.custom_primitives import QpPrimitive
from pennylane.capture.op_eqns import pop_op_eqns
from pennylane.core.apply import apply
from pennylane.core.queuing import AnnotatedQueue, QueuingManager
from pennylane.exceptions import (
    AdjointUndefinedError,
    DecompositionUndefinedError,
    DiagGatesUndefinedError,
    EigvalsUndefinedError,
    GeneratorUndefinedError,
    MatrixUndefinedError,
    ParameterFrequenciesUndefinedError,
    PowUndefinedError,
    SparseMatrixUndefinedError,
    TermsUndefinedError,
)
from pennylane.pytrees import flatten, leaf, register_pytree, unflatten
from pennylane.typing import (
    AbstractArray,
    AbstractWires,
    FlatPytree,
    TensorLike,
    _AbstractWireTypeFactory,
)
from pennylane.wires import AbstractQubit, Wires, WiresLike

from .base import _UNSET_BATCH_SIZE, AbstractOperator, Operator
from .meta import OperatorMeta
from .utils import abstractify

if TYPE_CHECKING:
    from pennylane.pauli import PauliSentence

ArgSpecType: TypeAlias = type[Number] | AbstractArray | AbstractWires


class GradMethod(StrEnum):
    """Supported gradient methods."""

    ANALYTIC = "A"
    FINITE_DIFF = "F"


ARGNAME_CATEGORIES = (
    "wire_argnames",
    "dynamic_argnames",
    "static_argnames",
    "compilable_argnames",
    "hybrid_argnames",
)


class OperatorRegistry:
    """A Singleton class that keeps track of all the Operator2 operators (including user-defined operators) defined."""

    _instance = None
    registry = {}

    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance

    def __getitem__(self, index):
        try:
            return self.registry[index]
        except KeyError as e:
            raise KeyError(f"No defined Operator2 with the name {index} found.") from e

    def __setitem__(self, index, value):
        if index not in self.registry:
            self.registry[index] = value
        elif self.registry[index] is not value:
            warnings.warn(
                f"More than one operator class by the same name ({index}) has been defined."
            )


[docs] class Operator2(metaclass=OperatorMeta): r"""Base class representing quantum operators that are designed for compatibility with :func:`~.qjit`. Child classes of ``Operator2`` are defined by their name and argument types, of which there are five categories that are designated as class variables. These arguments dictate how ``Operator2`` child classes are handled when compiling with :func:`~.qjit`. * :attr:`wire_argnames <Operator2.wire_argnames>` : The names of arguments corresponding to wires. Values for these arguments are automatically wrapped in :class:`~.Wires` objects by the ``Operator2`` constructor. .. note:: ``Operator2.wire_argnames`` defaults to ``("wires",)``. Thus, if an operator one has one wire argument and it is called ``wires``, ``wire_argnames`` does not need to be overridden. * :attr:`dynamic_argnames <Operator2.dynamic_argnames>` : The names of arguments that are treated as dynamic. Inputs for these arguments must be scalars, arrays, or castable to arrays. * :attr:`static_argnames <Operator2.static_argnames>` : The names of arguments that are treated as static but are **not compilable** (see below). * :attr:`compilable_argnames <Operator2.compilable_argnames>` : The names of arguments that are treated as **compilable** static arguments. Compilable static arguments include numeric values, strings, lists, tuples, and dictionaries. This feature is opt-in; if any static arguments are not guaranteed to be compilable, it is safer to place them in :attr:`static_argnames <Operator2.static_argnames>`. .. note:: An operator can only specify :attr:`static_argnames <Operator2.static_argnames>` or :attr:`compilable_argnames <Operator2.compilable_argnames>`, but not both; if **any** static arguments cannot be lowered to the IR, then all static arguments must be treated as not lowerable. * :attr:`hybrid_argnames <Operator2.hybrid_argnames>` : The names of arguments that represent dynamic data wrapped in static structures (known as Pytrees). Names in this category may only overlap with :attr:`wire_argnames <Operator2.wire_argnames>` when those arguments contain nested structures of wires. Args: *args (tuple[...]): positional arguments **kwargs (dict[str, Any]): Key-word arguments .. details:: :title: Defining Custom Operators Custom ``Operator2`` instances **must** designate all their arguments to one of the aforementioned categories. This means that the union of all the designated arguments must cover the full set of arguments. As an example, consider the following custom operator: .. code-block:: python import pennylane as qp from pennylane.core import Operator2 import jax.numpy as jnp class MyOp(Operator2): wire_argnames = ("wires", "rot_wire") compilable_argnames = ("pauli_string") dynamic_argnames = ("angle_array") def __init__(self, pauli_string, angle_array, wires, rot_wire): super().__init__(pauli_string, angle_array, wires, rot_wire) @staticmethod def compute_matrix(pauli_string, angle_array, wires, rot_wire): wire_map = {wires[i]: i for i in range(len(wires))} pauli_op = qp.pauli.string_to_pauli_word(pauli_string, wire_map=wire_map) rot_op = qp.Rot(*angle_array, wires=rot_wire) return qp.matrix(qp.prod(pauli_op, rot_op)) The ``wires`` and ``rot_wire`` arguments will be a part of :attr:`wire_argnames <Operator2.wire_argnames>`, and ``pauli_string`` and ``angle_array`` will belong to :attr:`compilable_argnames <Operator2.compilable_argnames>` and :attr:`dynamic_argnames <Operator2.dynamic_argnames>`, respectively. >>> from jax import numpy as jnp >>> angle_array = jnp.array([0.1, 0.2, 0.3]) >>> op = MyOp("XYZ", angle_array, wires=(0, 1, 2), rot_wire=(3,)) >>> op MyOp(pauli_string=XYZ, angle_array=[0.1 0.2 0.3], wires=[0, 1, 2], rot_wire=[3]) For optimal functionality, ``MyOp`` should define a decomposition using :func:`~pennylane.add_decomps`, which is covered in the following section. **Decomposing Operators** More information and specifics on how to define decomposition rules for operators is found in the :mod:`pennylane.decomposition` module. A brief synopsis is offered here. Adding a decomposition rule to an existing or a custom operator can be done by defining two functions: * A "resource" function, which contains the resources comprising the decomposition rule. * The decomposition rule itself, structured as a quantum function. Both the resource function and the decomposition rule **must** have the same call signature as the operator. Consider this example using the custom operator ``MyOp``. .. code-block:: python from collections import defaultdict def _my_op_resources(pauli_string, angle_array, wires, rot_wire): resources = defaultdict(int) for char in pauli_string: resources[getattr(qp, char)] += 1 resources[qp.Rot] = 1 return resources @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))} for wire, pauli in zip(wires, pauli_string): getattr(qp, pauli)(wire) qp.Rot(*angle_array, wires=rot_wire) qp.add_decomps(MyOp, _my_op_decomp) Resource functions are "registered" to the decomposition rule by decorating with :func:`~pennylane.register_resources`. Adding the decomposition rule to the operator officially is done via :func:`~pennylane.add_decomps`. To verify, we can inspect that the decomposition rule created as been added to ``MyOp`` as follows. .. code-block:: python num_wires = 4 @qp.qnode(qp.device("null.qubit", wires=4)) def f(): MyOp("XYY", jnp.array([0.1, 0.2, 0.3]), wires=(0, 1, 2), rot_wire=(3,)) return qp.expval(qp.Z(0)) >>> 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) 0: ──X───────────────────┤ 1: ──Y───────────────────┤ 2: ──Y───────────────────┤ 3: ──Rot(0.10,0.20,0.30)─┤ First-Level Expansion Gates: {PauliX: 1, PauliY: 2, Rot: 1} Full Expansion Gates: {PauliX: 1, PauliY: 2, Rot: 1} Weighted Cost: 4.0 >>> qp.decomposition.disable_graph() **Downstream effects of static_argnames, compilable_argnames** Static and *compilable static* arguments are similar, but have key differences to note that dictate how certain arguments are treated when compiled down to MLIR. Both ``static_argnames`` and ``compilable_argnames`` denote data that cannot be dynamic. In other words, they both represent concrete data whose values are known when tracing the program. The distinction in their behaviour comes at compile-time. Arguments in ``compilable_argnames`` denote data that *can* be concretely accessed and inspected at compile-time (it can be compiled and represented concretely in MLIR), including numeric values, strings, lists, tuples, and dictionaries. In the example above with ``MyOp``, the ``pauli_string`` argument is part of ``compilable_argnames``. Its concrete (static) value will be accessible at compile time, being represented at the MLIR level as follows, where the concrete value of ``pauli_string`` is captured in the ``static_data`` attribute in MLIR: >>> op = MyOp("XYZ", angle_array, wires=(0, 1, 2), rot_wire=(3,)) # doctest: +SKIP .. code-block:: %out_qubits:4 = quantum.operator "MyOp"(%arg0: tensor<3xf64>) qubits(%q0, %q1, %q2, %q3) static_data = {pauli_string = "XYZ"} param_map = {angle_array = [0]} qubit_map = {rot_wires = [1, 2, 3], wires = [0]} Arguments in ``static_argnames`` denote data that *cannot* be concretely accessed and inspected at compile-time (it cannot be compiled and represented concretely in MLIR), including arbitrary Python objects, Python functions, and custom classes. Static data will be reduced to a Unique Identifier (UID) at the MLIR level. In the example above with ``MyOp``, if the ``pauli_string`` argument was part of ``static_argnames``, ``MyOp`` would be represented in MLIR as follows, where the concrete value of ``pauli_string`` is reduced to a UID in MLIR: .. code-block:: %out_qreg = quantum.operator "MyOp"(%arg0: tensor<3xf64>) UID(278653) quregs(%arg3) indices(%arg1: tensor<3xi64>, %arg2: tensor<1xi64>) %out_qubits:4 = quantum.operator "MyOp"(%arg0: tensor<3xf64>) qubits(%arg4, %arg5, %arg6, %arg7) UID(234567) param_map = {angle_array = [0]} qubit_map = {rot_wires = [1, 2, 3], wires = [0]} .. note:: If ``hybrid_argnames`` is not empty, the above behaviour also occurs downstream; the dynamic data stored within the Pytree is lowered correctly, and the static structure of the Pytree is reduced to a UID in MLIR. """ # pylint: disable=too-many-public-methods, too-many-instance-attributes _operator_version = 2 # ----------------- Class variables set manually ------------------------- wire_argnames: ClassVar[tuple[str, ...]] = ("wires",) """The names of arguments corresponding to wires. Values for these arguments are automatically wrapped in :class:`~.Wires` objects by the ``Operator2`` constructor. If an argument is expected to be a structure that wraps wires (known as pytrees), such as a list of wire registers, make sure to include its name in ``hybrid_argnames`` as well. Additionally, ``Operator2`` does not descend into the pytree structure of such arguments, so subclasses must ensure every wire leaf inside a hybrid wire argument is already a :class:`~.Wires` object before forwarding it to ``super().__init__``. The order in which names appear in ``wire_argnames`` determines the order in which their wires appear in ``op.wires`` (see :attr:`Operator2.wires`). For hybrid wire arguments, the contained :class:`~.Wires` leaves are ordered by pytree traversal order. Wires contributed by arguments which are themselves :class:`~.Operator2` objects are appended *after* all ``wire_argnames`` wires. The special names ``"work_wires"`` and ``"work_wire"`` may be included in ``wire_argnames`` but their values are excluded from ``op.wires``. """ dynamic_argnames: ClassVar[tuple[str, ...]] = () """The names of arguments that are treated as dynamic. Dynamic arguments are numerical arguments whose concrete values may not be known at compile-time, such as rotation angles, matrices, etc., and may include trainable data. Additionally, dynamic arguments are the only ones used to infer :attr:`~.Operator2.batch_size`, necessary for broadcasting support. Inputs for these arguments must be scalars, arrays, or castable to arrays (e.g. multi- dimensional lists with homogenous shapes), and operator constructors will be responsible for "canonicalizing" them (such as casting a list input to an array). At compile-time, the concrete values of these arguments are assumed to be unknown—only their shapes and data types are known. """ static_argnames: ClassVar[tuple[str, ...]] = () """The names of arguments that are treated as static. Static arguments are those whose concrete values are known when compiling the program. Arguments specified here are not lowered to a compiler intermediate representation (IR). Alternatively, if an argument is of a type that can be lowered, it can be moved to ``compilable_argnames``. .. note:: An operator can only specify ``static_argnames`` and ``hybrid_argnames``, or ``compilable_argnames``, but not both; if **any** static or hybrid arguments are not or cannot be lowered to the IR, then all static and hybrid arguments are assumed to not be lowerable. """ compilable_argnames: ClassVar[tuple[str, ...]] = () """The names of arguments that are treated as **compilable** static arguments. Compilable static arguments are a subset of static arguments—arguments whose concrete values are known when compiling the program. But, unlike ``static_argnames``, they are lowered to the compiler intermediate representation, making their values visible to the compiler, which may be useful if the compiler needs to interact with such values. Such values may include numbers, strings, and lists, tuples, or dictionaries thereof. This feature is opt-in; if any static arguments are not guaranteed to be compilable, it is safer to place them in ``static_argnames``. .. note:: An operator can only specify ``static_argnames`` and ``hybrid_argnames``, or ``compilable_argnames``, but not both; if **any** static or hybrid arguments are not or cannot be lowered to the IR, then all static and hybrid arguments are assumed to not be lowerable. """ hybrid_argnames: ClassVar[tuple[str, ...]] = () """The names of arguments that represent dynamic data wrapped in static structures (known as Pytrees). Names in this category must be disjoint from ``dynamic_argnames``, ``static_argnames``, and ``compilable_argnames``, but may overlap with ``wire_argnames`` when those arguments contain nested structures of wires. Examples of hybrid arguments include collections of wires or dynamic arrays, operators, etc. .. note:: An operator can only specify ``static_argnames`` and ``hybrid_argnames``, or ``compilable_argnames``, but not both; if **any** static or hybrid arguments are not or cannot be lowered to the IR, then all static and hybrid arguments are assumed to not be lowerable. """ wire_sizes: ClassVar[tuple[int | None, ...] | None] = None """The expected number of wire labels for each wire argument. If any wire arguments support an arbitrary size, ``None`` must be used. By default, all wire arguments are assumed to support arbitrary sizes. For hybrid wire arguments, the wire size must always be ``None``. Specifying wire sizes allows for additional automatic validation to be implemented, but, specifying it is optional if such validation is not needed. """ arg_specs: ClassVar[dict[str, ArgSpecType] | None] = None """The expected types for the arguments of an operator. This attribute is optional—not setting it has no loss of functionality. If set, it can be used to perform automatic validation of an operators inputs during construction. Additionally, when defining decomposition rules for an operator, operator types with ``arg_specs`` that spans all the arguments with static types can be placed in the rules' resources without needing to fully construct abstract operators. .. note:: A type that is listed in 'arg_specs' says what an argument is allowed to be, not what it actually is. For example, if arg_specs contains Complex[-1, -1], the Operator can still be instantiated with a real float64 array, which will then be reported as complex even though it holds real data. The decomposition graph goes by the reported type, so real and complex inputs will look like the same operator and share one rule. To let them decompose differently, leave the argument out of ``arg_specs`` and give each rule a ``register_condition`` that checks the type. For a concrete example see ``BasisRotation``. """ # ----------------- Class variables set automatically -------------------- _sig: ClassVar[Signature] """The signature of the operator. Internal use only.""" has_fixed_sig: ClassVar[bool] = False """Whether the expected signature of an operator is fixed. If ``True``, then the operator's signature will always be fully known. When defining decomposition rules for an operator, operator types with fixed signatures can be placed in the rules' resources without needing to fully construct abstract operators. This is set automatically when ``arg_specs`` covers every dynamic and wire argument, there are no hybrid, static, or compilable arguments, and every declared type is fully fixed (no unknown array shapes or wire counts). """ # ----------------- Instance variables set automatically ----------------- _bound_args: BoundArguments """``BoundArguments`` mapping arguments names to their values.""" # ------------------------------------------------------------------------ # ----------------------------- Initialization --------------------------- # ------------------------------------------------------------------------ # this allows scalar multiplication from left with numpy arrays np.array(0.5) * ps1 # taken from [stackexchange](https://stackoverflow.com/questions/40694380/forcing-multiplication-to-use-rmul-instead-of-numpy-array-mul-or-byp/44634634#44634634) __array_priority__ = 1000 def __init__(self, *args, **kwargs): # Union[PauliSentence, None]: Representation of the operator as a # pauli sentence, if applicable self._pauli_rep: PauliSentence | None = None self._bound_args = self._sig.bind(*args, **kwargs) self._bound_args.apply_defaults() self._wires = Wires([]) _init_wires(self) _init_arg_types(self) # Broadcasting-related initialization self._batch_size: int | None = _UNSET_BATCH_SIZE self._ndim_params: tuple[int] = _UNSET_BATCH_SIZE self.tracer = None # ------------------------------------------------------------------------ # -------------------------- Public properties --------------------------- # ------------------------------------------------------------------------ @property def is_fully_abstract(self) -> bool: """Whether this operator contains only abstract data.""" # Make sure not to flatten wires here, because an empty Wires([]) flattens to # empty leaves, so it'd be incorrectly not identified as something concrete. leaves, _ = flatten(self, is_leaf=lambda l: isinstance(l, Wires)) return all(isinstance(l, (AbstractArray, AbstractWires, NoneType)) for l in leaves) @property def arguments(self) -> dict[str, Any]: """Dictionary mapping argument names to their values.""" return self._bound_args.arguments @property def dynamic_args(self) -> dict[str, Any]: """Dictionary mapping dynamic argument names to their values.""" return {name: self.arguments[name] for name in self.dynamic_argnames} @property def static_args(self) -> dict[str, Any]: """Dictionary mapping static argument names to their values.""" return {name: self.arguments[name] for name in self.static_argnames} @property def wire_args(self) -> dict[str, Any]: """Dictionary mapping wire argument names to their values.""" return {name: self.arguments[name] for name in self.wire_argnames} @property def hybrid_args(self) -> dict[str, Any]: """Dictionary mapping hybrid argument names to their values.""" return {name: self.arguments[name] for name in self.hybrid_argnames} @property def compilable_args(self) -> dict[str, Any]: """Dictionary mapping compilable argument names to their values.""" return {name: self.arguments[name] for name in self.compilable_argnames} @property def name(self) -> str: """Operator name.""" return self.__class__.__name__ @property def wires(self) -> Wires: """Wires that the operator acts on. By default, the returned :class:`~.Wires` are collected from the operator's arguments in the following order: 1. For each name in ``wire_argnames`` (in declaration order): * If the name is **not** in ``hybrid_argnames``, the canonical value of that argument is added. * If the name **is** in ``hybrid_argnames``, every :class:`~.Wires` leaf of the argument's pytree is added in pytree traversal order. 2. After all ``wire_argnames`` have been processed, for each name in ``hybrid_argnames`` that is **not** in ``wire_argnames``, the wires of any :class:`~.Operator2` leaves inside that argument are appended to the end in pytree traversal order. Duplicate wires are removed while preserving the first occurrence, so the final result is the ordered union of all wires above. .. note:: By default, work wires are **not included** in ``op.wires``. In particular, wire arguments named ``work_wires`` or ``work_wire`` are excluded. .. note:: This property may be overridden by developers if the default behaviour is not desired, for reasons such as including work wires or changing the order of the wires. Returns: Wires: wires """ return self._wires @property def batch_size(self) -> int | None: """Batch size of the operator if it is used with broadcasted parameters. The ``batch_size`` is determined based on ``ndim_params`` and the provided parameters for the operator. If (some of) the latter have an additional dimension, and this dimension has the same size for all parameters, its size is the batch size of the operator. If no parameter has an additional dimension, the batch size is ``None``. Returns: int or None: Size of the parameter broadcasting dimension if present, else ``None``. """ if self._batch_size is _UNSET_BATCH_SIZE: self._check_batching() return self._batch_size @property def ndim_params(self) -> tuple[int]: """Number of dimensions per trainable parameter of the operator. By default, this property returns the numbers of dimensions of the parameters used for the operator creation. If the parameter sizes for an operator subclass are fixed, this property can be overwritten to return the fixed value. Returns: tuple: Number of dimensions for each trainable parameter. """ if self._batch_size is _UNSET_BATCH_SIZE: self._check_batching() return self._ndim_params @property def num_params(self): """Number of trainable parameters.""" return len(self.ndim_params) @property def arithmetic_depth(self) -> int: """Arithmetic depth of the operator.""" return 0 @property def is_verified_hermitian(self) -> bool: """This property determines if an operator is verified to be Hermitian. .. note:: This property provides a fast, non-exhaustive check used for internal optimizations. It relies on quick, provable shortcuts (e.g., operator properties) rather than a full, computationally expensive check. For a definitive check, use the :func:`pennylane.is_hermitian` function. Please note that this comes with increased computational cost. Returns: bool: The property will return ``True`` if the operator is guaranteed to be Hermitian and ``False`` if the check is inconclusive and the operator may or may not be Hermitian. Consider this operator, >>> op = (qp.X(0) @ qp.Y(0) - qp.X(0) @ qp.Z(0)) * 1j In this case, Hermicity cannot be verified and leads to an inconclusive result: >>> op.is_verified_hermitian # inconclusive False However, using :func:`pennylane.is_hermitian` will give the correct answer: >>> qp.is_hermitian(op) # definitive True """ return False @property def pauli_rep(self) -> "PauliSentence | None": """A :class:`~.PauliSentence` representation of the Operator, or ``None`` if it doesn't have one.""" return self._pauli_rep # ------------------------------------------------------------------------ # -------------- Legacy Operator compatibility views ---------------------- # ------------------------------------------------------------------------ # The following properties provide backwards-compatible read-only views # matching the legacy ``Operator`` API (data, parameters, hyperparameters). # They are *not* the canonical Operator2 API — prefer ``arguments``, # ``dynamic_args``, ``static_args``, etc. for new code. _grad_recipe = None """Legacy Operator compatibility default for parameter-shift recipes.""" @property def grad_recipe(self): """Compute 'grad_recipe' lazily.""" if self._grad_recipe is None: return [None] * self.num_params return self._grad_recipe @grad_recipe.setter def grad_recipe(self, recipe): self._grad_recipe = recipe @property def grad_method(self): """Gradient computation method. * ``'A'``: analytic differentiation using the parameter-shift method. * ``'F'``: finite difference numerical differentiation. * ``None``: the operation may not be differentiated. Default is ``'F'``, or ``None`` if the Operation has zero parameters. """ # pylint: disable=import-outside-toplevel from pennylane.gradients import parameter_frequencies if self.num_params == 0: return None if self.grad_recipe != [None] * self.num_params: return GradMethod.ANALYTIC try: _ = parameter_frequencies(self) return GradMethod.ANALYTIC except ParameterFrequenciesUndefinedError: return GradMethod.FINITE_DIFF @property def data(self) -> tuple: """Legacy Operator compatibility view of dynamic numerical arguments.""" return tuple(self.arguments[name] for name in self.dynamic_argnames) @property def parameters(self) -> list: """Legacy Operator compatibility view of dynamic numerical arguments as a list.""" return list(self.data) @property def hyperparameters(self) -> dict: """Legacy Operator compatibility view of non-dynamic, non-wire constructor arguments.""" return { name: value for name, value in self.arguments.items() if name not in self.dynamic_argnames and name not in self.wire_argnames } # ------------------------------------------------------------------------ # --------------------------- Operator actions --------------------------- # ------------------------------------------------------------------------
[docs] def label( self, decimals: int | None = None, base_label: str | None = None, cache: dict | None = None ) -> str: r"""A customizable string representation of the operator. Args: decimals=None (int): If ``None``, no parameters are included. Else, specifies how to round the parameters. base_label=None (str): overwrite the non-parameter component of the label cache=None (dict): dictionary that carries information between label calls in the same drawing Returns: str: label to use in drawings **Example:** >>> op = qp.RX(1.23456, wires=0) >>> op.label() 'RX' >>> op.label(base_label="my_label") 'my_label' >>> op = qp.RX(1.23456, wires=0) >>> op.label() 'RX' >>> op.label(decimals=2) 'RX\n(1.23)' >>> op.label(base_label="my_label") 'my_label' >>> op.label(decimals=2, base_label="my_label") 'my_label\n(1.23)' Note that by default, operator wires and static inputs are not included in the label. To override this behaviour, ``Operator2`` subclasses must override the ``label`` method. If the operation has a matrix-valued parameter and a cache dictionary is provided, unique matrices will be cached in the ``'matrices'`` key list. The label will contain the index of the matrix in the ``'matrices'`` list. >>> op2 = qp.QubitUnitary(np.eye(2), wires=0) >>> cache = {'matrices': []} >>> op2.label(cache=cache) 'U\n(M0)' >>> cache['matrices'] [array([[1., 0.], [0., 1.]])] >>> op3 = qp.QubitUnitary(np.eye(4), wires=(0,1)) >>> op3.label(cache=cache) 'U\n(M1)' >>> cache['matrices'] [array([[1., 0.], [0., 1.]]), array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]])] """ op_label = base_label or self.__class__.__name__ if len(self.dynamic_argnames) == 0: return op_label # Format each parameter individually, excluding those that lead to empty strings param_strings = [ out for p in self.dynamic_args.values() if (out := _format_label_arg(p, decimals, cache)) != "" ] inner_string = ",\n".join(param_strings) if inner_string == "": return f"{op_label}" return f"{op_label}\n({inner_string})"
[docs] def pow(self, z: float) -> list["Operator2"]: """A list of new operators equal to this one raised to the given power. This method is used to simplify :class:`~.Pow` instances created by :func:`~.pow` or ``op ** power``. TODO: [sc-120843] Fix docstring after Pow is added ``Operator2.pow`` can be optionally defined by Operator developers, while :func:`~.pow` or ``op ** power`` are the entry point for constructing generic powers to exponents. Args: z (float): exponent for the operator Returns: list[:class:`~.core.operator.Operator2`] >>> from pennylane.core.operator import Operator2 >>> class MyClass(Operator2): ... dynamic_argnames = ("phi",) ... ... def __init__(self, phi, wires): ... super().__init__(phi, wires) ... ... def pow(self, z): ... return [MyClass(self.phi*z, self.wires)] ... >>> MyClass(0.5, 0).pow(2) [MyClass(1.0, wires=[0])] """ # Child methods may call super().pow(z%period) where op**period = I # For example, PauliX**2 = I, SX**4 = I. # Hence we define the non-negative integer cases here as a repeated list if z == 0: return [] if isinstance(z, int) and z > 0: if QueuingManager.recording(): return [apply(self) for _ in range(z)] return [copy(self) for _ in range(z)] raise PowUndefinedError
[docs] def queue(self, context: QueuingManager = QueuingManager): """Append the operator to the Operator queue.""" for h in self.hybrid_args.values(): leaves, _ = flatten(h, is_leaf=_is_op) _ = [context.remove(l) for l in leaves if isinstance(l, Operator)] context.append(self) # return self so pre-constructed Observables can be queued and returned in # a single statement return self
@classproperty @classmethod def has_adjoint(cls) -> bool: """Bool: Whether or not the Operator can compute its own adjoint. Note: Child classes may have this as an instance property instead of as a class property. """ return cls.adjoint != Operator2.adjoint
[docs] def adjoint(self) -> "Operator2": # pylint:disable=no-self-use """Create an operation that is the adjoint of this one. Used to simplify :class:`~.Adjoint` operators constructed by :func:`~.adjoint`. TODO: [sc-120844] Fix docstring after Adjoint is added Adjointed operations are the conjugated and transposed version of the original operation. Adjointed ops are equivalent to the inverted operation for unitary gates. ``Operator2.adjoint`` can be optionally defined by Operator developers, while :func:`~.adjoint` is the entry point for constructing generic adjoint representations. Returns: The adjointed operation. >>> from pennylane.core.operator import Operator2 >>> class MyClass(Operator2): ... dynamic_argnames = ("phi",) ... ... def __init__(self, phi, wires): ... super().__init__(phi, wires) ... ... def adjoint(self): ... return self ... >>> op = MyClass(0.5, wires=0).adjoint() >>> op MyClass(0.5, wires=[0]) """ raise AdjointUndefinedError
[docs] def map_wires(self, wire_map: dict[Hashable, Hashable]) -> "Operator2": """Returns a new operator with its wires changed according to the given wire map. Args: wire_map (dict): dictionary containing the old wires as keys and the new wires as values Returns: .Operator2: new operator """ new_args = dict(self.arguments) for n, wires in self.wire_args.items(): # Flattening/unflattening allows mapping hybrid wire arguments leaves, tree = flatten(wires, is_leaf=lambda w: isinstance(w, Wires)) mapped_leaves = [Wires([wire_map.get(w, w) for w in l]) for l in leaves] new_args[n] = unflatten(mapped_leaves, tree) for n, arg in self.hybrid_args.items(): if n in self.wire_argnames: continue leaves, tree = flatten(arg, is_leaf=_is_op) leaves = [l.map_wires(wire_map) if isinstance(l, Operator) else l for l in leaves] new_args[n] = unflatten(leaves, tree) return type(self)(**new_args)
[docs] def simplify(self) -> "Operator2": """Reduce the depth of nested operators to the minimum. Returns: .Operator2: simplified operator """ return self
# ------------------------------------------------------------------------ # ----------------------- Operator representations ----------------------- # ------------------------------------------------------------------------ # pylint: disable=unused-argument,comparison-with-callable,no-self-use
[docs] @staticmethod def compute_matrix(*args, **kwargs) -> TensorLike: """Representation of the operator as a canonical matrix in the computational basis (static method). The canonical matrix is the textbook matrix representation that does not consider wires. Implicitly, this assumes that the wires of the operator correspond to the global wire order. .. seealso:: :meth:`.Operator2.matrix` and :func:`qp.matrix() <pennylane.matrix>` Args: *args (tuple): Positional arguments of the operator **kwargs (dict): Keyword arguments of the operator Returns: tensor_like: matrix representation """ raise MatrixUndefinedError
@classproperty @classmethod def has_matrix(cls) -> bool: """Bool: Whether or not the Operator returns a defined matrix. Note: Child classes may have this as an instance property instead of as a class property. """ return cls.compute_matrix != Operator2.compute_matrix or cls.matrix != Operator2.matrix
[docs] def matrix(self, wire_order: WiresLike | None = None) -> TensorLike: """Representation of the operator as a matrix in the computational basis. If ``wire_order`` is provided, the numerical representation considers the position of the operator's wires in the global wire order. Otherwise, the wire order defaults to the operator's wires. If the matrix depends on trainable parameters, the result will be cast in the same autodifferentiation framework as the parameters. A ``MatrixUndefinedError`` is raised if the matrix representation has not been defined. .. seealso:: :meth:`~.Operator2.compute_matrix` Args: wire_order (Iterable): global wire order, must contain all wire labels from the operator's wires Returns: tensor_like: matrix representation """ canonical_matrix = self.compute_matrix(**self.arguments) return self._expand_canonical_matrix(canonical_matrix, wire_order)
def _expand_canonical_matrix(self, canonical_matrix, wire_order) -> TensorLike: if ( wire_order is None or self.wires == Wires(wire_order) or ( self.name in qp.ops.qubit.attributes.symmetric_over_all_wires and set(self.wires) == set(wire_order) ) ): return canonical_matrix return math.expand_matrix(canonical_matrix, wires=self.wires, wire_order=wire_order)
[docs] @staticmethod def compute_sparse_matrix(*args, format: str = "csr", **kwargs) -> spmatrix: """Representation of the operator as a sparse matrix in the computational basis (static method). The canonical matrix is the textbook matrix representation that does not consider wires. Implicitly, this assumes that the wires of the operator correspond to the global wire order. .. seealso:: :meth:`~.Operator2.sparse_matrix` Args: *args (tuple): Positional arguments of the operator format (str): format of the returned scipy sparse matrix, for example 'csr' **kwargs (dict): Keyword arguments of the operator Returns: scipy.sparse._csr.csr_matrix: sparse matrix representation """ raise SparseMatrixUndefinedError
@classproperty @classmethod def has_sparse_matrix(cls) -> bool: """Bool: Whether the Operator returns a defined sparse matrix. Note: Child classes may have this as an instance property instead of as a class property. """ return ( cls.compute_sparse_matrix != Operator2.compute_sparse_matrix or cls.sparse_matrix != Operator2.sparse_matrix )
[docs] def sparse_matrix(self, wire_order: WiresLike | None = None, format="csr") -> spmatrix: """Representation of the operator as a sparse matrix in the computational basis. If ``wire_order`` is provided, the numerical representation considers the position of the operator's wires in the global wire order. Otherwise, the wire order defaults to the operator's wires. A ``SparseMatrixUndefinedError`` is raised if the sparse matrix representation has not been defined. .. seealso:: :meth:`~.Operator2.compute_sparse_matrix` Args: wire_order (Iterable): global wire order, must contain all wire labels from the operator's wires format (str): format of the returned scipy sparse matrix, for example 'csr' Returns: scipy.sparse._csr.csr_matrix: sparse matrix representation """ canonical_sparse_matrix = self.compute_sparse_matrix(**self.arguments, format=format) return self._expand_canonical_matrix(canonical_sparse_matrix, wire_order).asformat(format)
[docs] @classmethod def compute_decomposition(cls, *args, **kwargs) -> list["Operator2"]: r"""Representation of the operator as a product of other operators (static method). .. math:: O = O_1 O_2 \dots O_n. .. note:: Operations making up the decomposition should be queued within the ``compute_decomposition`` method. .. seealso:: :meth:`~.Operator2.decomposition`. Args: *args (tuple): Positional arguments of the operator **kwargs (dict): Keyword arguments of the operator Returns: list[Operator2]: decomposition of the operator """ with pause(), QueuingManager.stop_recording(): # creating dummy op means this works for adjoint and ctrl too. op = cls(*args, **kwargs) for decomp in qp.list_decomps(op): if decomp.is_applicable(**op.arguments): with AnnotatedQueue() as q: decomp(**op.arguments) if QueuingManager.recording(): # no need for copies if we just use queue method _ = [op.queue() for op in q.queue] return q.queue raise DecompositionUndefinedError(f"No applicable decomposition rule for {cls}.")
@classproperty @classmethod def has_decomposition(cls) -> bool: """Bool: Whether or not the Operator returns a defined decomposition. This is a class-level check (no per-instance dispatch): ``True`` if ``compute_decomposition`` or ``decomposition`` is overridden, or if graph decomposition rules are registered for the operator type. Per-instance rule applicability is resolved in :meth:`~.Operator2.decomposition`, not here. """ # cant do cls.compute_decompsition != Operator2.compute_decomposition # because default is now a classmethod # classmethod is always different, even if not overwritten # cant do getattr(cls.compute_decomposition "__func__", cls.compute_decomposition) # because of an astroid/ pylint bug # see https://github.com/pylint-dev/pylint/issues/11198 # Instead, walk the MRO to detect an override in a subclass. # MRO = method resolution order determines who defines what methods def defines_compute_decomposition(op_type): for klass in op_type.__mro__: if klass is Operator2: return False if "compute_decomposition" in vars(klass): return True # should always find Operator2 in the mro msg = "This line should be impossible to hit. Something is wrong." # pragma: no cover raise TypeError(msg) # pragma: no cover return ( defines_compute_decomposition(cls) or cls.decomposition != Operator2.decomposition or qp.decomposition.has_decomp(cls) )
[docs] def decomposition(self) -> list["Operator2"]: r"""Representation of the operator as a product of other operators. .. math:: O = O_1 O_2 \dots O_n A ``DecompositionUndefinedError`` is raised if no representation by decomposition is defined. .. seealso:: :meth:`~.Operator2.compute_decomposition`. Returns: list[Operator2]: decomposition of the operator """ return self.compute_decomposition(**self.arguments)
[docs] @staticmethod def compute_eigvals(*args, **kwargs) -> TensorLike: r"""Eigenvalues of the operator in the computational basis (static method). If :attr:`diagonalizing_gates` are specified and implement a unitary :math:`U^{\dagger}`, the operator can be reconstructed as .. math:: O = U \Sigma U^{\dagger}, where :math:`\Sigma` is the diagonal matrix containing the eigenvalues. Otherwise, no particular order for the eigenvalues is guaranteed. .. seealso:: :meth:`Operator2.eigvals() <.eigvals>` and :func:`qp.eigvals() <pennylane.eigvals>` Args: *args (tuple): Positional arguments of the operator **kwargs (dict): Keyword arguments of the operator Returns: tensor_like: eigenvalues """ raise EigvalsUndefinedError
[docs] def eigvals(self) -> TensorLike: r"""Eigenvalues of the operator in the computational basis. If :attr:`diagonalizing_gates` are specified and implement a unitary :math:`U^{\dagger}`, the operator can be reconstructed as .. math:: O = U \Sigma U^{\dagger}, where :math:`\Sigma` is the diagonal matrix containing the eigenvalues. Otherwise, no particular order for the eigenvalues is guaranteed. .. note:: When eigenvalues are not explicitly defined, they are computed automatically from the matrix representation. Currently, this computation is *not* differentiable. A ``EigvalsUndefinedError`` is raised if the eigenvalues have not been defined and cannot be inferred from the matrix representation. .. seealso:: :meth:`~.Operator2.compute_eigvals` and :func:`qp.eigvals() <pennylane.eigvals>` Returns: tensor_like: eigenvalues """ try: return self.compute_eigvals(**self.arguments) except EigvalsUndefinedError as e: # By default, compute the eigenvalues from the matrix representation if one is defined. if self.has_matrix: # pylint: disable=using-constant-test return math.linalg.eigvals(self.matrix()) raise EigvalsUndefinedError from e
[docs] @staticmethod def compute_diagonalizing_gates(*args, **kwargs) -> list["Operator2"]: r"""Sequence of gates that diagonalize the operator in the computational basis (static method). Given the eigendecomposition :math:`O = U \Sigma U^{\dagger}` where :math:`\Sigma` is a diagonal matrix containing the eigenvalues, the sequence of diagonalizing gates implements the unitary :math:`U^{\dagger}`. The diagonalizing gates rotate the state into the eigenbasis of the operator. .. seealso:: :meth:`~.Operator2.diagonalizing_gates`. Args: *args (tuple): Positional arguments of the operator **kwargs (dict): Keyword arguments of the operator Returns: list[.Operator2]: list of diagonalizing gates """ raise DiagGatesUndefinedError
@classproperty @classmethod def has_diagonalizing_gates(cls) -> bool: """Bool: Whether or not the Operator returns defined diagonalizing gates. Note: Child classes may have this as an instance property instead of as a class property. """ # Operators may overwrite `diagonalizing_gates` instead of `compute_diagonalizing_gates` # Currently, those are mostly classes from the operator arithmetic module. return ( cls.compute_diagonalizing_gates != Operator2.compute_diagonalizing_gates or cls.diagonalizing_gates != Operator2.diagonalizing_gates )
[docs] def diagonalizing_gates(self) -> list["Operator2"]: r"""Sequence of gates that diagonalize the operator in the computational basis. Given the eigendecomposition :math:`O = U \Sigma U^{\dagger}` where :math:`\Sigma` is a diagonal matrix containing the eigenvalues, the sequence of diagonalizing gates implements the unitary :math:`U^{\dagger}`. The diagonalizing gates rotate the state into the eigenbasis of the operator. A ``DiagGatesUndefinedError`` is raised if no representation by decomposition is defined. .. seealso:: :meth:`~.Operator2.compute_diagonalizing_gates`. Returns: list[.Operator2] or None: a list of operators """ return self.compute_diagonalizing_gates(**self.arguments)
[docs] def terms(self) -> tuple[list[TensorLike], list["Operator2"]]: r"""Representation of the operator as a linear combination of other operators. .. math:: O = \sum_i c_i O_i A ``TermsUndefinedError`` is raised if no representation by terms is defined. Returns: tuple[list[tensor_like or float], list[.Operator2]]: list of coefficients :math:`c_i` and list of operations :math:`O_i` """ raise TermsUndefinedError
@classproperty @classmethod def has_generator(cls) -> bool: """Bool: Whether or not the Operator returns a defined generator. Note: Child classes may have this as an instance property instead of as a class property. """ return cls.generator != Operator2.generator
[docs] def generator(self) -> "Operator2": r"""Generator of an operator that is in single-parameter-form. For example, for operator .. math:: U(\phi) = e^{i\phi (0.5 Y + Z\otimes X)} we get the generator >>> U.generator() # doctest: +SKIP 0.5 * Y(0) + Z(0) @ X(1) The generator may also be provided in the form of a dense or sparse Hamiltonian (using :class:`.LinearCombination` and :class:`.SparseHamiltonian` respectively). """ raise GeneratorUndefinedError(f"Operation {self.name} does not have a generator")
# ------------------------------------------------------------------------ # ------------------------ General dunder methods ------------------------ # ------------------------------------------------------------------------ def __repr__(self) -> str: # NOTE: Handle special case for single wire non-parameteric # operators like 'repr(qp.X(wires=0)) = X(0)' non_wire_args = ( self.dynamic_argnames + self.static_argnames + self.compilable_argnames + self.hybrid_argnames ) if not non_wire_args and len(self.wire_argnames) == 1: wire_arg = self.arguments[self.wire_argnames[0]] if isinstance(wire_arg, Wires) and len(wire_arg) == 1: return f"{self.name}({wire_arg.tolist()[0]!r})" non_dyn_args = self.static_argnames + self.compilable_argnames + self.hybrid_argnames inputs = [] for key, value in self.arguments.items(): # Hybrid wire arguments. if key in self.wire_argnames and key in self.hybrid_argnames: leaves, tree = flatten(value, is_leaf=_is_wires) leaves = [w.tolist() if isinstance(w, Wires) else w for w in leaves] value = unflatten(leaves, tree) # Simplified repr for operators with only dynamic args is_dyn = key in self.dynamic_argnames and not non_dyn_args inputs.append(f"{value}" if is_dyn else f"{key}={value}") inputs = ", ".join(inputs) return f"{self.name}({inputs})" def __str__(self) -> str: if self.has_fixed_sig and self.is_fully_abstract: return self.name return repr(self) def __hash__(self) -> int: serialized_dynamic = tuple( _canonicalize_dynamic(self.arguments[d], self.name) for d in self.dynamic_argnames ) serialized_wires = tuple( self.arguments[w] for w in self.wire_argnames if w not in self.hybrid_argnames ) serialized_static = tuple(str(self.arguments[s]) for s in self.static_argnames) serialized_compilable = tuple(str(self.arguments[c]) for c in self.compilable_argnames) serialized_hybrid = [] if self.hybrid_argnames: # Imported lazily to avoid a circular import # pylint: disable=import-outside-toplevel from pennylane.decomposition.resources import CompressedResourceOp hashable_leaf_types = (AbstractWires, Operator, Wires, CompressedResourceOp) for h in self.hybrid_argnames: leaves, tree = flatten(self.arguments[h], is_leaf=_is_hash_leaf) ser_leaves = tuple( l if isinstance(l, hashable_leaf_types) else _canonicalize_dynamic(l) for l in leaves ) serialized_hybrid.append((ser_leaves, tree)) return hash( ( self.name, serialized_dynamic, serialized_wires, serialized_static, serialized_compilable, tuple(serialized_hybrid), ) ) def __eq__(self, other) -> bool: return qp.equal(self, other) def __copy__(self) -> "Operator2": cls = type(self) copied_op = cls.__new__(cls) for attr, value in vars(self).items(): setattr(copied_op, attr, value) return copied_op def __deepcopy__(self, memo) -> "Operator2": cls = type(self) copied_op = cls.__new__(cls) # The memo dict maps object ID to object, and is required by # the deepcopy function to keep track of objects it has already # deep copied. memo[id(self)] = copied_op for attr, value in vars(self).items(): setattr(copied_op, attr, deepcopy(value, memo)) return copied_op def __getattr__(self, name): # By default, all operator arguments are accessible as properties without needing # to manually add properties. However, these properties are created dynamically in # __init_subclass__. Pylint raises 'no-member' errors when trying to access these # dynamically added properties. This dunder method is added to circumvent the error. # Pylint does not raise the 'no-member' error for classes that contain __getattr__. # The catch is that 'no-member' errors will no longer be raised for values that are # _actually_ not present. # __getattr__ is a fallback called after an attribute is not found on an object, so, # unconditionally raising an AttributeError is exactly what would be expected anyway. raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'") # ------------------------------------------------------------------------ # ------------------ Operator arithmetic dunder methods ------------------ # ------------------------------------------------------------------------ def __add__(self, other: Operator | TensorLike) -> Operator: """The addition operation of Operator-Operator objects and Operator-scalar.""" if isinstance(other, Operator): return qp.sum(self, other, lazy=False) if isinstance(other, TensorLike): if not qp.math.is_tracer(other) and qp.math.allequal(other, 0): return self return qp.sum( self, qp.s_prod(scalar=other, operator=qp.Identity(self.wires), lazy=False), lazy=False, ) return NotImplemented __radd__ = __add__ def __mul__(self, other: TensorLike) -> Operator: """The scalar multiplication between scalars and Operators.""" if isinstance(other, TensorLike): return qp.s_prod(scalar=other, operator=self, lazy=False) return NotImplemented def __truediv__(self, other: TensorLike): """The division between an Operator and a number.""" if isinstance(other, TensorLike): return self.__mul__(1 / other) return NotImplemented __rmul__ = __mul__ def __matmul__(self, other: Operator) -> Operator: """The product operation between Operator objects.""" return qp.prod(self, other, lazy=False) if isinstance(other, Operator) else NotImplemented def __sub__(self, other: Operator | TensorLike) -> Operator: """The subtraction operation of Operator-Operator objects and Operator-scalar.""" if isinstance(other, Operator): return self + qp.s_prod(-1, other, lazy=False) if isinstance(other, TensorLike): return self + (qp.math.multiply(-1, other)) return NotImplemented def __rsub__(self, other: Operator | TensorLike) -> Operator: """The reverse subtraction operation of Operator-Operator objects and Operator-scalar.""" return -self + other def __neg__(self) -> Operator: """The negation operation of an Operator object.""" return qp.s_prod(scalar=-1, operator=self, lazy=False) def __pow__(self, other: TensorLike) -> Operator: r"""The power operation of an Operator object.""" if isinstance(other, TensorLike): return qp.pow(self, z=other) return NotImplemented # ---------------------------------------------------------------------------- # ------------------ Private utililities for initialization ------------------ # ---------------------------------------------------------------------------- def _flatten(self) -> FlatPytree: """Serialize the operation into dynamic and static components. Returns: data, metadata: The dynamic and static components. See ``Operator2._unflatten``. The dynamic component can be recursive and include other operators. The metadata **must** be hashable. If the static data contains a non-hashable component, then this method and ``Operator2._unflatten`` should be overridden to provide a hashable version of the static data. **Example:** >>> op = qp.PauliRot(1.5, "XY", wires=[0, 1]) >>> op._flatten() (([1.5], [Wires([0, 1])], []), ('XY',)) >>> qp.PauliRot._unflatten(*op._flatten()) PauliRot(theta=1.5, pauli_word=XY, wires=[0, 1]) """ # Sort dynamic data as dynamic_args, wire_args, hybrid_args dyn_args = [self._bound_args.arguments[d] for d in self.dynamic_argnames] wires = [self._bound_args.arguments[w] for w in self.wire_argnames] hybrid_args = [ self._bound_args.arguments[h] for h in self.hybrid_argnames if h not in self.wire_argnames ] leaves = (dyn_args, wires, hybrid_args) # Put static/compilable args in hashable_data hashable_argnames = self.static_argnames or self.compilable_argnames hashable_data = tuple(self._bound_args.arguments[name] for name in hashable_argnames) return leaves, hashable_data @classmethod def _unflatten(cls, data: Iterable[Any], metadata: Hashable): """Recreate an operation from its serialized format. Args: data: the dynamic component of the operation metadata: the static component of the operation. The output of ``Operator2._flatten`` and the class type must be sufficient to reconstruct the original operation with ``Operator2._unflatten``. **Example:** >>> op = qp.PauliRot(1.5, "XY", wires=[0, 1]) >>> op._flatten() (([1.5], [Wires([0, 1])], []), ('XY',)) >>> qp.PauliRot._unflatten(*op._flatten()) PauliRot(theta=1.5, pauli_word=XY, wires=[0, 1]) """ args = {} # Process dynamic data for name, value in zip(cls.dynamic_argnames, data[0], strict=True): args[name] = value for name, value in zip(cls.wire_argnames, data[1], strict=True): args[name] = value non_wire_hybrid_argnames = ( name for name in cls.hybrid_argnames if name not in cls.wire_argnames ) for i, name in enumerate(non_wire_hybrid_argnames): args[name] = data[2][i] # Process static data hashable_argnames = cls.static_argnames or cls.compilable_argnames for name, value in zip(hashable_argnames, metadata, strict=True): args[name] = value # NOTE: To prepare for lowering, JAX 0.7.1 will insert 'ArgInfo' placeholders # during the `jit_trace` pass in `stages.make_args_info`. This triggers # pre-mature unflattening even when just calling `make_jaxpr`. We manually populate # the "shell" operator with attributes created inside the constructor to ensure # correct behaviour # TODO: Remove this workaround once we support JAX > 0.7.1 as they fixed this in later versions if any(_is_pytree_placeholder(leaf) for leaf in flatten(args)[0]): return _create_hollow_operator(cls, args) with QueuingManager.stop_recording(), pause(): return cls(**args) def _check_batching(self): """Check if the expected numbers of dimensions of parameters coincides with the ones received and sets the ``_batch_size`` attribute. The check always passes and sets the ``_batch_size`` to ``None`` for the default ``Operator.ndim_params`` property but subclasses may overwrite it to define fixed expected numbers of dimensions, allowing to infer a batch size. """ self._batch_size = None dynamic_args = self.data ndims = tuple(math.ndim(arg) for arg in dynamic_args) if any(len(math.shape(arg)) >= 1 and math.shape(arg)[0] is None for arg in dynamic_args): # if the batch dimension is unknown, then skip the validation # this happens when a tensor with a partially known shape is passed, e.g. (None, 12), # typically during compilation of a function decorated with jax.jit return # pragma: no cover self._ndim_params = ndims if ndims != self.ndim_params: ndims_matches = [ (ndim == exp_ndim, ndim == exp_ndim + 1) for ndim, exp_ndim in zip(ndims, self.ndim_params, strict=True) ] if not all(correct or batched for correct, batched in ndims_matches): raise ValueError( f"{self.name}: wrong number(s) of dimensions in parameters. " f"Parameters with ndims {ndims} passed, {self.ndim_params} expected." ) first_dims = [ math.shape(arg)[0] for (_, batched), arg in zip(ndims_matches, dynamic_args, strict=True) if batched ] if not math.allclose(first_dims, first_dims[0]): raise ValueError( "Broadcasting was attempted but the broadcasted dimensions " f"do not match: {first_dims}." ) self._batch_size = first_dims[0] def _bind_primitive(self): """Bind the operator plxpr primitive.""" # Skip if program capture is disabled if not capture.enabled(): return # Substitute AbstractArray and AbstractWires for symbolic arrays. arguments = {k: _to_symbolic_array(v) for k, v in self.arguments.items()} positional_args = [arguments[d] for d in self.dynamic_argnames] # In _to_symbolic_array, we explicitly replace AbstractWires and AbstractArray # with bindings of the symbolic_array primitive. If the arguments still contain # instances of AbstractArray, it indicates that we're not in a tracing context, # in which case we can exit early. new_argument_leaves, _ = flatten(arguments) if any(isinstance(l, (AbstractArray, AbstractWires)) for l in new_argument_leaves): return wire_lens = [] pure_wire_argnames = (n for n in self.wire_argnames if n not in self.hybrid_argnames) for name in pure_wire_argnames: positional_args.extend(arguments[name]) wire_lens.append(len(arguments[name])) hybrid_lens, hybrid_trees = [], [] forward_mask = [] for name in self.hybrid_argnames: leaves, tree, mask = _process_bind_hybrid_arg( arguments[name], is_wire_arg=name in self.wire_argnames ) forward_mask.extend(mask) positional_args.extend(leaves) hybrid_lens.append(len(leaves)) hybrid_trees.append(tree) static_args = {} for name in self.static_argnames + self.compilable_argnames: # Pytree flattening is a simple way to make static arguments hashable value = self.arguments[name] leaves, tree = flatten(value) static_args[name] = (tuple(leaves), tree) res = operator_p.bind( *positional_args, op_cls=type(self), wire_lens=wire_lens, hybrid_lens=hybrid_lens, hybrid_trees=hybrid_trees, forward_mask=forward_mask, n_ctrls=0, adjoint=False, **static_args, ) # If we bind the primitive outside a tracing context but with program capture enabled, # `res`` will be a concrete operator, not an abstract tracer, so we don't save it. if math.is_tracer(res): self.tracer = res def __init_subclass__(cls: type["Operator2"], is_baseclass=False) -> None: cls._sig = signature(cls) OperatorRegistry()[cls.__name__] = cls if is_baseclass: return # Argnames setup for attr in ARGNAME_CATEGORIES: if isinstance(v := getattr(cls, attr), str): setattr(cls, attr, (v,)) _init_subclass_validate_argnames(cls) _init_subclass_arg_specs_setup(cls) _init_subclass_wire_sizes_setup(cls) _init_subclass_add_dynamic_properties(cls) register_pytree(cls, cls._flatten, cls._unflatten) for attr in ARGNAME_CATEGORIES: # enforce sorting by signature sorted_names = tuple(a for a in cls._sig.parameters if a in getattr(cls, attr)) setattr(cls, attr, sorted_names) if cls.has_fixed_sig: qp.decomposition.register_signature(cls)
# --------------------------------------------------------------------------------- # ------------------------- Operator registry helper ------------------------------ # --------------------------------------------------------------------------------- def get_op_class_by_name(name: str) -> type[Operator2]: """ Helper to get an operator class by name using a function call. Args: name (str): the name of the class to retrieve. Returns: The class with the provided name. **Example** .. code-block:: python from pennylane.core.operator import Operator2 class MyNamedOp(Operator2): static_argnames = ("label",) def __init__(self, label, wires): super().__init__(label, wires=wires) >>> from pennylane.core import get_op_class_by_name >>> get_op_class_by_name("MyNamedOp")("my-label", [0, 1]) MyNamedOp(label=my-label, wires=[0, 1]) """ return OperatorRegistry()[name] # --------------------------------------------------------------------------------- # ------------------------- Instance construction helpers ------------------------- # --------------------------------------------------------------------------------- def _init_wires(op: Operator2): """Initialize operator wires. * Union of all wire_argnames into _wires * Flatten pytree arguments and look for operators * Append operator argument wires to _wires """ # pylint: disable=protected-access all_algorithmic_wires = [] for wname, wsize in zip(op.wire_argnames, op.wire_sizes, strict=True): if wname not in op.hybrid_argnames: warg = op._bound_args.arguments[wname] canonical_wires = warg if isinstance(warg, AbstractWires) else Wires(warg) op._bound_args.arguments[wname] = canonical_wires if wsize is not None and len(canonical_wires) != wsize: raise ValueError( f"Incorrect number of wires for '{op.name}.{wname}'. Expected {wsize} " f"wires but got {len(canonical_wires)}." ) # Work wires are NOT included in the full wires list. if wname not in ("work_wires", "work_wire"): all_algorithmic_wires.append(canonical_wires) # Pytree wires handling else: leaves, _ = flatten(op._bound_args.arguments[wname], is_leaf=_is_wires) if not all(isinstance(l, (Wires, AbstractWires)) for l in leaves): raise ValueError( f"Hybrid wires argument '{wname}' is invalid. All leaf values must be " "cast to 'qp.wires.Wires'." ) # Work wires are NOT included in the full wires list. if wname not in ("work_wires", "work_wire"): all_algorithmic_wires.extend(leaves) for hname in op.hybrid_argnames: if hname in op.wire_argnames: continue leaves, _ = flatten(op._bound_args.arguments[hname], is_leaf=_is_op) ops = filter(_is_op, leaves) all_algorithmic_wires.extend(op.wires for op in ops) if any(isinstance(w, AbstractWires) and not w.shape_fixed for w in all_algorithmic_wires): raise ValueError("Operator2 instances must be constructed with wires of fixed length.") op._wires = Wires.all_wires(all_algorithmic_wires) def _init_arg_types(op: Operator2) -> None: """Validate the provided arguments against their expected type. This method only performs validation on operators if ``op.arg_specs`` is defined. """ # arg_specs not present or there are no arguments if not op.arg_specs: return for name, exp_type in op.arg_specs.items(): argval = op.arguments[name] if name in op.wire_argnames: # pragma: no cover # This branch is effectively unreachable since a mismatch between the actual # and expected length for a wire argument is validated in __init_wires. We will # only ever reach this branch if __validate_arg_types is called manually. if exp_type.shape_fixed: msg = f"Expected '{name}' to have length {len(exp_type)}, but got {argval}." assert len(exp_type) == len(argval), msg continue # Dynamic argument if isinstance(argval, (Number, list, tuple)): argval = np.array(argval) # If the argument is batched, compare the shape other than that batch dimension arg_shape = argval.shape if isinstance(argval, AbstractArray) else math.shape(argval) either_is_ellipsis = exp_type.shape is Ellipsis or arg_shape is Ellipsis is_broadcasted = False if either_is_ellipsis else len(arg_shape) > exp_type.ndim unbatched_shape = arg_shape[1:] if is_broadcasted else arg_shape argval_dtype = ( argval.dtype if isinstance(argval, AbstractArray) else math.get_dtype_name(argval) ) comparison_abstract_type = AbstractArray(unbatched_shape, np.dtype(argval_dtype)) # Check if either shape or dtype is not compatible if not exp_type.is_compatible_with(comparison_abstract_type): # Isolate if it's a pure dtype issue by comparing with a mock type that has the # expected shape but the actual dtype actual_dtype = argval_dtype if not exp_type.is_compatible_with(AbstractArray(exp_type.shape, actual_dtype)): raise ValueError( f"Parameter '{name}' does not match the operator's expected 'arg_specs' dtype. " f"Expected {exp_type.dtype} but received {actual_dtype}." ) # If dtype is fine, must be a shape mismatch broadcast_msg = " (non-broadcasting dimensions)" if is_broadcasted else "" raise ValueError( f"Parameter '{name}' does not match the operator's expected 'arg_specs' shape. " f"Expected {exp_type.shape}{broadcast_msg} but received {arg_shape}." ) # NOTE: If the argval is an abstract type, we wish to canonicalize it to the # spec in 'arg_specs' in order to have a single source of truth. if isinstance(argval, AbstractArray): new_argval = AbstractArray(arg_shape, exp_type.dtype) # pylint: disable=protected-access # FIX: Hacky way to set attribute of a frozen dataclass object.__setattr__(new_argval, "_weak_type", exp_type._weak_type) op.arguments[name] = new_argval # ------------------------------------------------------------------------------- # ----------------------- Subclass initialization helpers ----------------------- # ------------------------------------------------------------------------------- def _init_subclass_validate_argnames(cls: type[Operator2]) -> None: """Validate the values inside all ``**_argnames`` for an operator class.""" if (cls.hybrid_argnames or cls.static_argnames) and cls.compilable_argnames: raise TypeError( "Operators can only contain 'static_argnames' and 'hybrid_argnames', or " "'compilable_argnames', not both." ) # dynamic/wire/static/compilable argnames must be disjoint. seen: dict[str, str] = {} for group_name in ( "dynamic_argnames", "wire_argnames", "static_argnames", "compilable_argnames", ): for name in getattr(cls, group_name): if other := seen.get(name): raise TypeError( f"Argument '{name}' appears in both '{other}' and '{group_name}'; " "dynamic, wire, static, and compilable argnames must not overlap." ) seen[name] = group_name # hybrid_argnames may overlap with wire_argnames, but not with the others. hybrid = set(cls.hybrid_argnames) non_wire = {n for n, g in seen.items() if g != "wire_argnames"} if bad := hybrid & non_wire: raise TypeError( f"hybrid_argnames {bad} overlap with dynamic, static, or " "compilable argnames; hybrid_argnames may only overlap with wire_argnames." ) # Every named signature parameter must appear in at least one *_argnames. sig_params = set(cls._sig.parameters.keys()) # pylint: disable=protected-access if unclassified := sig_params - set(seen.keys()) - hybrid: raise TypeError( f"The following parameters of '{cls.__name__}' are not classified in " f"any argnames tuples: {unclassified}." ) def _init_subclass_arg_specs_setup(cls: type[Operator2]) -> None: """Set up ``arg_specs`` for ``Operator2`` subclasses.""" arg_specs = cls.arg_specs or {} argnames_in_specs = set(arg_specs.keys()) illegal_args_in_specs = set(cls.hybrid_argnames + cls.compilable_argnames + cls.static_argnames) traced_argnames = set(cls.dynamic_argnames + cls.wire_argnames) if illegal_argnames := argnames_in_specs & illegal_args_in_specs: raise TypeError( f"{cls.__name__}.arg_specs can only contain dynamic and wire " f"arguments, but got {illegal_argnames}." ) cls.has_fixed_sig = argnames_in_specs == traced_argnames and len(illegal_args_in_specs) == 0 for name, exp_type in arg_specs.items(): if isinstance(exp_type, _AbstractWireTypeFactory): raise TypeError( "'Wire' cannot be used on its own to represent a single wire, " "Use 'Wire[1]' instead." ) canonical_exp_type = exp_type if isinstance(exp_type, type) and issubclass(exp_type, Number): canonical_exp_type = AbstractArray((), exp_type) cls.arg_specs[name] = canonical_exp_type if not canonical_exp_type.shape_fixed: cls.has_fixed_sig = False def _init_subclass_wire_sizes_setup(cls: type[Operator2]) -> None: """Set up ``wire_sizes`` for ``Operator2`` subclasses.""" arg_specs = cls.arg_specs or {} if cls.wire_sizes is None: cls.wire_sizes = tuple( ( None if name not in arg_specs or not arg_specs[name].shape_fixed else len(arg_specs[name]) ) for name in cls.wire_argnames ) return if not isinstance(cls.wire_sizes, Sequence): cls.wire_sizes = (cls.wire_sizes,) if len(cls.wire_sizes) != len(cls.wire_argnames): raise TypeError("'wire_sizes' must have the same length as 'wire_argnames'.") for wname, wsize in zip(cls.wire_argnames, cls.wire_sizes, strict=True): # Hybrid wire arguments' entry in wire_sizes must always be ``None``. Hybrid arguments # can be arbitrary pytrees by design if wname in cls.hybrid_argnames and wsize is not None: raise TypeError( f"Expected wire_size == None for '{wname}' as it is a hybrid wire argument." ) if not ((isinstance(wsize, int) and wsize > 0) or wsize is None): raise TypeError( f"'{cls.__name__}.wire_sizes' is invalid. 'wire_sizes' must be a sequence " f"of positive integers or 'None' values, but got {cls.wire_sizes}." ) # If the wire argument is in arg_specs, the entries in arg_specs # and wire_sizes must match. Arbitrary number of wires is denoted by ``None`` and # ``-1`` in wire_sizes and arg_specs respectively. if (expected_type := arg_specs.get(wname, None)) is not None: if not expected_type.shape_fixed: # Dynamic wire count, wire_sizes must specify arbitrary wires (None) mismatch = wsize is not None else: # Fixed wire count: wire count must match size mismatch = len(expected_type) != wsize if mismatch: cname = cls.__name__ declared_num = len(expected_type) if expected_type.shape_fixed else -1 raise TypeError( f"Number of wires specified for '{wname}' does not match the declared " f"type in {cname}.arg_specs and {cname}.wire_sizes. Got " f"{declared_num} and {wsize} respectively." ) def _init_subclass_add_dynamic_properties(cls: type[Operator2]) -> None: """Create dynamic properties for an operator using its signature.""" # pylint: disable=protected-access for name in cls._sig.parameters: if not hasattr(cls, name): dyn_property = partial(_init_subclass_dynamic_property, name=name) setattr(cls, name, property(dyn_property)) def _init_subclass_dynamic_property(self: Operator2, name: str) -> Any: """Dynamic property for an argument called ``name``.""" # pylint: disable=protected-access if "_bound_args" in vars(self) and name in self._bound_args.arguments: return self._bound_args.arguments[name] raise AttributeError( f"'{type(self).__name__}' object has no attribute '{name}'." ) # pragma: no cover # ------------------------------------------------------------------------------- # --------------------------- Program capture helpers --------------------------- # ------------------------------------------------------------------------------- # pylint: disable=ungrouped-imports operator_p = QpPrimitive("operator") operator_p.prim_type = "operator" # pylint: disable=too-many-arguments,unused-argument @operator_p.def_impl def _op_impl( *all_args, op_cls, wire_lens, hybrid_lens, hybrid_trees, forward_mask, n_ctrls=0, n_ctrl_work_wires=0, ctrl_work_wire_type="borrowed", adjoint=False, **static_args, ): # NOTE: every explicit keyword above shadows an operator argname of the same name, so the # controlled-specific params injected by `ControlledOp2._bind_primitive` are namespaced # with a `ctrl_`/`n_ctrl_` prefix. Otherwise an operator declaring e.g. `work_wire_type` # as a static/compilable arg (`MultiControlledX`, `ControlledQubitUnitary`) would have its # own value swallowed here and silently replaced by the controlled default. args = {name: unflatten(*value) for name, value in static_args.items()} i = 0 for name in op_cls.dynamic_argnames: args[name] = all_args[i] i += 1 wire_lens_iter = iter(wire_lens) for name in op_cls.wire_argnames: if name not in op_cls.hybrid_argnames: len_ = next(wire_lens_iter) # TODO: impl is being used here for reconstruction while the interpreter itself is # under JAX tracing. Need to separate this logic from such scenario. For now, # we can use the fact that wires are always integers and cast them to int. args[name] = _to_int_wires(all_args[i : i + len_]) i += len_ # Reorder hybrid args such that hybrid wire args are first for name, len_, tree in zip(op_cls.hybrid_argnames, hybrid_lens, hybrid_trees, strict=True): leaves = all_args[i : i + len_] args[name] = unflatten(leaves, tree) i += len_ # `ControlledOp2._bind_primitive` appends control wires, control values, and work # wires (in that order) after the base op's own args, so they're consumed in the # same order here. if n_ctrls: control_wires = _to_int_wires(all_args[i : i + n_ctrls]) i += n_ctrls control_values = all_args[i : i + n_ctrls] i += n_ctrls work_wires = _to_int_wires(all_args[i : i + n_ctrl_work_wires]) i += n_ctrl_work_wires else: control_wires = control_values = work_wires = () op = type.__call__(op_cls, **args) if adjoint: op = type.__call__(qp.ops.op_math.Adjoint2, op) if n_ctrls: op = type.__call__( qp.ops.op_math.ControlledOp2, op, control_wires=control_wires, control_values=control_values, work_wires=work_wires, work_wire_type=ctrl_work_wire_type, ) return op @operator_p.def_abstract_eval def _op_aval(*_, **__): return AbstractOperator() def _is_pytree_placeholder(obj) -> bool: """Whether 'obj' is a sentinel placeholder that JAX substitutes for real pytree leaves.""" cls = type(obj) return cls.__name__ == "ArgInfo" and cls.__module__.partition(".")[0] == "jax" def _create_hollow_operator(cls, args) -> Operator2: """Create an operator instance with hollow values. This is needed if there is any sentinel placeholder that JAX substitutes for real pytree leaves. The values can be hollow because these placeholders are used temporarily and discarded. """ # pylint: disable=protected-access op = object.__new__(cls) op._bound_args = op._sig.bind(**args) op._pauli_rep = None op._wires = Wires([]) op._batch_size = _UNSET_BATCH_SIZE op._ndim_params = _UNSET_BATCH_SIZE op.tracer = None return op def _op_arg_forward_mask(op: Operator2) -> list[bool]: """Build ``forward_mask`` entries for an operator argument.""" op_leaves, _ = flatten(op, is_leaf=_is_wires) hybrid_mask = [] for op_leaf in op_leaves: if isinstance(op_leaf, Wires): hybrid_mask.extend([False] * len(op_leaf)) else: hybrid_mask.append(True) return hybrid_mask def _to_symbolic_array(value): if isinstance(value, AbstractWires): wire_array = [symbolic_array((), int) for _ in range(len(value))] if any(isinstance(w, AbstractArray) for w in wire_array): return value # if we're not in a tracing context, do nothing return wire_array if isinstance(value, AbstractArray): return symbolic_array(value.shape, value.dtype) leaves, struct = flatten(value) if struct == leaf: return value # return pytree leaves as is # before using unflatten to reconstruct the hybrid args which would bind new # operator primitives, we remove the old operator primitives from the program. _prune_op_primitives(value) new_leaves = [_to_symbolic_array(l) for l in leaves] return unflatten(new_leaves, struct) def _prune_op_primitives(value): partial_leaves, struct = flatten(value, is_leaf=_is_op) op_leaves = list(filter(_is_op, partial_leaves)) _ = pop_op_eqns(op_leaves) if struct != leaf: for l in op_leaves: _prune_op_primitives(l) def _process_bind_hybrid_arg(hybrid_val, is_wire_arg: bool) -> tuple[list, Any, list[bool]]: """Process a hybrid argument for binding an operator primitive.""" # We don't use is_leaf=_is_op because we're deliberately not supporting program # capture with legacy operators mixed with new operators partial_leaves, _ = flatten(hybrid_val, is_leaf=lambda h: isinstance(h, Operator2)) _ = pop_op_eqns(filter(_is_op, partial_leaves)) leaves, tree = flatten(hybrid_val) if is_wire_arg: return leaves, tree, [False] * len(leaves) hybrid_mask: list[bool] = [] for partial_leaf in partial_leaves: if isinstance(partial_leaf, Operator2): hybrid_mask.extend(_op_arg_forward_mask(partial_leaf)) else: hybrid_mask.append(False) return leaves, tree, hybrid_mask # ----------------------------------------------------------------------------- # --------------------------- Miscelleneous helpers --------------------------- # ----------------------------------------------------------------------------- def _format_label_arg(x, decimals, cache): """Format a scalar parameter or retrieve/store a matrix-valued parameter from/to cache, formatting its position in the cache as parameter string.""" if len(math.shape(x)) == 0: # Scalar case if decimals is None: return "" try: return format(math.toarray(x), f".{decimals}f") except ValueError: # pragma: no cover # If the parameter can't be displayed as a float return format(x) if cache is None or not isinstance(mat_cache := cache.get("matrices", None), list): # No caching; matrices are not printed out fully, so no printing of this parameter return "" # Retrieve matrix location in cache, or write the matrix to cache as new entry for i, mat in enumerate(mat_cache): if math.shape(x) == math.shape(mat) and math.allclose(x, mat): return f"M{i}" mat_num = len(mat_cache) mat_cache.append(x) return f"M{mat_num}" def _is_wires(val: Any) -> bool: """Check whether a value is a Wires object.""" return isinstance(val, Wires) def _is_op(val: Any) -> bool: """Check whether a value is an Operator (legacy or new).""" return isinstance(val, Operator) def _canonicalize_dynamic(d, op_name=None) -> Hashable: """Canonicalize dynamic data for hashing.""" def _mod_and_round(x, mod_val): if qp.math.asarray(x).dtype == bool: return x x = x if mod_val is None else qp.math.real(x) % mod_val return qp.math.round(x, 10) # Use qp.math.real to take the real part. We may get complex inputs for # example when differentiating holomorphic functions with JAX: a complex # valued QNode (one that returns qp.state) requires complex typed inputs. if op_name is not None and op_name in ("RX", "RY", "RZ", "PhaseShift", "Rot", "U1", "U2", "U3"): mod_val = 2 * np.pi elif op_name is not None and op_name in ("CRX", "CRY", "CRZ", "CRot"): # Rot(θ) ∈ SU(2) double-covers SO(3) via center {-I, I}, so θ ↦ θ+2π is global phase -I; # in CRot, -I becomes a relative phase on |1⟩, breaking 2π periodicity to 4π. mod_val = 4 * np.pi else: mod_val = None if isinstance(d, AbstractArray): return hash(d) # We stringify the data because arrays are unhashable return str(id(d) if math.is_tracer(d) else _mod_and_round(d, mod_val)) def _is_hash_leaf(l) -> bool: """Check whether a value is a pytree leaf for hashing. For the purpose of hashing, wires and operators are considered leaves.""" return _is_op(l) or _is_wires(l) def _is_abstract_array(arg): return isinstance(arg, (ShapedArray, AbstractArray, AbstractWires, AbstractQubit)) def _to_int_wires(wires): """Cast all wires to integers.""" if not wires: return Wires(wires) if all(_is_abstract_array(w) for w in wires): return AbstractWires(len(wires)) if any(_is_abstract_array(w) for w in wires): raise ValueError( "Operator instances cannot be constructed with a combination of both concrete" " wires and abstract values like ShapedArray, AbstractArray," " AbstractWires, AbstractQubits" ) return Wires(tuple(w if math.is_tracer(w) else int(w) for w in wires)) class _ArgType(Enum): """Enum to keep track of an arguments type.""" WIRES = auto() DYN = auto() HYBRID = auto() def _resolve_arg_kind(cls, name: str) -> _ArgType: """Resolves an arguments name to what kind of argument type it is.""" # Check hybrid first: hybrid args can also appear in wire_argnames # and must be treated as hybrid. if name in cls.hybrid_argnames: return _ArgType.HYBRID if name in cls.wire_argnames: return _ArgType.WIRES return _ArgType.DYN # pylint: disable=too-many-return-statements def _canonicalize_abstract_type(val, kind: _ArgType): """Canonicalizes the input into its abstract equivalent. Args: val (Any): The input value. kind (_ArgType): The argument's classification. - WIRES: Coerce the value to be an AbstractWires instance. - DYN: Flatten into a single, unified AbstractArray - HYBRID: Preserve the PyTree structure, mapping internal leaves to either AbstractWires or AbstractArray. """ if isinstance(val, (AbstractArray, AbstractWires)): return val if type(val).__name__ == "ShapedArray": # jax.core.ShapedArray return AbstractArray(val.shape, val.dtype) if isinstance(val, type) and issubclass(val, Number): return AbstractArray((), val) match kind: case _ArgType.WIRES: # abstractify expects a Wires object for wire-routing, so we sanitize it first return abstractify(Wires(val)) case _ArgType.DYN: # A sequence of types is not supported (i.e., [float, float, float]) # for dynamic args. Ambiguous how to canonicalize it generally. if isinstance(val, (list, tuple)) and any(_is_abstract_specifier(x) for x in val): raise NotImplementedError( "A sequence of types for a dynamic argument is not " "currently supported. Instead, please use the type " "specifiers found in pennylane.typing." ) # Ensure it behaves like a clean array/scalar leaf before abstractifying if math.is_tracer(val) or issparse(val): return abstractify(val) return abstractify(math.asarray(val)) case _ArgType.HYBRID: # Since abstractify natively handles PyTree recursion and leaves, # we can pass the entire structure straight through return abstractify(val) case _: # pragma: no cover raise ValueError(f"Unknown kind: '{kind}'") def _is_abstract_specifier(val): return isinstance(val, AbstractArray) or (isinstance(val, type) and issubclass(val, Number)) @abstractify.register(OperatorMeta) @QueuingManager.stop_recording() def _abstractify_operator_type(op_type: type[Operator2]) -> Operator2: """Abstractify a subclass of operator.""" if op_type.has_fixed_sig: return op_type(**op_type.arg_specs) raise TypeError( f"'{op_type.__name__}' must set 'arg_specs' and cover all dynamic and wire " "arguments with fixed abstract types to be abstractified." ) @abstractify.register(Operator2) @QueuingManager.stop_recording() def _abstractify_operator(op: Operator2) -> Operator2: """Abstractify an operator.""" if op.is_fully_abstract: return op op_cls = type(op) target_args = op_cls.dynamic_argnames + op_cls.hybrid_argnames + op_cls.wire_argnames new_args = dict(op.arguments) for name in target_args: kind = _resolve_arg_kind(op_cls, name) new_args[name] = _canonicalize_abstract_type(new_args[name], kind) return op_cls(**new_args) class StatePrepBase2(Operator2, is_baseclass=True): """An interface for state-prep operations.""" @abstractmethod def state_vector(self, wire_order: WiresLike | None = None) -> TensorLike: """ Returns the initial state vector for a circuit given a state preparation. Args: wire_order (Iterable): global wire order, must contain all wire labels from the operator's wires Returns: array: A state vector for all wires in a circuit """ # pylint: disable=unused-argument def label( self, decimals: int | None = None, base_label: str | None = None, cache: dict | None = None ) -> str: """The default label for a state prep operation.""" return base_label or "|Ψ⟩"