# Copyright 2018-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.
"""
This submodule defines a base class for composite operations.
"""
import abc
from collections.abc import Callable, Sequence
from functools import cached_property
from inspect import signature
import pennylane as qp
from pennylane import math
from pennylane.core.operator import Operator, Operator2
from pennylane.queuing import remove_from_program
from pennylane.typing import AbstractWires
from .composite import handle_recursion_error
# pylint: disable=too-many-instance-attributes,invalid-sequence-index
[docs]
class CompositeOp2(Operator2, is_baseclass=True):
"""A base class for operators that are composed of other operators.
Args:
operands: (tuple[~.operation.Operator]): a tuple of operators which will be combined.
The child composite operator should define the `_op_symbol` property
during initialization and define any relevant representations, such as
:meth:`~.operation.Operator.matrix` and :meth:`~.operation.Operator.decomposition`.
"""
wire_argnames = ()
_eigs = {} # cache eigen vectors and values like in qp.Hermitian
def __init__(self, operands: Sequence[Operator], _init_pauli_rep=None):
if any(isinstance(op, (qp.ops.MidMeasure, qp.ops.PauliMeasure)) for op in operands):
raise ValueError("Composite operators of mid-circuit measurements are not supported.")
super().__init__(**self._init_args)
self._operands = operands
self._hash = None
self._has_overlapping_wires = len(self.wires) < sum(len(op.wires) for op in operands)
if isinstance(self.wires, AbstractWires):
self._pauli_rep = None
else:
self._pauli_rep = (
self._build_pauli_rep() if _init_pauli_rep is None else _init_pauli_rep
)
remove_from_program(*operands)
# FIX: This is a temporary work-around. Long-term fix is to remove `_init_pauli_rep`
# from the constructor [sc-130145].
def _flatten(self):
(dyn_args, wires, hybrid_args), metadata = super()._flatten()
# Filter out _init_pauli_rep, replacing it with None for JAX compatibility
names = [h for h in self.hybrid_argnames if h not in self.wire_argnames]
hybrid_args = tuple(
None if name == "_init_pauli_rep" else arg
for name, arg in zip(names, hybrid_args, strict=True)
)
return (dyn_args, wires, hybrid_args), metadata
@property
def operands(self) -> Sequence[Operator]:
"""The operands of the composite operator."""
return self._operands
def __new__(cls, *args, **kwargs):
obj = super().__new__(cls)
# NOTE: If called without arguments (during a __copy__)
# skip signature binding as attributes will be restored
# during the copy.
if not args and not kwargs:
return obj
# The purpose of this function here is to intercept the argument passed to the
# constructor of the subclass and store it on the operator, so that in __init__,
# we can pass that along to the base Operator2.__init__, which expects the
# arguments to match the pre-defined signature of the subclass.
sig = signature(cls)
bound_args = sig.bind(*args, **kwargs)
bound_args.apply_defaults()
obj._init_args = bound_args.arguments
return obj
def __init_subclass__(cls, is_baseclass=False) -> None:
super().__init_subclass__(is_baseclass)
if cls.compute_diagonalizing_gates is CompositeOp2.compute_diagonalizing_gates:
def _compute_diagonalizing_gates(operands=(), _init_pauli_rep=None):
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:`~.Operator.compute_diagonalizing_gates`.
Returns:
list[.Operator] or None: a list of operators
"""
op = cls(operands, _init_pauli_rep)
remove_from_program(op)
diag_gates = []
for ops in op.overlapping_ops:
if len(ops) == 1:
diag_gates.extend(ops[0].diagonalizing_gates())
else:
tmp_sum = op.__class__(ops)
eigvecs = tmp_sum.eigendecomposition["eigvec"]
diag_gates.append(
qp.QubitUnitary(math.transpose(math.conj(eigvecs)), wires=tmp_sum.wires)
)
return diag_gates
cls.compute_diagonalizing_gates = staticmethod(_compute_diagonalizing_gates)
if cls.compute_eigvals is CompositeOp2.compute_eigvals:
@handle_recursion_error
# pylint: disable-next=unused-argument
def _compute_eigvals(operands=(), _init_pauli_rep=None):
"""Return the eigenvalues of the specified operator.
This method uses pre-stored eigenvalues for standard observables where
possible and stores the corresponding eigenvectors from the eigendecomposition.
Returns:
array: array containing the eigenvalues of the operator
"""
op = cls(operands, _init_pauli_rep)
remove_from_program(op)
eigvals = []
for ops in op.overlapping_ops:
if len(ops) == 1:
eigvals.append(
math.expand_vector(ops[0].eigvals(), list(ops[0].wires), list(op.wires))
)
else:
tmp_composite = op.__class__(ops)
eigvals.append(
math.expand_vector(
tmp_composite.eigendecomposition["eigval"],
list(tmp_composite.wires),
list(op.wires),
)
)
framework = math.get_deep_interface(eigvals)
eigvals = [math.asarray(ei, like=framework) for ei in eigvals]
return op._math_op(math.vstack(eigvals), axis=0) # pylint: disable=protected-access
cls.compute_eigvals = staticmethod(_compute_eigvals)
def __repr__(self):
return f" {self._op_symbol} ".join(
[f"({op})" if getattr(op, "arithmetic_depth", 0) > 0 else f"{op}" for op in self]
)
def __iter__(self):
"""Return the iterator over the underlying operands."""
return iter(self.operands)
def __getitem__(self, idx):
"""Return the operand at position ``idx`` of the composition."""
return self.operands[idx]
def __len__(self):
"""Return the number of operators in this composite operator"""
return len(self.operands)
@property
@abc.abstractmethod
def _op_symbol(self) -> str:
"""The symbol used when visualizing the composite operator"""
@property
def num_wires(self):
"""Number of wires the operator acts on."""
return len(self.wires)
@property
@handle_recursion_error
def is_fully_abstract(self):
return super().is_fully_abstract
@property
@handle_recursion_error
def num_params(self):
return sum(op.num_params for op in self)
@handle_recursion_error
def _check_batching(self):
self._ndim_params = tuple(dim for op in self for dim in op.ndim_params)
batch_sizes = {op.batch_size for op in self if op.batch_size is not None}
if len(batch_sizes) > 1:
raise ValueError(
"Broadcasting was attempted but the broadcasted dimensions "
f"do not match: {batch_sizes}."
)
self._batch_size = batch_sizes.pop() if batch_sizes else None
@property
def has_overlapping_wires(self) -> bool:
"""Boolean expression that indicates if the factors have overlapping wires."""
return self._has_overlapping_wires
@property
@abc.abstractmethod
def is_verified_hermitian(self):
"""This property determines if the composite operator is hermitian."""
# pylint: disable=arguments-renamed, invalid-overridden-method, arguments-differ
@property
@handle_recursion_error
def has_matrix(self):
return all(op.has_matrix for op in self)
@property
@handle_recursion_error
def data(self):
"""Create data property"""
return tuple(d for op in self for d in op.data)
@cached_property
def overlapping_ops(self) -> list[list[Operator]]:
"""Groups all operands of the composite operator that act on overlapping wires.
Returns:
List[List[Operator]]: List of lists of operators that act on overlapping wires. All the
inner lists commute with each other.
"""
groups = []
for op in self:
# For every op, find all groups that have overlapping wires with it.
i = 0
first_group_idx = None
while i < len(groups):
if first_group_idx is None and any(wire in op.wires for wire in groups[i][1]):
# Found the first group that has overlapping wires with this op
groups[i][1] = groups[i][1] + op.wires
first_group_idx = i # record the index of this group
i += 1
elif first_group_idx is not None and any(wire in op.wires for wire in groups[i][1]):
# If the op has already been added to the first group, every subsequent
# group that overlaps with this op is merged into the first group
ops, wires = groups.pop(i)
groups[first_group_idx][0].extend(ops)
groups[first_group_idx][1] = groups[first_group_idx][1] + wires
else:
i += 1
if first_group_idx is not None:
groups[first_group_idx][0].append(op)
else:
# Create new group
groups.append([[op], op.wires])
return [group[0] for group in groups]
@property
def eigendecomposition(self):
r"""Return the eigendecomposition of the matrix specified by the operator.
This method uses pre-stored eigenvalues for standard observables where
possible and stores the corresponding eigenvectors from the eigendecomposition.
It transforms the input operator according to the wires specified.
Returns:
dict[str, array]: dictionary containing the eigenvalues and the
eigenvectors of the operator.
"""
eigen_func = math.linalg.eigh if self.is_verified_hermitian else math.linalg.eig
if self not in self._eigs:
mat = self.matrix()
w, U = eigen_func(mat)
self._eigs[self] = {"eigvec": U, "eigval": w}
return self._eigs[self]
# pylint: disable-next=arguments-differ
@property
def has_diagonalizing_gates(self):
if self.has_overlapping_wires:
for ops in self.overlapping_ops:
# if any of the single ops doesn't have diagonalizing gates, the overall operator doesn't either
if len(ops) == 1 and not ops[0].has_diagonalizing_gates:
return False
# the lists of ops with multiple operators can be handled if there is a matrix
return self.has_matrix
return all(op.has_diagonalizing_gates for op in self)
[docs]
@handle_recursion_error
def label(self, decimals=None, base_label=None, cache=None):
r"""How the composite operator is represented in diagrams and drawings.
Args:
decimals (int): If ``None``, no parameters are included. Else,
how to round the parameters. Defaults to ``None``.
base_label (Iterable[str]): Overwrite the non-parameter component of the label.
Must be same length as ``operands`` attribute. Defaults to ``None``.
cache (dict): Dictionary that carries information between label calls
in the same drawing. Defaults to ``None``.
Returns:
str: label to use in drawings
**Example (using the Sum composite operator)**
>>> op = qp.S(0) + qp.X(0) + qp.Rot(1,2,3, wires=[1])
>>> op.label()
'𝓗'
"""
def _label(op, decimals, base_label, cache):
sub_label = op.label(decimals, base_label, cache)
return f"({sub_label})" if getattr(op, "arithmetic_depth", 0) > 0 else sub_label
if base_label is not None:
if isinstance(base_label, str) or len(base_label) != len(self):
raise ValueError(
"Composite operator labels require ``base_label`` keyword to be same length as operands."
)
return self._op_symbol.join(
_label(op, decimals, lbl, cache) for op, lbl in zip(self, base_label, strict=True)
)
return self._op_symbol.join(_label(op, decimals, None, cache) for op in self)
@classmethod
@abc.abstractmethod
def _sort(cls, op_list, wire_map: dict = None) -> list[Operator]:
"""Sort composite operands by their wire indices."""
@handle_recursion_error
def __hash__(self):
if self._hash is None:
self._hash = hash(
(str(self.name), str([hash(factor) for factor in self._sort(self.operands)]))
)
return self._hash
@property
@handle_recursion_error
def arithmetic_depth(self) -> int:
return 1 + max(getattr(op, "arithmetic_depth", 0) for op in self)
@property
@abc.abstractmethod
def _math_op(self) -> Callable:
"""The function used when combining the operands of the composite operator"""
[docs]
@handle_recursion_error
def map_wires(self, wire_map: dict):
# pylint:disable=protected-access
if self._init_pauli_rep:
rep = self._init_pauli_rep.map_wires(wire_map=wire_map)
else:
rep = None
new = self.__class__([op.map_wires(wire_map=wire_map) for op in self], rep)
return new
@abc.abstractmethod
def _build_pauli_rep(self):
"""The function to generate the pauli representation for the composite operator."""