Source code for pennylane.templates.subroutines.multix

# 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 MultiX template."""

import numpy as np
from scipy import sparse

from pennylane import capture, compiler, math
from pennylane.allocation import allocate
from pennylane.control_flow import for_loop
from pennylane.core.operator import Operator2
from pennylane.decomposition import add_decomps, register_condition, register_resources
from pennylane.decomposition.symbolic_decomposition import self_adjoint
from pennylane.ops import CNOT, Hadamard, PauliX, adjoint, cond
from pennylane.ops.op_math.controlled2 import flip_zero_control as flip_zero_control2
from pennylane.ops.op_math.pow2 import pow_involutory
from pennylane.ops.op_math.prod2 import _multi_temporary_and_all_ones
from pennylane.typing import AbstractArray, AbstractWires, Bool, TensorLike, Wire
from pennylane.wires import DynamicWire, Wires, WiresLike, is_abstract_qubit

from .arithmetic.temporary_and import TemporaryAND


[docs] class MultiX(Operator2): r""" Conditionally applies PauliX gates according to a non-empty bitstring. For a bitstring :math:`\mathbf{b} = (b_0, \ldots, b_{n-1})`, ``MultiX`` applies the operator .. math:: \operatorname{MultiX}(\mathbf{b}) = X^{b_0} \otimes X^{b_1} \otimes \cdots \otimes X^{b_{n-1}}, \qquad b_i \in \{0, 1\}, where :math:`X^0 = I` and :math:`X^1 = X`. The position of each bit corresponds to the wire at the same position in ``wires``. Args: bitstring (TensorLike): A one-dimensional Boolean array. Integer arrays containing only ``0`` or ``1`` entries are accepted and cast to Boolean. wires (WiresLike): The wires on which ``MultiX`` acts. The number of wires must match the length of ``bitstring``. **Examples** The bitstring ``[1, 0, 1]`` applies a :class:`~.PauliX` gate to the first and third wires. This can be seen directly from the decomposition: >>> import pennylane as qp >>> op = qp.MultiX([1, 0, 1], wires=["a", "b", "c"]) >>> op.decomposition() [X('a'), X('c')] Applying the same operation to :math:`|000\rangle` produces the computational basis state :math:`|101\rangle`: >>> dev = qp.device("default.qubit", wires=3) >>> @qp.qnode(dev) ... def circuit(): ... qp.MultiX([1, 0, 1], wires=range(3)) ... return qp.probs(wires=range(3)) >>> circuit() array([0., 0., 0., 0., 0., 1., 0., 0.]) """ dynamic_argnames = ("bitstring",) arg_specs = {"bitstring": Bool[-1], "wires": Wire[-1]} is_verified_hermitian = True grad_method = None def __init__(self, bitstring: TensorLike, wires: WiresLike) -> None: bitstring, wires = MultiX._canonicalize_validate_and_cast_inputs(bitstring, wires) super().__init__(bitstring, wires) @property def num_wires(self) -> int: """Return the number of wires on which the operation acts.""" return len(self.wires) @staticmethod def _canonicalize_inputs(bitstring: TensorLike, wires: WiresLike) -> tuple[TensorLike, Wires]: """Canonicalize the ``bitstring`` and ``wires`` arguments.""" if isinstance(bitstring, (list, tuple)): bitstring = math.array(bitstring) wires = Wires(wires) return bitstring, wires @staticmethod def _validate_inputs( bitstring: AbstractArray | TensorLike, wires: AbstractWires | WiresLike ) -> None: """Validate the bitstring's shape and values and its length relative to the wires.""" if math.ndim(bitstring) != 1: raise ValueError("The bitstring argument must be a one-dimensional array.") if len(wires) == 0: raise ValueError("The wires argument must contain at least one wire.") bitstring_length = math.shape(bitstring)[0] if bitstring_length != len(wires): raise ValueError("The bitstring and wires arguments must have equal lengths.") bitstring_dtype = ( bitstring.dtype if isinstance(bitstring, AbstractArray) else math.get_dtype_name(bitstring) ) is_bitstring_integer_or_bool = np.issubdtype(bitstring_dtype, np.integer) or np.issubdtype( bitstring_dtype, bool ) if not is_bitstring_integer_or_bool: raise ValueError("The bitstring must be an integer or boolean array.") is_bitstring_abstract = isinstance(bitstring, AbstractArray) or math.is_tracer(bitstring) if not is_bitstring_abstract: is_bitstring_binary = math.all(math.logical_or(bitstring == 0, bitstring == 1)) # is_bitstring_binary evaluates to True at least when all entries belong to (0, 1, False, True) if not is_bitstring_binary: raise ValueError( "The bitstring must contain only integer or boolean binary (0,1,False,True) values." ) @staticmethod def _canonicalize_validate_and_cast_inputs( bitstring: TensorLike, wires: WiresLike ) -> tuple[TensorLike, Wires]: """Runs the full pipeline for handling input the input arguments ``bitstring`` and ``wires`` arguments.""" # canonicalize (standardize formats/containers) bitstring, wires = MultiX._canonicalize_inputs(bitstring, wires) # validate (throw error if inputs have problems) MultiX._validate_inputs(bitstring, wires) # cast (convert bitstring to Boolean dtype) bitstring = ( Bool[len(bitstring)] if isinstance(bitstring, AbstractArray) else math.cast(bitstring, bool) ) return bitstring, wires
[docs] @staticmethod # pylint: disable-next=arguments-differ def compute_matrix(bitstring: TensorLike, wires: WiresLike) -> TensorLike: r""" Representation of the operator as a canonical matrix in the computational basis. Assumes the wire order is the order provided by ``wires``. Args: bitstring (TensorLike): A one-dimensional Boolean array. Integer arrays containing only ``0`` or ``1`` entries are accepted and cast to Boolean. wires (WiresLike): The wires on which ``MultiX`` acts. The number of wires must match the length of ``bitstring``. Returns: TensorLike: The canonical matrix representing ``MultiX(bitstring, wires)``. """ bitstring, wires = MultiX._canonicalize_validate_and_cast_inputs(bitstring, wires) # The local matrices are either identity or pauli_x matrices interface = math.get_interface(bitstring) identity = math.eye(2, like=interface) pauli_x = math.asarray(PauliX.compute_matrix(), like=interface) def _local_matrix(i): # helper function for computing the i-th local matrix according to the bitstring numerical_bit = math.cast(bitstring[i], int) return numerical_bit * pauli_x + (1 - numerical_bit) * identity # Here we require len(bitstring) >= 1 as validated on input above matrix = _local_matrix(0) for i in range(1, len(wires)): matrix = math.kron(matrix, _local_matrix(i)) return matrix
[docs] @staticmethod # pylint: disable-next=arguments-differ def compute_sparse_matrix( bitstring: TensorLike, wires: WiresLike, format: str = "csr" ) -> sparse.spmatrix: r""" Representation of the operator as a canonical sparse matrix in the computational basis. Args: bitstring (TensorLike): A one-dimensional Boolean array. Integer arrays containing only ``0`` or ``1`` entries are accepted and cast to Boolean. wires (WiresLike): The wires on which ``MultiX`` acts. The number of wires must match the length of ``bitstring``. format (str): Format of the returned SciPy sparse matrix, for example ``"csr"``. Returns: scipy.sparse.spmatrix: The canonical sparse matrix representing ``MultiX(bitstring, wires)``. """ # Example: MultiX([1,1], wires=[0,1]) is the operator X @ X # In the computational basis, X @ X performs the map # # |00>,|01>,|10>,|11> --- X @ X ---> |11>,|10>,|01>,|00> # # which just permutes the computational basis states. # The canonical matrix representation is therefore # [[0 0 0 1], # X @ X = [0 0 1 0], # [0 1 0 0], # [1 0 0 0]] # Note MultiX(bitstring) is always a permutation matrix sending |x> to |x (+) b> # where x = (x0, ..., xn-1) is a basis state and b = (b0, ..., bn-1) is the bitstring. # # The only indices (row,col) where the canonical matrix for MultiX(bitstring) contains # a non-zero entry of '1' are when the 'column index' is the bit-wise OR '^' between # the 'row index' and the provided 'bitstring'. Hence the operation below # flipped_states = bit_mask ^ basis_states # # Also note MultiX(bitstring) is not only Hermitian but symmetric meaning the canonical # matrix will equal its own transpose. # Therefore, row and column indices, respectively 'basis_states' and 'flipped_states', # can safely be considered interchangable. bitstring, wires = MultiX._canonicalize_validate_and_cast_inputs(bitstring, wires) dimension = 2 ** len(wires) bit_mask = sum(int(bit) << (len(wires) - index - 1) for index, bit in enumerate(bitstring)) basis_states = np.arange(0, dimension, 1, dtype=int) flipped_states = bit_mask ^ basis_states matrix = sparse.csr_matrix( (np.ones(dimension, dtype=int), (basis_states, flipped_states)), shape=(dimension, dimension), ) return matrix.asformat(format)
[docs] @staticmethod # pylint: disable-next=arguments-differ def compute_eigvals(bitstring: TensorLike, wires: WiresLike) -> TensorLike: r""" Eigenvalues of the operator. Args: bitstring (TensorLike): A one-dimensional Boolean array. Integer arrays containing only ``0`` or ``1`` entries are accepted and cast to Boolean. wires (WiresLike): The wires on which ``MultiX`` acts. The number of wires must match the length of ``bitstring``. Returns: TensorLike: The eigenvalues of ``MultiX(bitstring, wires)``. """ bitstring, wires = MultiX._canonicalize_validate_and_cast_inputs(bitstring, wires) interface = math.get_interface(bitstring) identity_eigvals = math.asarray([1, 1], like=interface) pauli_x_eigvals = math.asarray([1, -1], like=interface) def _local_eigvals(i): # helper function for computing the i-th local eigvals according to the bitstring numerical_bit = math.cast(bitstring[i], int) return numerical_bit * pauli_x_eigvals + (1 - numerical_bit) * identity_eigvals # Here we require len(bitstring) >= 1 as validated on input above eigvals = _local_eigvals(0) for i in range(1, len(wires)): eigvals = math.kron(eigvals, _local_eigvals(i)) return eigvals
[docs] @staticmethod # pylint: disable-next=arguments-differ def compute_diagonalizing_gates(bitstring: TensorLike, wires: WiresLike): r""" A sequence of local Hadamard gates that diagonalizes a sequence of local PauliX gates. Args: bitstring (TensorLike): A one-dimensional Boolean array. Integer arrays containing only ``0`` or ``1`` entries are accepted and cast to Boolean. wires (WiresLike): The wires on which ``MultiX`` acts. The number of wires must match the length of ``bitstring``. Returns: A Hadamard gate for each position in ``bitstring`` containing a 1. """ bitstring, wires = MultiX._canonicalize_inputs(bitstring, wires) MultiX._validate_inputs(bitstring, wires) return [Hadamard(wire) for i, wire in enumerate(wires) if bitstring[i]]
def __repr__(self) -> str: if not (isinstance(self.bitstring, AbstractArray) or isinstance(self.wires, AbstractWires)): return f"MultiX({math.cast(self.bitstring, int)}, wires={self.wires})" return super().__repr__()
[docs] def adjoint(self) -> "MultiX": """Return the adjoint of the operator.""" return MultiX(self.bitstring, wires=self.wires)
[docs] def pow(self, z: int | float) -> list[Operator2]: # Only encodes the involutive property: MultiX^2 = I return super().pow(z % 2)
# Resources function for MultiX def _multix_resources(bitstring: TensorLike, wires: WiresLike): # pylint: disable=unused-argument # The total number of PauliX gates used depends on the bitstring. # Specifically, sum(bitstring) gates are used by MultiX, not len(bitstring). # However, if bitstring is an AbstractArray, only the shape of bitstring is known. # Therefore, the resource count can only supply the *worst-case* scenario instead. # Hence why exact=False is used when registering the resource. return {PauliX: len(wires)} # Decomposition function for MultiX @register_resources(_multix_resources, exact=False) def _multix_decomposition(bitstring: TensorLike, wires: WiresLike) -> None: # Dynamically-allocated wires (``AbstractQubit`` handles, e.g. from ``qp.allocate``) cannot # be stacked into a numeric array for ``for_loop``-based dynamic indexing, so unroll instead # (``bitstring`` may still be traced data, indexed with a static index). Remove this fallback # once dynamic-wire indexing is supported (shortcut.com/story/129521). if any(is_abstract_qubit(w) or isinstance(w, DynamicWire) for w in wires): if compiler.active() or capture.enabled(): bitstring = math.array(bitstring, like="jax") for i, wire in enumerate(wires): cond(bitstring[i], PauliX)(wires=wire) return if compiler.active() or capture.enabled(): bitstring = math.array(bitstring, like="jax") wires = math.array(wires, like="jax") @for_loop(0, len(wires), 1) def locally_apply_paulix(i): cond(bitstring[i], PauliX)(wires=wires[i]) locally_apply_paulix() # pylint: disable=no-value-for-parameter add_decomps(MultiX, _multix_decomposition) add_decomps("Adjoint(MultiX)", self_adjoint) add_decomps("Pow(MultiX)", pow_involutory) def _controlled_multix_ladder_resources(base, control_wires, **_): # num_control_wires - 1 TemporaryAND gates to compute the AND ladder, as many to uncompute it, # and up to one CNOT per target wire (worst case, hence exact=False). num_control_wires = len(control_wires) return { TemporaryAND: num_control_wires - 1, adjoint(TemporaryAND(Wire[3])): num_control_wires - 1, CNOT: len(base.wires), } def _multix_ladder_fanout(base, control_wires, work_wires): """Computes ``AND(control_wires)`` into a single work wire with the ``TemporaryAND`` ladder in :func:`~._multi_temporary_and_all_ones`, fans that wire out with a ``CNOT`` to every set bit of ``base``, then uncomputes the ladder. Requires ``len(control_wires) - 1`` wires in ``work_wires``, all in the zero state.""" bitstring = base.bitstring wires = base.wires if compiler.active() or capture.enabled(): bitstring = math.array(bitstring, like="jax") num_needed = len(control_wires) - 1 target_wire = _multi_temporary_and_all_ones(control_wires, work_wires) def _apply_cnot(wire): CNOT(wires=[target_wire, wire]) if any( is_abstract_qubit(w) or isinstance(w, DynamicWire) for w in (*wires, *work_wires, *control_wires) ): for i, wire in enumerate(wires): cond(bitstring[i], _apply_cnot)(wire) else: wires = math.array(wires, like="jax") @for_loop(0, len(wires), 1) def _locally_apply_cnot(i): cond(bitstring[i], _apply_cnot)(wires[i]) _locally_apply_cnot() # pylint: disable=no-value-for-parameter # Uncompute the ladder. Rebuilt inline rather than via adjoint(_multi_temporary_and_all_ones)(), # since adjoint-of-a-qfunc doesn't support DynamicRegister arguments under capture. for i in range(num_needed - 1, 0, -1): adjoint(TemporaryAND)(wires=[work_wires[i - 1], control_wires[i + 1], work_wires[i]]) adjoint(TemporaryAND)(wires=[control_wires[0], control_wires[1], work_wires[0]]) def _controlled_multix_ladder_extra_work_wires(control_wires, work_wires, work_wire_type, **_): # Allocate only the shortfall beyond any zeroed work wires already supplied. num_needed = len(control_wires) - 1 num_available = len(work_wires) if work_wire_type == "zeroed" else 0 return {"zeroed": max(0, num_needed - num_available)} @register_condition(lambda control_wires, **_: len(control_wires) > 1 and not compiler.active()) @register_resources( _controlled_multix_ladder_resources, work_wires=_controlled_multix_ladder_extra_work_wires, exact=False, ) def _controlled_multix_ladder(base, control_wires, work_wires, work_wire_type, **_): """Controlled-``MultiX`` decomposition that loads the fanout through a single work wire holding ``AND(control_wires)``, rather than repeating the multi-control structure once per target wire. Uses as many of the caller-supplied zeroed work wires as needed, dynamically allocating the rest.""" num_needed = len(control_wires) - 1 available = list(work_wires[:num_needed]) if work_wire_type == "zeroed" else [] num_to_allocate = num_needed - len(available) with allocate(num_to_allocate, state="zero", restored=True) as allocated: _multix_ladder_fanout(base, control_wires, work_wires=available + list(allocated)) add_decomps("C(MultiX)", flip_zero_control2(_controlled_multix_ladder))