Source code for pennylane.ops.op_math.change_op_basis

# Copyright 2018-2025 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 class for compute-uncompute patterns.
"""

import inspect
from collections import Counter, defaultdict
from collections.abc import Callable
from functools import reduce

from pennylane import capture, math
from pennylane.core import queuing
from pennylane.core.apply import apply
from pennylane.core.operator import Operator, Operator2, abstractify
from pennylane.decomposition import add_decomps, register_resources
from pennylane.exceptions import (
    DiagGatesUndefinedError,
    EigvalsUndefinedError,
    MatrixUndefinedError,
    SparseMatrixUndefinedError,
)
from pennylane.ops.op_math import adjoint, ctrl, prod
from pennylane.ops.op_math.adjoint import _adjoint_eager
from pennylane.ops.op_math.adjoint2 import _adjoint_abstract
from pennylane.ops.op_math.change_op_basis2 import ChangeOpBasis2
from pennylane.ops.op_math.controlled2 import _ctrl_abstract
from pennylane.pytrees import flatten, unflatten
from pennylane.typing import Wire

from .composite import CompositeOp, handle_recursion_error


def _validate_callable(func: Callable) -> None:
    """Validates that a callable has no unbound mandatory parameters."""
    sig = inspect.signature(func)

    for param in sig.parameters.values():
        # The function,
        #
        # def f(*args, **kwargs):
        #     pass
        #
        # technically doesn't have any required parameters.
        if param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
            continue

        # If param has no default we can early exit
        if param.default is inspect.Parameter.empty:
            raise TypeError(
                "change_op_basis requires that Callable inputs have no unbound mandatory parameters. Please use functools.partial to bind them."
            )


def _is_abstract_operator(op) -> bool:
    """Return whether ``op`` is an operator-valued JAX tracer."""
    return math.is_tracer(op) and isinstance(op.aval, capture.AbstractOperator)


def _convert_to_prod(op_or_func):
    if callable(op_or_func):
        _validate_callable(op_or_func)
        return prod(op_or_func)()
    if isinstance(op_or_func, Operator):
        return op_or_func
    raise TypeError(
        f"The parameters to change_op_basis must be Operator or Callable, not {type(op_or_func)}"
    )


[docs] def change_op_basis( compute_op: Operator | Callable, target_op: Operator | Callable, uncompute_op: Operator | Callable | None = None, ): """Construct an operator representing a compute-uncompute pattern. Args: compute_op (~.Operator or Callable): operator applied before the target target_op (~.Operator or Callable): operator applied in the changed basis uncompute_op (~.Operator or Callable or None): Operator applied after the target. If ``None`` (the default), the adjoint of ``compute_op`` is used. Returns: ~ops.op_math.ChangeOpBasis or ~ops.op_math.ChangeOpBasis2: the operator representing the compute-uncompute pattern Raises: TypeError: if an operand is not an operator or a supported callable .. note:: With program capture enabled, all operands must be operators. Use :func:`~.subcircuit` to turn a :class:`~.DecompositionRule` into an operator class, then pass an instance of that class. With program capture disabled, callables with no unbound mandatory parameters are also accepted (see below for details). .. seealso:: :func:`~.subcircuit`, :class:`~.ops.op_math.ChangeOpBasis`, :class:`~.ops.op_math.ChangeOpBasis2` **Example** Consider the following example involving a ``change_op_basis``. The compute-uncompute pattern is composed of a Quantum Fourier Transform (``QFT``), followed by a ``PhaseAdder``, and finally an inverse ``QFT``. .. code-block:: python import pennylane as qp from functools import partial dev = qp.device("default.qubit") @qp.qnode(dev) def circuit(): qp.H(0) qp.CNOT([1,2]) qp.ctrl( qp.change_op_basis(qp.QFT([1,2]), qp.PhaseAdder(1, x_wires=[1,2])), control=0 ) return qp.state() circuit2 = qp.transforms._tape_decompose(circuit, gate_set=qp.gate_sets.ROTATIONS_PLUS_CNOT, max_expansion=1) When this circuit is decomposed, the ``compute_op`` and ``uncompute_op`` are not controlled, resulting in a much more resource-efficient decomposition: >>> print(qp.draw(circuit2)()) 0: ──RZ(3.14)──RY(1.57)─╭GlobalPhase(-1.57)─────────╭●──────────────────────┤ ╭State 1: ─────────────────────├GlobalPhase(-1.57)─╭●─╭QFT─├PhaseAdder(1.00)─╭QFT†─┤ ├State 2: ─────────────────────╰GlobalPhase(-1.57)─╰X─╰QFT─╰PhaseAdder(1.00)─╰QFT†─┤ ╰State With program capture disabled, a callable can also be provided as an argument. The callable applies a series of operations and must have no unbound mandatory parameters. ``functools.partial`` can be used to bind any necessary parameters. .. code-block:: python def my_compute_op(a, reg1, reg2): qp.BasisState(np.zeros(len(reg2)), reg2) qp.QFT(reg1) qp.RX(a, reg1[0]) def my_target_op(wires): qp.PauliX(wires[0]) dev = qp.device("default.qubit") @qp.qnode(dev) def circuit(): # Use partial to absorb any input parameters compute = partial(my_compute_op, 0.1, [0], [1]) target = partial(my_target_op, [0]) qp.change_op_basis(compute, target) return qp.state() circuit3 = qp.transforms._tape_decompose(circuit, gate_set=qp.gate_sets.ROTATIONS_PLUS_CNOT, max_expansion=1) >>> print(qp.draw(circuit3)()) 0: ─╭RX(0.10)@QFT@|Ψ⟩──X─╭(RX(0.10)@QFT@|Ψ⟩)†─┤ ╭State 1: ─╰RX(0.10)@QFT@|Ψ⟩────╰(RX(0.10)@QFT@|Ψ⟩)†─┤ ╰State .. details:: :title: Program capture Instantiate a :func:`~.subcircuit` to use a quantum function as an operand: .. code-block:: python @qp.subcircuit(dynamic_argnames=("angle",)) @qp.register_resources({qp.H: 1, qp.RX: 1}) def Compute(angle, wires): qp.H(wires) qp.RX(angle, wires) qp.capture.enable() op = qp.change_op_basis(Compute(0.2, wires=0), qp.RZ(0.3, 0)) >>> isinstance(op, qp.ops.ChangeOpBasis2) True >>> qp.capture.disable() """ if capture.enabled(): operands = (compute_op, target_op) if uncompute_op is not None: operands += (uncompute_op,) for op in operands: if callable(op): raise TypeError( "change_op_basis does not support callables as inputs when using program " "capture. To create an operator from a quantum function, use qp.subcircuit." ) if not (isinstance(op, Operator) or _is_abstract_operator(op)): raise TypeError( "The parameters to change_op_basis must be of type Operator when using program " f"capture, not {type(op)}" ) compute, target, uncompute = compute_op, target_op, uncompute_op else: compute = _convert_to_prod(compute_op) target = _convert_to_prod(target_op) uncompute = _convert_to_prod(uncompute_op) if uncompute_op is not None else None if ( isinstance(compute, Operator2) and isinstance(target, Operator2) and (isinstance(uncompute, Operator2) or uncompute is None) ): return ChangeOpBasis2( compute, target, uncompute, ) return ChangeOpBasis(compute, target, uncompute)
[docs] class ChangeOpBasis(CompositeOp): """ Composite operator representing a compute-uncompute pattern of operators, which constitutes changing the basis in which an operator is applied. Args: compute_op (:class:`~.Operator`): A single operator or product that applies quantum operations. target_op (:class:`~.Operator`): A single operator or a product that applies quantum operations. uncompute_op (:class:`~.Operator`): A single operator or a product that applies quantum operations. Default is uncompute_op=qp.adjoint(compute_op). Returns: (Operator): Returns an Operator which is the change_op_basis of the provided Operators: compute_op, target_op, uncompute_op. .. note:: When a ``ChangeOpBasis`` operator is iterated over, its factors are iterated in the reverse order. This is to have a similar behaviour to ``Prod`` which applies its factors in reverse order. .. seealso:: :func:`~.change_op_basis` """ def __init__( self, compute_op: Operator, target_op: Operator, uncompute_op: Operator | None = None ): if uncompute_op is None: uncompute_op = adjoint(compute_op) super().__init__(uncompute_op, target_op, compute_op) def _flatten(self): return tuple(reversed(self.operands)), tuple() @classmethod # pylint: disable-next=arguments-differ def _primitive_bind_call(cls, compute_op, target_op, uncompute_op=None): if uncompute_op is None: uncompute_op = adjoint(compute_op) leaves, structure = flatten( (compute_op, target_op, uncompute_op), is_leaf=lambda x: isinstance(x, Operator) ) new_leaves = [] for leaf in leaves: if isinstance(leaf, Operator2): if leaf.tracer is None: leaf._bind_primitive() # pylint: disable=protected-access new_leaves.append(leaf if leaf.tracer is None else leaf.tracer) # The equation is now an input to the legacy primitive. Detach its tracer # so prebuilt operands can be reused in another trace. leaf.tracer = None elif isinstance(leaf, Operator): queuing.QueuingManager.remove(leaf) new_leaves.append(apply(leaf)) else: new_leaves.append(leaf) compute_op, target_op, uncompute_op = unflatten(new_leaves, structure) return cls._primitive.bind(compute_op, target_op, uncompute_op) resource_keys = frozenset({"compute_op", "target_op", "uncompute_op"}) has_matrix = False has_sparse_matrix = False _op_symbol = "@" _math_op = staticmethod(math.prod)
[docs] def matrix(self, wire_order=None): raise MatrixUndefinedError
[docs] def sparse_matrix(self, wire_order=None, format="csr"): raise SparseMatrixUndefinedError
[docs] def diagonalizing_gates(self): raise DiagGatesUndefinedError
[docs] def eigvals(self): raise EigvalsUndefinedError
@property @handle_recursion_error def resource_params(self): return { "compute_op": abstractify(self[2]), "target_op": abstractify(self[1]), "uncompute_op": abstractify(self[0]), } grad_method = None @classmethod def _sort(cls, op_list: list, wire_map: dict = None) -> list[Operator]: """ We do not sort the ops. The order is guaranteed to matter since if the compute operator and the base operator commute, the pattern would simplify to just being the base operator. Args: op_list (List[.Operator]): list of operators to be sorted wire_map (dict): Dictionary containing the wire values as keys and its indexes as values. Defaults to None. Returns: List[.Operator]: sorted list of operators """ return op_list @property def is_verified_hermitian(self): """Check if the product operator is hermitian. Note, this check is not exhaustive. There can be hermitian operators for which this check yields false, which ARE hermitian. So a false result only implies that a more explicit check must be performed. """ return self[1].is_verified_hermitian @property def has_decomposition(self): return True
[docs] def decomposition(self): r"""Decomposition of the product operator is given by each of compute_op, target_op, compute_op† applied in succession.""" if queuing.QueuingManager.recording(): _ = [apply(op) for op in reversed(self)] return list(self[::-1])
@property def has_adjoint(self): # pylint: disable=arguments-renamed,invalid-overridden-method return True
[docs] def adjoint(self): return ChangeOpBasis(*(_adjoint_eager(factor, update_queue=True) for factor in self))
def _build_pauli_rep(self): """PauliSentence representation of the Product of operations.""" if all(operand_pauli_reps := [op.pauli_rep for op in self.operands[::-1]]): return reduce(lambda a, b: a @ b, operand_pauli_reps) if operand_pauli_reps else None return None
def _change_op_basis_standard_resources(compute_op, target_op, uncompute_op): resources = Counter() resources[compute_op] += 1 resources[target_op] += 1 resources[uncompute_op] += 1 return resources def _adjoint_change_op_basis_standard_resources(base_params, **_): resources = defaultdict(int) resources[base_params["compute_op"]] += 1 resources[base_params["uncompute_op"]] += 1 target_op = base_params["target_op"] resources[_adjoint_abstract(target_op)] += 1 return resources @register_resources(_adjoint_change_op_basis_standard_resources, name="adjoint_target") def _adjoint_change_op_basis_standard(*_, base, **__): apply(base.operands[2]) adjoint(apply(base.operands[1])) apply(base.operands[0]) add_decomps("Adjoint(ChangeOpBasis)", _adjoint_change_op_basis_standard) # pylint: disable-next=too-many-arguments def _controlled_change_op_basis_standard_resources( *_, num_control_wires, num_zero_control_values, num_work_wires, work_wire_type, base_class, # pylint: disable=unused-argument base_params, **__, ): resources = defaultdict(int) resources[base_params["compute_op"]] += 1 resources[ _ctrl_abstract( base_params["target_op"], Wire[num_control_wires], Wire[num_work_wires], work_wire_type, num_zero_control_values, ) ] += 1 resources[base_params["uncompute_op"]] += 1 return resources @register_resources(_controlled_change_op_basis_standard_resources, name="control_target") def _controlled_change_op_basis_standard( *_, control_wires, control_values, work_wires, work_wire_type, base, **__, ): apply(base.operands[2]) ctrl( apply(base.operands[1]), control=control_wires, control_values=control_values, work_wires=work_wires, work_wire_type=work_wire_type, ) apply(base.operands[0]) @register_resources(_change_op_basis_standard_resources, name="expand_basis_change") def _change_op_basis_standard(*_, wires=None, operands, **__): # pylint: disable=unused-argument for op in operands[::-1]: apply(op) add_decomps(ChangeOpBasis, _change_op_basis_standard) add_decomps("C(ChangeOpBasis)", _controlled_change_op_basis_standard)