Source code for pennylane.ops.op_math.pow2

# 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.

"""Defines the base class for the power of operators."""

from functools import reduce
from typing import Union, override

from scipy.linalg import fractional_matrix_power

import pennylane as qp
from pennylane import capture, math
from pennylane.capture.op_eqns import pop_op_eqns
from pennylane.core import Operator
from pennylane.core.apply import apply
from pennylane.core.operator import abstractify
from pennylane.decomposition.decomposition_rule import (
    DecompCollection,
    DecompositionRule,
    _get_registered_decomps,
    _list_decomps,
    get_fixed_decomp,
    register_condition,
    register_resources,
)
from pennylane.decomposition.resources import (
    AbstractOperatorLike,
    CompressedResourceOp,
    pow_resource_rep,
)
from pennylane.decomposition.symbolic_decomposition import is_integer
from pennylane.decomposition.utils import to_name
from pennylane.exceptions import (
    AdjointUndefinedError,
    DecompositionUndefinedError,
    PowUndefinedError,
    SparseMatrixUndefinedError,
)
from pennylane.ops._pauli_conversion import to_operator
from pennylane.ops.op_math import adjoint

from .adjoint import Adjoint
from .adjoint2 import Adjoint2
from .symbolicop2 import SymbolicOp2

_superscript = str.maketrans("0123456789.+-", "⁰¹²³⁴⁵⁶⁷⁸⁹⋅⁺⁻")


[docs] class Pow2(SymbolicOp2): """Symbolic operator denoting an operator raised to a power. Args: base (~.operation.Operator): the operator to be raised to a power z=1 (float): the exponent **Example** >>> sqrt_x = Pow2(qp.X(0), 0.5) >>> Pow2.compute_decomposition(qp.X(0), 0.5) [SX(0)] >>> qp.matrix(sqrt_x) array([[0.5+0.5j, 0.5-0.5j], [0.5-0.5j, 0.5+0.5j]]) >>> qp.matrix(qp.SX(0)) array([[0.5+0.5j, 0.5-0.5j], [0.5-0.5j, 0.5+0.5j]]) >>> qp.matrix(Pow2(qp.T(0), 1.234)) array([[1. +0.j , 0. +0.j ], [0. +0.j , 0.56...+0.8244...j]]) """ z: int | float wire_argnames = () hybrid_argnames = ("base",) static_argnames = ("z",) def __init__(self, base: Operator, z: float): super().__init__(base, z) if isinstance(z, int) and z > 0: if (base_pauli_rep := getattr(self.base, "pauli_rep", None)) and ( self.batch_size is None ): pr = base_pauli_rep for _ in range(z - 1): pr = pr @ base_pauli_rep self._pauli_rep = pr else: self._pauli_rep = None else: self._pauli_rep = None @override def _bind_primitive(self): pop_op_eqns((self.base,)) super()._bind_primitive() def __repr__(self): return ( f"({self.base})**{self.z}" if self.base.arithmetic_depth > 0 else f"{self.base}**{self.z}" ) @property @override def basis(self): # pylint: disable=missing-function-docstring return self.base.basis @property @override def name(self) -> str: return f"Pow({self.base.name})" @property @override def ndim_params(self): return self.base.ndim_params @property @override def data(self): return self.base.data @property @override def num_wires(self): """The number of wires this power op acts on.""" return self.base.num_wires
[docs] @override def label(self, decimals=None, base_label=None, cache=None): z_string = format(self.z).translate(_superscript) base_label = self.base.label(decimals, base_label, cache=cache) return ( f"({base_label}){z_string}" if self.base.arithmetic_depth > 0 else base_label + z_string )
@property @override def has_sparse_matrix(self) -> bool: return self.base.has_sparse_matrix and isinstance(self.z, int)
[docs] @staticmethod @override def compute_matrix(base, z): # pylint: disable=arguments-differ mat = qp.matrix(base) if isinstance(z, int): return math.linalg.matrix_power(mat, z) return fractional_matrix_power(mat, z)
[docs] @staticmethod @override def compute_sparse_matrix(base=None, z=0, format="csr"): # pylint: disable=arguments-differ if isinstance(z, int): base_matrix = base.compute_sparse_matrix(**base.arguments) return (base_matrix**z).asformat(format) raise SparseMatrixUndefinedError
@property @override def has_decomposition(self): # pylint: disable=arguments-differ,invalid-overridden-method if isinstance(self.z, int) and self.z > 0: return True try: self.base.pow(self.z) except PowUndefinedError: return False except Exception as e: # some pow methods cant handle a batched z if math.ndim(self.z) != 0: return False raise e return True
[docs] @staticmethod @override def compute_decomposition(base, z): # pylint: disable=arguments-differ try: return base.pow(z) except PowUndefinedError as e: if isinstance(z, int) and z > 0: return [apply(base) for _ in range(z)] # TODO: consider: what if z is an int and less than 0? # do we want Pow(base, -1) to be a "more fundamental" op raise DecompositionUndefinedError from e except Exception as e: raise DecompositionUndefinedError from e
@property @override def has_diagonalizing_gates(self): # pylint: disable=arguments-differ,invalid-overridden-method return self.base.has_diagonalizing_gates
[docs] @staticmethod @override def compute_diagonalizing_gates(base, z): # pylint: disable=arguments-differ,unused-argument 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 of an operator to a power is the same as the diagonalizing gates as the original operator. As we can see, .. math:: O^2 = U \Sigma U^{\dagger} U \Sigma U^{\dagger} = U \Sigma^2 U^{\dagger} This formula can be extended to inversion and any rational number. 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`. Args: base (~.Operation): the operator to be raised to a power z (int): the exponent Returns: list[.Operator] or None: a list of operators """ return base.diagonalizing_gates()
[docs] @override def eigvals(self): base_eigvals = self.base.eigvals() is_single_precision = math.get_dtype_name(base_eigvals) in ("float32", "complex64") complex_dtype = "complex64" if is_single_precision else "complex128" return math.cast(base_eigvals, complex_dtype) ** self.z
@property @override def has_generator(self): # pylint: disable=arguments-differ,invalid-overridden-method return self.base.has_generator
[docs] @override def generator(self): r"""Generator of an operator that is in single-parameter-form. The generator of a power operator is ``z`` times the generator of the base matrix. .. math:: U(\phi)^z = e^{i\phi (z G)} See also :func:`~.generator` """ return self.z * self.base.generator()
[docs] @override def pow(self, z): return [Pow2(base=self.base, z=self.z * z)]
@property @override def has_adjoint(self): # pylint: disable=arguments-differ,invalid-overridden-method return isinstance(self.z, int)
[docs] @override def adjoint(self): """Create an operation that is the adjoint of this one. Adjointed operations are the conjugated and transposed version of the original operation. Adjointed ops are equivalent to the inverted operation for unitary gates. .. warning:: The adjoint of a fractional power of an operator is not well-defined due to branch cuts in the power function. Therefore, an ``AdjointUndefinedError`` is raised when the power ``z`` is not an integer. The integer power check is a type check, so that floats like ``2.0`` are not considered to be integers. Returns: The adjointed operation. Raises: AdjointUndefinedError: If the exponent ``z`` is not of type ``int``. """ if isinstance(self.z, int): return Pow2(base=adjoint(self.base), z=self.z) raise AdjointUndefinedError( "The adjoint of Pow operators only is well-defined for integer powers." )
[docs] @override def simplify(self) -> Union["Pow", "Identity"]: from pennylane.ops.identity import Identity # pylint: disable=import-outside-toplevel # try using pauli_rep: if pr := self.pauli_rep: pr.prune() return to_operator(pr, identity_wires=self.wires) base = self.base if capture.enabled() else self.base.simplify() try: ops = base.pow(z=self.z) if not ops: return Identity(self.wires) if not capture.enabled(): ops = [op.simplify() for op in ops] return reduce(lambda nxt, acc: nxt @ acc, ops) if len(ops) > 1 else ops[0] except PowUndefinedError: return Pow2(base=base, z=self.z)
def _pow_abstract(op: AbstractOperatorLike | type[Operator], z: int | float = 1): op = abstractify(op) if isinstance(op, CompressedResourceOp): return pow_resource_rep(op.op_type, op.params, z) return qp.pow(op, z) @register_condition(lambda base, z, **_: is_integer(z) and z >= 0) @register_resources(lambda base, z: {abstractify(base): z}, name="repeat_base") def _pow_repeat_base(base, z): """Decompose the power of an operator by repeating the base operator. Assumes z is a non-negative integer.""" @qp.for_loop(0, z) def _loop(_): qp.apply(base) _loop() # pylint: disable=no-value-for-parameter @register_resources( lambda base, z: {qp.pow(abstractify(base.base), z * base.z): 1}, name="merge_powers" ) def _pow_merge_powers(base, z): """Decompose nested powers by combining them.""" qp.pow(base.base, z * base.z) def _pow_flip_adjoint_resources(base, z): # base class is adjoint, and the base of the base is the target class return {qp.adjoint(Pow2(base.base, z=z)): 1} @register_resources(_pow_flip_adjoint_resources, name="flip_adjoint") def _pow_flip_adjoint(base, z, **__): """Decompose the power of an adjoint by power to the base of the adjoint and then taking the adjoint of the power.""" adjoint(qp.pow(base.base, z)) def make_pow_decomp_with_period(period) -> DecompositionRule: """Make a decomposition rule for the power of an op that has a period.""" def _condition_fn(base, z): # pylint: disable=unused-argument return math.shape(z) == () and z % period != z def _pow_reduce_period_resources(base, z): z_mod_period = z % period if z_mod_period == 0: return {} if z_mod_period == 1: return {abstractify(base): 1} return {_pow_abstract(base, z_mod_period): 1} @register_condition(_condition_fn) @register_resources(_pow_reduce_period_resources, name="reduce_period") def _pow_reduce_period(base, z, **__): z_mod_period = z % period if z_mod_period == 1: apply(base) elif z_mod_period > 0 and z_mod_period != period: qp.pow(base, z_mod_period) return _pow_reduce_period pow_involutory = make_pow_decomp_with_period(2) def _pow_scale_angle_resources(base, z): # pylint: disable=unused-argument return {abstractify(base): 1} @register_resources(_pow_scale_angle_resources, name="scale_angle") def _pow_scale_angle(base, z): """Decompose the power of a general rotation operator by multiplying the power by the angle.""" # A rotation should only have 1 dynamic parameter assert len(base.dynamic_argnames) == 1 angle = tuple(base.dynamic_args.values())[0] qp.ops.functions.bind_new_parameters(base, (angle * z,)) @_list_decomps.register def _list_pow_decomps(op: Pow2) -> DecompCollection: abs_op = abstractify(op) # fixed_decomps would override everything. if fixed_rule := get_fixed_decomp(op): return DecompCollection([fixed_rule]) # special case of merging nested powers. if isinstance(abs_op.base, Pow2): return DecompCollection([_pow_merge_powers]) # special case that the base is an Adjoint. if isinstance(abs_op.base, (Adjoint, Adjoint2)): return DecompCollection([_pow_flip_adjoint]) # Custom decomposition rules registered specifically to the pow operator custom_rules = _get_registered_decomps(to_name(abs_op)) return custom_rules + [_pow_repeat_base] if is_integer(op.z) else custom_rules @to_name.register def _pow2_to_name(op: Pow2): return f"Pow({to_name(op.base)})"