Source code for pennylane.templates.subroutines.arithmetic.left_classical_comparator

# 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.
"""Contains the LeftClassicalComparator template for performing an inequality
test of a quantum register and a classical integer."""

from pennylane import capture, compiler, math
from pennylane.control_flow import for_loop
from pennylane.core.operator import Operator2
from pennylane.decomposition import add_decomps, register_resources
from pennylane.ops import CNOT, X, cond
from pennylane.typing import AbstractArray, AbstractWires, Int, Wire
from pennylane.wires import Wires, WiresLike

from .temporary_and import Elbow


[docs] class LeftClassicalComparator(Operator2): r"""This operator performs an inequality test between a quantum register :math:`\lvert x\rangle` and a classical integer :math:`\mathrm{value}`, storing the result in a target qubit. The operator evaluates the following relation, given by the ``comparator="<"`` argument .. math:: \text{LeftClassicalComparator}_{<} \lvert x\rangle \lvert 0\rangle = \lvert x\rangle \lvert x < \mathrm{value}\rangle \text{ if comparator} = \text{'<'} The decomposition is based on the left block in Figure 6 in Appendix E of `Su et al. (2021) <https://arxiv.org/abs/2105.12767>`_, adapted for a classical constant. .. warning:: Note that the decomposition uses auxiliary wires and in order to clean them, one must apply the adjoint of this operator after using the target qubit. Args: x_wires (WiresLike): The wires that store the quantum integer :math:`x`. value (int): The classical integer to compare against. It must be non-negative and at most :math:`2^{n}`, where :math:`n` is the number of ``x_wires`` (the upper value :math:`2^{n}` is only allowed for the ``'<'`` and ``'>='`` comparators, for which the test is statically satisfied for every representable ``x``). target_wire (WiresLike): The wire that stores the value of the inequality test. work_wires (WiresLike): The auxiliary wires to use for the comparison. At least ``len(x_wires) - 1`` zeroed work wires should be provided. They are not returned in the zero state. comparator (str): The operator used in the inequality. Possible values are: ``'<'``, ``'<='``, ``'>='`` and ``'>'``. **Example** .. code-block:: python import pennylane as qp dev = qp.device("default.qubit") @qp.qnode(dev) def circuit(): qp.BasisState(qp.math.int_to_binary(3, 3), wires=[0, 1, 2]) qp.LeftClassicalComparator( x_wires=[0, 1, 2], value=2, target_wire=3, work_wires=[4, 5], comparator=">=", ) return qp.probs(wires=3) >>> print(circuit()) [0. 1.] """ wire_argnames = ("x_wires", "target_wire", "work_wires") dynamic_argnames = ("value",) compilable_argnames = ("comparator",) ndim_params = (0,) num_params = 0 # The integer threshold is dynamic but is not differentiable. arg_specs = { "value": Int, "x_wires": Wire[-1], "target_wire": Wire[1], "work_wires": Wire[-1], } def __init__( self, x_wires: WiresLike, value: int, target_wire: WiresLike, work_wires: WiresLike, comparator: str, ): # pylint: disable=too-many-arguments if math.shape(value) != (): raise ValueError("value must be a scalar integer.") if comparator not in ["<", "<=", ">=", ">"]: raise ValueError("Allowed values for 'comparator' are: '<', '<=', '>=' and '>'.") if isinstance(x_wires, AbstractWires): super().__init__(x_wires, value, target_wire, work_wires, comparator) return x_wires = Wires(x_wires) target_wire = Wires(target_wire) work_wires = Wires(work_wires) if len(work_wires) < len(x_wires) - 1: raise ValueError( f"At least {len(x_wires) - 1} work_wires are required, but only " f"{len(work_wires)} were provided. (x_wires={list(x_wires)}, " f"work_wires={list(work_wires)})" ) overlap = work_wires.intersection(target_wire) if overlap: raise ValueError( f"work_wires and target_wire must be disjoint, but share: {list(overlap)}. " f"(work_wires={list(work_wires)}, target_wire={list(target_wire)})" ) overlap = work_wires.intersection(x_wires) if overlap: raise ValueError( f"work_wires and x_wires must be disjoint, but share: {list(overlap)}. " f"(work_wires={list(work_wires)}, x_wires={list(x_wires)})" ) overlap = x_wires.intersection(target_wire) if overlap: raise ValueError( f"x_wires and target_wire must be disjoint, but share: {list(overlap)}. " f"(x_wires={list(x_wires)}, target_wire={list(target_wire)})" ) # The comparators ``"<"`` and ``">="`` accept the degenerate bound ``value == 2 ** n`` # (``x < 2 ** n`` is statically True for every representable ``x``); ``"<="`` / ``">"`` # add one internally, so their largest allowed input stays ``2 ** n - 1``. max_value = 2 ** len(x_wires) if comparator in ["<", ">="] else 2 ** len(x_wires) - 1 if ( not isinstance(value, AbstractArray) and not math.is_tracer(value) and not 0 <= value <= max_value ): raise ValueError( f"value must be less than or equal to {max_value} and non-negative for comparator " f"'{comparator}'. Got {value=} and {2 ** len(x_wires)=}." ) super().__init__(x_wires, value, target_wire, work_wires, comparator)
def _get_specific_bit(value, i): # returns the i-th bit of the binary representation of value in little endian convention. return (value >> i) & 1 def _left_classical_comparator_resources(x_wires, value, target_wire, work_wires, comparator, **_): """Return conservative worst-case gate counts without knowing the runtime threshold.""" # pylint: disable=unused-argument n = len(x_wires) # Count every conditional gate: two Xs for bit 0, four per remaining low bit, # and one for bit n. The final negation depends only on the comparator. return { Elbow: n - 1, CNOT: n, X: 4 * n - 1 + int(comparator in [">", ">="]), } @register_resources(_left_classical_comparator_resources, exact=False) def _left_classical_comparator(x_wires, value, target_wire, work_wires, comparator, **_): x_wires = x_wires[::-1] def _negate_output(): X(wires=target_wire) if comparator in ["<=", ">"]: value += 1 used_work_wires = Wires.all_wires([work_wires[: len(x_wires) - 1], target_wire]) bit = _get_specific_bit(value, 0) cond(bit, X)(wires=[x_wires[0]]) cond(bit, CNOT)(wires=[x_wires[0], used_work_wires[0]]) cond(bit, X)(wires=[x_wires[0]]) if compiler.active() or capture.enabled(): x_wires = math.array(x_wires, like="jax") used_work_wires = math.array(used_work_wires, like="jax") @for_loop(1, len(x_wires)) def _loop(i): bit = _get_specific_bit(value, i) cond(bit, X)(wires=[x_wires[i]]) cond(bit, X)(wires=[used_work_wires[i - 1]]) Elbow(wires=[used_work_wires[i - 1], x_wires[i], used_work_wires[i]]) cond(bit, X)(wires=[used_work_wires[i - 1]]) CNOT(wires=[used_work_wires[i - 1], used_work_wires[i]]) cond(bit, X)(wires=[x_wires[i]]) _loop() # pylint: disable=no-value-for-parameter # Degenerate bound: when the effective ``value`` equals ``2 ** len(x_wires)`` its # low ``n`` bits are all zero, so the bitwise core above computes the constant # ``x < 0`` (always False) rather than the intended "always True". Bit ``n`` of # ``value`` is set exactly in this case, so a single conditional ``X`` fixes the # target wire. bit_n = _get_specific_bit(value, len(x_wires)) cond(bit_n, X)(wires=[used_work_wires[len(x_wires) - 1]]) cond(comparator.startswith(">"), _negate_output)() add_decomps(LeftClassicalComparator, _left_classical_comparator)