Source code for pennylane.core.pauli

# 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.
"""The Pauli arithmetic abstract reduced representation classes"""

# pylint: disable=protected-access


import warnings
from copy import copy
from functools import lru_cache, reduce

import numpy as np
from scipy import sparse

from pennylane import math
from pennylane.exceptions import PennyLaneDeprecationWarning
from pennylane.typing import TensorLike
from pennylane.wires import WireError, Wires

__all__ = ["PauliWord", "PauliSentence"]

matI = np.eye(2)
matX = np.array([[0, 1], [1, 0]])
matY = np.array([[0, -1j], [1j, 0]])
matZ = np.array([[1, 0], [0, -1]])

mat_map = {
    "I": matI,
    "X": matX,
    "Y": matY,
    "Z": matZ,
}

anticom_map = {
    "I": {"I": 0, "X": 0, "Y": 0, "Z": 0},
    "X": {"I": 0, "X": 0, "Y": 1, "Z": 1},
    "Y": {"I": 0, "X": 1, "Y": 0, "Z": 1},
    "Z": {"I": 0, "X": 1, "Y": 1, "Z": 0},
}


@lru_cache
def _cached_sparse_data(op):
    """Returns the sparse data and indices of a Pauli operator."""
    if op == "I":
        data = np.array([1.0, 1.0], dtype=np.complex128)
        indices = np.array([0, 1], dtype=np.int64)
    elif op == "X":
        data = np.array([1.0, 1.0], dtype=np.complex128)
        indices = np.array([1, 0], dtype=np.int64)
    elif op == "Y":
        data = np.array([-1.0j, 1.0j], dtype=np.complex128)
        indices = np.array([1, 0], dtype=np.int64)
    else:  # op == "Z"
        data = np.array([1.0, -1.0], dtype=np.complex128)
        indices = np.array([0, 1], dtype=np.int64)
    return data, indices


@lru_cache(maxsize=2)
def _cached_arange(n):
    "Caches `np.arange` output to speed up sparse calculations."
    return np.arange(n)


pauli_to_sparse_int = {"I": 0, "X": 1, "Y": 1, "Z": 0}  # (I, Z) and (X, Y) have the same sparsity


def _ps_to_sparse_index(pauli_words, wires):
    """Represent the Pauli words sparse structure in a matrix of shape n_words x n_wires."""
    indices = np.zeros((len(pauli_words), len(wires)))
    for i, pw in enumerate(pauli_words):
        if not pw.wires:
            continue
        wire_indices = np.array(wires.indices(pw.wires))
        indices[i, wire_indices] = [pauli_to_sparse_int[pw[w]] for w in pw.wires]
    return indices


_map_I = {
    "I": (1, "I"),
    "X": (1, "X"),
    "Y": (1, "Y"),
    "Z": (1, "Z"),
}
_map_X = {
    "I": (1, "X"),
    "X": (1, "I"),
    "Y": (1.0j, "Z"),
    "Z": (-1.0j, "Y"),
}
_map_Y = {
    "I": (1, "Y"),
    "X": (-1.0j, "Z"),
    "Y": (1, "I"),
    "Z": (1j, "X"),
}
_map_Z = {
    "I": (1, "Z"),
    "X": (1j, "Y"),
    "Y": (-1.0j, "X"),
    "Z": (1, "I"),
}

mul_map = {"I": _map_I, "X": _map_X, "Y": _map_Y, "Z": _map_Z}


[docs] class PauliWord(dict): r""" Immutable dictionary used to represent a Pauli Word, associating wires with their respective operators. Can be constructed from a standard dictionary. .. note:: An empty :class:`~.PauliWord` will be treated as the multiplicative identity (i.e identity on all wires). Its matrix is the identity matrix (trivially the :math:`1\times 1` one matrix when no ``wire_order`` is passed to ``PauliWord({}).to_mat()``). **Examples** Initializing a Pauli word: >>> w = PauliWord({"a": 'X', 2: 'Y', 3: 'Z'}) >>> w X(a) @ Y(2) @ Z(3) When multiplying Pauli words together, we obtain a :class:`~PauliSentence` with the resulting ``PauliWord`` as a key and the corresponding coefficient as its value. >>> w1 = PauliWord({0:"X", 1:"Y"}) >>> w2 = PauliWord({1:"X", 2:"Z"}) >>> w1 @ w2 -1j * X(0) @ Z(1) @ Z(2) We can multiply scalars to Pauli words or add/subtract them, resulting in a :class:`~PauliSentence` instance. >>> 0.5 * w1 - 1.5 * w2 + 2 0.5 * X(0) @ Y(1) + -1.5 * X(1) @ Z(2) + 2 * I """ __slots__ = ("_hashval",) # this allows scalar multiplication from left with numpy arrays np.array(0.5) * pw1 # taken from [stackexchange](https://stackoverflow.com/questions/40694380/forcing-multiplication-to-use-rmul-instead-of-numpy-array-mul-or-byp/44634634#44634634) __array_priority__ = 1000 def __missing__(self, key): """If the wire is not in the Pauli word, then no operator acts on it, so return the Identity.""" return "I" def __init__(self, mapping, _skip_filter=False): """Strip identities from PauliWord on init!""" if _skip_filter: super().__init__(mapping) else: super().__init__(filter(lambda item: item[1] != "I", mapping.items())) self._hashval = None @property def pauli_rep(self): """Trivial pauli_rep""" return PauliSentence({self: 1.0}) def __reduce__(self): """Defines how to pickle and unpickle a PauliWord. Otherwise, un-pickling would cause __setitem__ to be called, which is forbidden on PauliWord. For more information, see: https://docs.python.org/3/library/pickle.html#object.__reduce__ """ return (PauliWord, (dict(self),)) def __copy__(self): """Copy the PauliWord instance.""" res = PauliWord(self, _skip_filter=True) res._hashval = self._hashval return res def __deepcopy__(self, memo): res = self.__copy__() memo[id(self)] = res return res def __setitem__(self, key, item): """Restrict setting items after instantiation.""" raise TypeError("PauliWord object does not support assignment")
[docs] def update(self, __m, **kwargs) -> None: """Restrict updating PW after instantiation.""" raise TypeError("PauliWord object does not support assignment")
def __hash__(self): # NOTE: `lru_cache` and related methods can't be used here since they rely on a hash value existing if self._hashval is None: self._hashval = hash(frozenset(self.items())) return self._hashval def _matmul(self, other): """Private matrix multiplication that returns (pauli_word, coeff) tuple for more lightweight processing""" base, iterator, swapped = ( (self, other, False) if len(self) >= len(other) else (other, self, True) ) result = dict(base) coeff = 1 for wire, term in iterator.items(): if wire in base: factor, new_op = mul_map[term][base[wire]] if swapped else mul_map[base[wire]][term] if new_op == "I": del result[wire] else: coeff *= factor result[wire] = new_op elif term != "I": result[wire] = term return PauliWord(result), coeff def __matmul__(self, other): """Multiply two Pauli words together using the matrix product if wires overlap and the tensor product otherwise. Empty Pauli words are treated as the Identity operator on all wires. Args: other (PauliWord): The Pauli word to multiply with Returns: PauliSentence: coeff * new_word """ if isinstance(other, PauliSentence): return PauliSentence({self: 1.0}) @ other new_word, coeff = self._matmul(other) return PauliSentence({new_word: coeff}) def __mul__(self, other): """Multiply a PauliWord by a scalar Args: other (Scalar): The scalar to multiply the PauliWord with Returns: PauliSentence """ if isinstance(other, TensorLike): if not math.ndim(other) == 0: raise ValueError( f"Attempting to multiply a PauliWord with an array of dimension {math.ndim(other)}" ) return PauliSentence({self: other}) raise TypeError( f"PauliWord can only be multiplied by numerical data. Attempting to multiply by {other} of type {type(other)}" ) __rmul__ = __mul__ def __add__(self, other): """Add PauliWord instances and scalars to PauliWord. Returns a PauliSentence.""" # Note that the case of PauliWord + PauliSentence is covered in PauliSentence if isinstance(other, PauliWord): if other == self: return PauliSentence({self: 2.0}) return PauliSentence({self: 1.0, other: 1.0}) if isinstance(other, TensorLike): # Scalars are interepreted as scalar * Identity IdWord = PauliWord({}) if IdWord == self: return PauliSentence({self: 1.0 + other}) return PauliSentence({self: 1.0, IdWord: other}) return NotImplemented __radd__ = __add__ def __iadd__(self, other): """Inplace addition""" return self + other def __sub__(self, other): """Subtract other PauliSentence, PauliWord, or scalar""" return self + -1 * other def __rsub__(self, other): """Subtract other PauliSentence, PauliWord, or scalar""" return -1 * self + other def __truediv__(self, other): """Divide a PauliWord by a scalar""" if isinstance(other, TensorLike): return self * (1 / other) raise TypeError( f"PauliWord can only be divided by numerical data. Attempting to divide by {other} of type {type(other)}" )
[docs] def commutes_with(self, other): """Fast check if two PauliWords commute with each other""" wires = set(self) & set(other) if not wires: return True anticom_count = sum(anticom_map[self[wire]][other[wire]] for wire in wires) return (anticom_count % 2) == 0
def _commutator(self, other): """comm between two PauliWords, returns tuple (new_word, coeff) for faster arithmetic""" # This may be helpful to developers that need a more lightweight comm between pauli words # without creating PauliSentence classes if self.commutes_with(other): return PauliWord({}), 0.0 new_word, coeff = self._matmul(other) return new_word, 2 * coeff
[docs] def commutator(self, other): """ Compute commutator between a ``PauliWord`` :math:`P` and other operator :math:`O` .. math:: [P, O] = P O - O P When the other operator is a :class:`~PauliWord` or :class:`~PauliSentence`, this method is faster than computing ``P @ O - O @ P``. It is what is being used in :func:`~commutator` when setting ``pauli=True``. Args: other (Union[PauliWord, PauliSentence]): Second Pauli word or sentence Returns: ~PauliSentence: The commutator result in form of a :class:`~PauliSentence` instances. **Examples** You can compute commutators between :class:`~PauliWord` instances. >>> pw = PauliWord({0:"X"}) >>> pw.commutator(PauliWord({0:"Y"})) 2j * Z(0) Use :func:`~pennylane.commutator` for other operator types with a Pauli representation. >>> qp.commutator(pw, qp.Y(0), pauli=True) 2j * Z(0) """ if isinstance(other, PauliWord): new_word, coeff = self._commutator(other) if coeff == 0: return PauliSentence({}) return PauliSentence({new_word: coeff}) if isinstance(other, PauliSentence): # for infix method, this would be handled by __ror__ return -1.0 * other.commutator(self) raise NotImplementedError( "PauliWord.commutator accepts only PauliWord or PauliSentence inputs. " "Use qp.commutator(self, other, pauli=True) for operators." )
def __str__(self): """String representation of a PauliWord.""" if len(self) == 0: return "I" return " @ ".join(f"{op}({w})" for w, op in self.items()) def __repr__(self): """Terminal representation for PauliWord""" return str(self) @property def wires(self): """Track wires in a PauliWord.""" return Wires(self)
[docs] def to_mat(self, wire_order=None, format="dense", coeff=1.0): """Returns the matrix representation. Keyword Args: wire_order (iterable or None): The order of qubits in the tensor product. format (str): The format of the matrix. It is "dense" by default. Use "csr" for sparse. coeff (float): Coefficient multiplying the resulting matrix. Returns: (Union[NumpyArray, ScipySparseArray]): Matrix representation of the Pauli word. Raises: ValueError: Can't get the matrix of an empty PauliWord. """ wire_order = self.wires if wire_order is None else Wires(wire_order) if not wire_order.contains_wires(self.wires): raise ValueError( "Can't get the matrix for the specified wire order because it " f"does not contain all the Pauli word's wires {self.wires}" ) if len(self) == 0: n = len(wire_order) if wire_order is not None else 0 return ( np.diag([coeff] * 2**n) if format == "dense" else coeff * sparse.eye(2**n, format=format, dtype="complex128") ) if format == "dense": return coeff * reduce(math.kron, (mat_map[self[w]] for w in wire_order)) return self._to_sparse_mat(wire_order, coeff)
def _to_sparse_mat(self, wire_order, coeff): """Compute the sparse matrix of the Pauli word times a coefficient, given a wire order. See pauli_sparse_matrices.md for the technical details of the implementation.""" matrix_size = 2 ** len(wire_order) matrix = sparse.csr_matrix((matrix_size, matrix_size), dtype="complex128") # Avoid checks and copies in __init__ by directly setting the attributes of an empty matrix matrix.data = self._get_csr_data(wire_order, coeff) matrix.indices = self._get_csr_indices(wire_order) matrix.indptr = _cached_arange(matrix_size + 1) # Non-zero entries by row (starting from 0) return matrix def _get_csr_data(self, wire_order, coeff): """Computes the sparse matrix data of the Pauli word times a coefficient, given a wire order.""" full_word = [self[wire] for wire in wire_order] matrix_size = 2 ** len(wire_order) if len(self) == 0: return np.full(matrix_size, coeff, dtype=np.complex128) data = np.empty(matrix_size, dtype=np.complex128) # Non-zero values current_size = 2 data[:current_size], _ = _cached_sparse_data(full_word[-1]) data[:current_size] *= coeff # Multiply initial term better than the full matrix for s in full_word[-2::-1]: if s == "I": data[current_size : 2 * current_size] = data[:current_size] elif s == "X": data[current_size : 2 * current_size] = data[:current_size] elif s == "Y": data[current_size : 2 * current_size] = 1j * data[:current_size] data[:current_size] *= -1j elif s == "Z": data[current_size : 2 * current_size] = -data[:current_size] current_size *= 2 return data def _get_csr_data_2(self, wire_order, coeff): """Computes the sparse matrix data of the Pauli word times a coefficient, given a wire order.""" full_word = [self[wire] for wire in wire_order] nwords = len(full_word) if nwords < 2: return np.array([1.0]), self._get_csr_data(wire_order, coeff) outer = self._get_csr_data(wire_order[: nwords // 2], 1.0) inner = self._get_csr_data(wire_order[nwords // 2 :], coeff) return outer, inner def _get_csr_indices(self, wire_order): """Computes the sparse matrix indices of the Pauli word times a coefficient, given a wire order.""" full_word = [self[wire] for wire in wire_order] matrix_size = 2 ** len(wire_order) if len(self) == 0: return _cached_arange(matrix_size) indices = np.empty(matrix_size, dtype=np.int64) # Column index of non-zero values current_size = 2 _, indices[:current_size] = _cached_sparse_data(full_word[-1]) for s in full_word[-2::-1]: if s == "I": indices[current_size : 2 * current_size] = indices[:current_size] + current_size elif s == "X": indices[current_size : 2 * current_size] = indices[:current_size] indices[:current_size] += current_size elif s == "Y": indices[current_size : 2 * current_size] = indices[:current_size] indices[:current_size] += current_size elif s == "Z": indices[current_size : 2 * current_size] = indices[:current_size] + current_size current_size *= 2 return indices
[docs] def map_wires(self, wire_map: dict) -> "PauliWord": """Return a new PauliWord with the wires mapped.""" return self.__class__({wire_map.get(w, w): op for w, op in self.items()})
pw_id = PauliWord({}) # empty pauli word to be re-used
[docs] class PauliSentence(dict): r"""Dictionary representing a linear combination of Pauli words, with the keys as :class:`~pennylane.pauli.PauliWord` instances and the values correspond to coefficients. .. note:: An empty :class:`~.PauliSentence` will be treated as the additive identity (i.e ``0 * Identity()``). Its matrix is the all-zero matrix (trivially the :math:`1\times 1` zero matrix when no ``wire_order`` is passed to ``PauliSentence({}).to_mat()``). **Examples** >>> ps = PauliSentence({ ... PauliWord({0:'X', 1:'Y'}): 1.23, ... PauliWord({2:'Z', 0:'Y'}): -0.45j ... }) >>> ps 1.23 * X(0) @ Y(1) + (-0-0.45j) * Z(2) @ Y(0) Combining Pauli words automatically results in Pauli sentences that can be used to construct more complicated operators. >>> w1 = PauliWord({0:"X", 1:"Y"}) >>> w2 = PauliWord({1:"X", 2:"Z"}) >>> ps = 0.5 * w1 - 1.5 * w2 + 2 >>> ps + PauliWord({3:"Z"}) - 1 0.5 * X(0) @ Y(1) + -1.5 * X(1) @ Z(2) + 1 * I + 1.0 * Z(3) Note that while the empty :class:`~PauliWord` ``PauliWord({})`` respresents the identity, the empty ``PauliSentence`` represents 0 >>> PauliSentence({}) 0 * I We can compute commutators using the ``PauliSentence.commutator()`` method >>> op1 = PauliWord({0:"X", 1:"X"}) >>> op2 = PauliWord({0:"Y"}) + PauliWord({1:"Y"}) >>> op1.commutator(op2) 2j * Z(0) @ X(1) + 2j * X(0) @ Z(1) Or, alternatively, use :func:`~commutator`. >>> qp.commutator(op1, op2, pauli=True) 2j * Z(0) @ X(1) + 2j * X(0) @ Z(1) Note that we need to specify ``pauli=True`` as :func:`~.commutator` returns PennyLane operators by default. """ # this allows scalar multiplication from left with numpy arrays np.array(0.5) * ps1 # taken from [stackexchange](https://stackoverflow.com/questions/40694380/forcing-multiplication-to-use-rmul-instead-of-numpy-array-mul-or-byp/44634634#44634634) __array_priority__ = 1000 @property def pauli_rep(self): """Trivial pauli_rep""" return self def __missing__(self, key): """If the PauliWord is not in the sentence then the coefficient associated with it should be 0.""" return 0.0
[docs] def trace(self): r"""Return the normalized trace of the ``PauliSentence`` instance .. math:: \frac{1}{2^n} \text{tr}\left( P \right). The normalized trace does not scale with the number of qubits :math:`n`. >>> PauliSentence({PauliWord({0:"I", 1:"I"}): 0.5}).trace() 0.5 >>> PauliSentence({PauliWord({}): 0.5}).trace() 0.5 """ return self.get(pw_id, 0.0)
def __add__(self, other): """Add a PauliWord, scalar or other PauliSentence to a PauliSentence. Empty Pauli sentences are treated as the additive identity (i.e 0 * Identity on all wires). The non-empty Pauli sentence is returned. """ if isinstance(other, PauliSentence): smaller_ps, larger_ps = ( (self, copy(other)) if len(self) < len(other) else (other, copy(self)) ) for key in smaller_ps: larger_ps[key] += smaller_ps[key] return larger_ps if isinstance(other, PauliWord): res = copy(self) if other in res: res[other] += 1.0 else: res[other] = 1.0 return res if isinstance(other, TensorLike): # Scalars are interepreted as scalar * Identity res = copy(self) IdWord = PauliWord({}) if IdWord in res: res[IdWord] += other else: res[IdWord] = other return res raise TypeError(f"Cannot add {other} of type {type(other)} to PauliSentence") __radd__ = __add__ def __iadd__(self, other): """Inplace addition of two Pauli sentence together by adding terms of other to self""" if isinstance(other, PauliSentence): for key in other: if key in self: self[key] += other[key] else: self[key] = other[key] return self if isinstance(other, PauliWord): if other in self: self[other] += 1.0 else: self[other] = 1.0 return self if isinstance(other, TensorLike): IdWord = PauliWord({}) if IdWord in self: self[IdWord] += other else: self[IdWord] = other return self raise TypeError(f"Cannot add {other} of type {type(other)} to PauliSentence") def __sub__(self, other): """Subtract other PauliSentence, PauliWord, or scalar""" return self + -1 * other def __rsub__(self, other): """Subtract other PauliSentence, PauliWord, or scalar""" return -1 * self + other def __copy__(self): """Copy the PauliSentence instance.""" copied_ps = {} for pw, coeff in self.items(): copied_ps[copy(pw)] = coeff return PauliSentence(copied_ps) def __deepcopy__(self, memo): res = self.__copy__() memo[id(self)] = res return res def __matmul__(self, other): """Matrix / tensor product between two PauliSentences by iterating over each sentence and multiplying the Pauli words pair-wise""" if isinstance(other, PauliWord): other = PauliSentence({other: 1.0}) final_ps = PauliSentence() if len(self) == 0 or len(other) == 0: return final_ps for pw1 in self: for pw2 in other: prod_pw, coeff = pw1._matmul(pw2) final_ps[prod_pw] = final_ps[prod_pw] + coeff * self[pw1] * other[pw2] return final_ps def __mul__(self, other): """Multiply a PauliWord by a scalar Args: other (Scalar): The scalar to multiply the PauliWord with Returns: PauliSentence """ if isinstance(other, TensorLike): if not math.ndim(other) == 0: raise ValueError( f"Attempting to multiply a PauliSentence with an array of dimension {math.ndim(other)}" ) return PauliSentence({key: other * value for key, value in self.items()}) raise TypeError( f"PauliSentence can only be multiplied by numerical data. Attempting to multiply by {other} of type {type(other)}" ) __rmul__ = __mul__ def __truediv__(self, other): """Divide a PauliSentence by a scalar""" if isinstance(other, TensorLike): return self * (1 / other) raise TypeError( f"PauliSentence can only be divided by numerical data. Attempting to divide by {other} of type {type(other)}" )
[docs] def commutator(self, other): """ Compute commutator between a ``PauliSentence`` :math:`P` and other operator :math:`O` .. math:: [P, O] = P O - O P When the other operator is a :class:`~PauliWord` or :class:`~PauliSentence`, this method is faster than computing ``P @ O - O @ P``. It is what is being used in :func:`~commutator` when setting ``pauli=True``. Args: other (Union[PauliWord, PauliSentence]): Second Pauli word or sentence Returns: ~PauliSentence: The commutator result in form of a :class:`~PauliSentence` instances. **Examples** You can compute commutators between :class:`~PauliSentence` instances. >>> pw1 = PauliWord({0:"X"}) >>> pw2 = PauliWord({1:"X"}) >>> ps1 = PauliSentence({pw1: 1., pw2: 2.}) >>> ps2 = PauliSentence({pw1: 0.5j, pw2: 1j}) >>> ps1.commutator(ps2) 0 * I Use :func:`~pennylane.commutator` for other operator types with a Pauli representation. >>> qp.commutator(ps1, qp.Y(0), pauli=True) 2j * Z(0)""" final_ps = PauliSentence() if isinstance(other, PauliWord): for pw1 in self: comm_pw, coeff = pw1._commutator(other) if len(comm_pw) != 0: final_ps[comm_pw] += coeff * self[pw1] return final_ps if not isinstance(other, PauliSentence): raise NotImplementedError( "PauliSentence.commutator accepts only PauliWord or PauliSentence inputs. " "Use qp.commutator(self, other, pauli=True) for operators." ) for pw1 in self: for pw2 in other: comm_pw, coeff = pw1._commutator(pw2) if len(comm_pw) != 0: final_ps[comm_pw] += coeff * self[pw1] * other[pw2] return final_ps
def __str__(self): """String representation of the PauliSentence.""" if len(self) == 0: return "0 * I" return "\n+ ".join(f"{coeff} * {str(pw)}" for pw, coeff in self.items()) def __repr__(self): """Terminal representation for PauliSentence""" return str(self) @property def wires(self): """Track wires of the PauliSentence.""" return Wires.all_wires(pw.wires for pw in self.keys())
[docs] def to_mat(self, wire_order=None, format="dense", buffer_size=None): """Returns the matrix representation. Keyword Args: wire_order (iterable or None): The order of qubits in the tensor product. format (str): The format of the matrix. It is "dense" by default. Use "csr" for sparse. buffer_size (int or None): The maximum allowed memory in bytes to store intermediate results in the calculation of sparse matrices. It defaults to ``2 ** 30`` bytes that make 1GB of memory. In general, larger buffers allow faster computations. Returns: (Union[NumpyArray, ScipySparseArray]): Matrix representation of the Pauli sentence. Raises: ValueError: Can't get the matrix of an empty PauliSentence. """ wire_order = self.wires if wire_order is None else Wires(wire_order) if len(self) == 0: n = len(wire_order) if wire_order is not None else 0 if format == "dense": return np.zeros((2**n, 2**n)) return sparse.csr_matrix((2**n, 2**n), dtype="complex128").asformat(format) if format == "dense": return self._to_dense_mat(wire_order) return self._to_sparse_mat(wire_order, buffer_size=buffer_size).asformat(format)
def _to_sparse_mat(self, wire_order, buffer_size=None): """Compute the sparse matrix of the Pauli sentence by efficiently adding the Pauli words that it is composed of. See pauli_sparse_matrices.md for the technical details.""" pauli_words = list(self) # Ensure consistent ordering n_wires = len(wire_order) matrix_size = 2**n_wires matrix = sparse.csr_matrix((matrix_size, matrix_size), dtype="complex128") op_sparse_idx = _ps_to_sparse_index(pauli_words, wire_order) _, unique_sparse_structures, unique_invs = np.unique( op_sparse_idx, axis=0, return_index=True, return_inverse=True ) pw_sparse_structures = unique_sparse_structures[unique_invs] buffer_size = buffer_size or 2**30 # Default to 1GB of memory # Convert bytes to number of matrices: # complex128 (16) for each data entry and int64 (8) for each indices entry buffer_size = max(1, buffer_size // ((16 + 8) * matrix_size)) mat_data = np.empty((matrix_size, buffer_size), dtype=np.complex128) mat_indices = np.empty((matrix_size, buffer_size), dtype=np.int64) n_matrices_in_buffer = 0 for sparse_structure in unique_sparse_structures: indices, *_ = np.nonzero(pw_sparse_structures == sparse_structure) mat = self._sum_same_structure_pws([pauli_words[i] for i in indices], wire_order) mat_data[:, n_matrices_in_buffer] = mat.data mat_indices[:, n_matrices_in_buffer] = mat.indices n_matrices_in_buffer += 1 if n_matrices_in_buffer == buffer_size: # Add partial results in batches to control the memory usage matrix += self._sum_different_structure_pws(mat_indices, mat_data) n_matrices_in_buffer = 0 matrix += self._sum_different_structure_pws( mat_indices[:, :n_matrices_in_buffer], mat_data[:, :n_matrices_in_buffer] ) matrix.eliminate_zeros() return matrix def _to_dense_mat(self, wire_order): """Compute the dense matrix of the Pauli sentence by efficiently adding the Pauli words that it is composed of. See pauli_sparse_matrices.md for the technical details.""" pauli_words = list(self) # Ensure consistent ordering try: op_sparse_idx = _ps_to_sparse_index(pauli_words, wire_order) except WireError as e: raise ValueError( "Can't get the matrix for the specified wire order because it " f"does not contain all the Pauli sentence's wires {self.wires}" ) from e _, unique_sparse_structures, unique_invs = np.unique( op_sparse_idx, axis=0, return_index=True, return_inverse=True ) pw_sparse_structures = unique_sparse_structures[unique_invs] full_matrix = None for sparse_structure in unique_sparse_structures: indices, *_ = np.nonzero(pw_sparse_structures == sparse_structure) mat = self._sum_same_structure_pws_dense([pauli_words[i] for i in indices], wire_order) full_matrix = mat if full_matrix is None else math.add(full_matrix, mat) return full_matrix
[docs] def dot(self, vector, wire_order=None): """Computes the matrix-vector product of the Pauli sentence with a state vector. See pauli_sparse_matrices.md for the technical details.""" wire_order = self.wires if wire_order is None else Wires(wire_order) if not wire_order.contains_wires(self.wires): raise ValueError( "Can't get the matrix for the specified wire order because it " f"does not contain all the Pauli sentence's wires {self.wires}" ) pauli_words = list(self) # Ensure consistent ordering op_sparse_idx = _ps_to_sparse_index(pauli_words, wire_order) _, unique_sparse_structures, unique_invs = np.unique( op_sparse_idx, axis=0, return_index=True, return_inverse=True ) pw_sparse_structures = unique_sparse_structures[unique_invs] dtype = np.complex64 if vector.dtype in (np.float32, np.complex64) else np.complex128 if vector.ndim == 1: vector = vector.reshape(1, -1) mv = np.zeros_like(vector, dtype=dtype) for sparse_structure in unique_sparse_structures: indices, *_ = np.nonzero(pw_sparse_structures == sparse_structure) entries, data = self._get_same_structure_csr( [pauli_words[i] for i in indices], wire_order ) mv += vector[:, entries] * data.reshape(1, -1) return mv.reshape(vector.shape)
def _get_same_structure_csr(self, pauli_words, wire_order): """Returns the CSR indices and data for Pauli words with the same sparse structure.""" indices = pauli_words[0]._get_csr_indices(wire_order) nwires = len(wire_order) nwords = len(pauli_words) inner = np.empty((nwords, 2 ** (nwires - nwires // 2)), dtype=np.complex128) outer = np.empty((nwords, 2 ** (nwires // 2)), dtype=np.complex128) for i, word in enumerate(pauli_words): outer[i, :], inner[i, :] = word._get_csr_data_2( wire_order, coeff=math.to_numpy(self[word]) ) data = outer.T @ inner return indices, data.ravel() def _sum_same_structure_pws_dense(self, pauli_words, wire_order): matrix_size = 2 ** (len(wire_order)) base_matrix = sparse.csr_matrix((matrix_size, matrix_size), dtype="complex128") data0 = pauli_words[0]._get_csr_data(wire_order, 1) base_matrix.data = np.ones_like(data0) base_matrix.indices = pauli_words[0]._get_csr_indices(wire_order) base_matrix.indptr = _cached_arange( matrix_size + 1 ) # Non-zero entries by row (starting from 0) base_matrix = base_matrix.toarray() coeff = self[pauli_words[0]] ml_interface = math.get_interface(coeff) if ml_interface == "torch": data0 = math.convert_like(data0, coeff) data = coeff * data0 if math.ndim(coeff) == 0 else math.outer(coeff, data0) for pw in pauli_words[1:]: coeff = self[pw] csr_data = pw._get_csr_data(wire_order, 1) ml_interface = math.get_interface(coeff) if ml_interface == "torch": csr_data = math.convert_like(csr_data, coeff) data += coeff * csr_data if math.ndim(coeff) == 0 else math.outer(coeff, csr_data) return math.einsum("ij,...i->...ij", base_matrix, data) def _sum_same_structure_pws(self, pauli_words, wire_order): """Sums Pauli words with the same sparse structure.""" mat = pauli_words[0].to_mat( wire_order, coeff=math.to_numpy(self[pauli_words[0]]), format="csr" ) for word in pauli_words[1:]: mat.data += word.to_mat(wire_order, coeff=math.to_numpy(self[word]), format="csr").data return mat @staticmethod def _sum_different_structure_pws(indices, data): """Sums Pauli words with different parse structures.""" size = indices.shape[0] idx = np.argsort(indices, axis=1) matrix = sparse.csr_matrix((size, size), dtype="complex128") matrix.indices = np.take_along_axis(indices, idx, axis=1).ravel() matrix.data = np.take_along_axis(data, idx, axis=1).ravel() num_entries_per_row = indices.shape[1] matrix.indptr = _cached_arange(size + 1) * num_entries_per_row # remove zeros and things sufficiently close to zero matrix.data[np.abs(matrix.data) < 1e-16] = 0 # Faster than np.isclose(matrix.data, 0) matrix.eliminate_zeros() return matrix
[docs] def prune(self, tol=1e-8): """Remove any ``PauliWord`` with coefficients less than the threshold tolerance. **Examples** >>> ps = PauliSentence({ ... PauliWord({0:'X', 1:'Y'}): 0, ... PauliWord({2:'Z', 0:'Y'}): -0.45j ... }) >>> ps 0 * X(0) @ Y(1) + (-0-0.45j) * Z(2) @ Y(0) >>> ps.prune() >>> ps (-0-0.45j) * Z(2) @ Y(0) """ items = list(self.items()) for pw, coeff in items: if not math.is_tracer(coeff) and abs(coeff) <= tol: del self[pw]
[docs] def simplify(self, tol=1e-8) -> None: """Remove any ``PauliWord`` with coefficients less than the threshold tolerance. This method mutates the ``PauliSentence`` in place, and does not return anything. .. seealso:: :meth:`~.prune` .. warning:: The ``simplify`` method is deprecated and will be removed in v0.47. Please use the :meth:`~.prune` method instead. """ warnings.warn( "PauliSentence.simplify is deprecated. Please use PauliSentence.prune instead.", PennyLaneDeprecationWarning, ) self.prune(tol)
[docs] def map_wires(self, wire_map: dict) -> "PauliSentence": """Return a new PauliSentence with the wires mapped.""" return self.__class__({pw.map_wires(wire_map): coeff for pw, coeff in self.items()})