Skip to content

operator

General quantum operators.

Operator

Represent a quantum operator.

Construct from a dense matrix, a Pauli label/expression string (e.g. XII or XXI + XYZ), a PauliString, or a PauliSum.

Label-based inputs store a PauliSum and only materialize .matrix on first access.

Source code in shadowsim/core/operator.py
class Operator:
    """Represent a quantum operator.

    Construct from a dense matrix, a Pauli label/expression string (e.g. ``XII``
    or ``XXI + XYZ``), a ``PauliString``, or a ``PauliSum``.

    Label-based inputs store a ``PauliSum`` and only materialize ``.matrix``
    on first access.
    """

    def __init__(self, matrix: _OperatorInput, name: str | None = None) -> None:
        """Initialize an Operator object which represents a quantum operator.

        Parameter matrix: Dense matrix, Pauli expression string, PauliString, or PauliSum.
        Parameter name: Optional name; defaults to the Pauli expression when built from labels.
        """
        assert isinstance(name, str) or name is None, "name must be a string or None"
        self._pauli_sum: PauliSum | None = None
        self._matrix_cache: _Matrix | None = None
        self._flags_ready = False
        self._is_hermitian = False
        self._is_unitary = False
        self._is_positive_semidefinite = False
        self._is_negative_semidefinite = False
        self._is_indefinite = False

        if isinstance(matrix, np.ndarray):
            self._matrix_cache = matrix
            self.dimension = int(matrix.shape[0])
            self.name = name
            self._set_flags_from_matrix(matrix)
        elif isinstance(matrix, (str, PauliString, PauliSum)):
            pauli_sum = _coerce_pauli_sum(matrix)
            self._pauli_sum = pauli_sum
            self.dimension = 2**pauli_sum.num_qubits
            self.name = str(pauli_sum) if name is None else name
        else:
            raise TypeError(f"matrix must be a numpy array, str, PauliString, or PauliSum; got {type(matrix)!r}")

    def _set_flags_from_matrix(self, matrix: _Matrix) -> None:
        self._is_hermitian = bool(hermitian(matrix))
        self._is_unitary = bool(unitary(matrix))
        self._is_positive_semidefinite = bool(positive_semidefinite(matrix))
        self._is_negative_semidefinite = bool(negative_semidefinite(matrix))
        self._is_indefinite = bool(indefinite(matrix))
        self._flags_ready = True

    def _ensure_matrix(self) -> _Matrix:
        if self._matrix_cache is None:
            if self._pauli_sum is None:
                raise RuntimeError("Operator has neither a matrix cache nor a PauliSum")
            self._matrix_cache = self._pauli_sum.to_matrix()
            self._set_flags_from_matrix(self._matrix_cache)
        return self._matrix_cache

    def _ensure_flags(self) -> None:
        if self._flags_ready:
            return
        matrix = self._ensure_matrix()
        if not self._flags_ready:
            self._set_flags_from_matrix(matrix)

    @property
    def matrix(self) -> _Matrix:
        """Return the dense matrix, materializing from a PauliSum if needed."""
        return self._ensure_matrix()

    @property
    def pauli_sum(self) -> PauliSum | None:
        """Return the stored PauliSum, or ``None`` if built from a dense matrix."""
        return self._pauli_sum

    @property
    def is_hermitian(self) -> bool:
        """Return whether the operator is Hermitian."""
        if self._flags_ready:
            return self._is_hermitian
        if self._pauli_sum is not None and self._matrix_cache is None:
            return self._pauli_sum.is_hermitian()
        self._ensure_flags()
        return self._is_hermitian

    @property
    def is_unitary(self) -> bool:
        """Return whether the operator is unitary."""
        self._ensure_flags()
        return self._is_unitary

    @property
    def is_positive_semidefinite(self) -> bool:
        """Return whether the operator is positive semidefinite."""
        self._ensure_flags()
        return self._is_positive_semidefinite

    @property
    def is_negative_semidefinite(self) -> bool:
        """Return whether the operator is negative semidefinite."""
        self._ensure_flags()
        return self._is_negative_semidefinite

    @property
    def is_indefinite(self) -> bool:
        """Return whether the operator is indefinite."""
        self._ensure_flags()
        return self._is_indefinite

    def __str__(self) -> str:
        """Return a string representation of the operator."""
        if self._pauli_sum is not None and self._matrix_cache is None:
            return f"Operator(pauli_sum={self._pauli_sum})"
        return f"Operator(matrix={self.matrix})"

    def __repr__(self) -> str:
        """Return a string representation of the operator."""
        if self._pauli_sum is not None and self._matrix_cache is None:
            return f"Operator(pauli_sum={self._pauli_sum!r})"
        return f"Operator(matrix={self.matrix})"

    def __eq__(self, other: object) -> bool:
        """Return whether the operator is equal to another operator.

        Operators whose matrices have different shapes compare unequal.
        """
        if not isinstance(other, Operator):
            return NotImplemented
        return _matrices_close(self.matrix, other.matrix)

    __hash__ = None  # type: ignore[assignment]  # matrix equality uses allclose; instances are not hashable

    def __ne__(self, other: object) -> bool:
        """Return whether the operator is not equal to another operator.

        Operators whose matrices have different shapes compare unequal.
        """
        if not isinstance(other, Operator):
            return NotImplemented
        return not _matrices_close(self.matrix, other.matrix)

    def to_operator_set(self) -> OperatorSet:
        """Return an OperatorSet containing the operator."""
        from shadowsim.core.operator_set import OperatorSet  # noqa: PLC0415

        return OperatorSet([self])

    def to_local_operator(self, sites: list[int], local_dim: int = 2) -> LocalOperator:
        """Return a LocalOperator representing the operator acting on the given sites."""
        from shadowsim.core.local_operator import LocalOperator  # noqa: PLC0415

        return LocalOperator(self.matrix, sites, local_dim)

    def set_name(self, name: str | None) -> None:
        """Set the operator name."""
        assert isinstance(name, str) or name is None, "name must be a string or None"
        self.name = name

matrix property

matrix: _Matrix

Return the dense matrix, materializing from a PauliSum if needed.

pauli_sum property

pauli_sum: PauliSum | None

Return the stored PauliSum, or None if built from a dense matrix.

is_hermitian property

is_hermitian: bool

Return whether the operator is Hermitian.

is_unitary property

is_unitary: bool

Return whether the operator is unitary.

is_positive_semidefinite property

is_positive_semidefinite: bool

Return whether the operator is positive semidefinite.

is_negative_semidefinite property

is_negative_semidefinite: bool

Return whether the operator is negative semidefinite.

is_indefinite property

is_indefinite: bool

Return whether the operator is indefinite.

__init__

__init__(
    matrix: _OperatorInput, name: str | None = None
) -> None

Initialize an Operator object which represents a quantum operator.

Parameter matrix: Dense matrix, Pauli expression string, PauliString, or PauliSum. Parameter name: Optional name; defaults to the Pauli expression when built from labels.

Source code in shadowsim/core/operator.py
def __init__(self, matrix: _OperatorInput, name: str | None = None) -> None:
    """Initialize an Operator object which represents a quantum operator.

    Parameter matrix: Dense matrix, Pauli expression string, PauliString, or PauliSum.
    Parameter name: Optional name; defaults to the Pauli expression when built from labels.
    """
    assert isinstance(name, str) or name is None, "name must be a string or None"
    self._pauli_sum: PauliSum | None = None
    self._matrix_cache: _Matrix | None = None
    self._flags_ready = False
    self._is_hermitian = False
    self._is_unitary = False
    self._is_positive_semidefinite = False
    self._is_negative_semidefinite = False
    self._is_indefinite = False

    if isinstance(matrix, np.ndarray):
        self._matrix_cache = matrix
        self.dimension = int(matrix.shape[0])
        self.name = name
        self._set_flags_from_matrix(matrix)
    elif isinstance(matrix, (str, PauliString, PauliSum)):
        pauli_sum = _coerce_pauli_sum(matrix)
        self._pauli_sum = pauli_sum
        self.dimension = 2**pauli_sum.num_qubits
        self.name = str(pauli_sum) if name is None else name
    else:
        raise TypeError(f"matrix must be a numpy array, str, PauliString, or PauliSum; got {type(matrix)!r}")

__str__

__str__() -> str

Return a string representation of the operator.

Source code in shadowsim/core/operator.py
def __str__(self) -> str:
    """Return a string representation of the operator."""
    if self._pauli_sum is not None and self._matrix_cache is None:
        return f"Operator(pauli_sum={self._pauli_sum})"
    return f"Operator(matrix={self.matrix})"

__repr__

__repr__() -> str

Return a string representation of the operator.

Source code in shadowsim/core/operator.py
def __repr__(self) -> str:
    """Return a string representation of the operator."""
    if self._pauli_sum is not None and self._matrix_cache is None:
        return f"Operator(pauli_sum={self._pauli_sum!r})"
    return f"Operator(matrix={self.matrix})"

__eq__

__eq__(other: object) -> bool

Return whether the operator is equal to another operator.

Operators whose matrices have different shapes compare unequal.

Source code in shadowsim/core/operator.py
def __eq__(self, other: object) -> bool:
    """Return whether the operator is equal to another operator.

    Operators whose matrices have different shapes compare unequal.
    """
    if not isinstance(other, Operator):
        return NotImplemented
    return _matrices_close(self.matrix, other.matrix)

__ne__

__ne__(other: object) -> bool

Return whether the operator is not equal to another operator.

Operators whose matrices have different shapes compare unequal.

Source code in shadowsim/core/operator.py
def __ne__(self, other: object) -> bool:
    """Return whether the operator is not equal to another operator.

    Operators whose matrices have different shapes compare unequal.
    """
    if not isinstance(other, Operator):
        return NotImplemented
    return not _matrices_close(self.matrix, other.matrix)

to_operator_set

to_operator_set() -> OperatorSet

Return an OperatorSet containing the operator.

Source code in shadowsim/core/operator.py
def to_operator_set(self) -> OperatorSet:
    """Return an OperatorSet containing the operator."""
    from shadowsim.core.operator_set import OperatorSet  # noqa: PLC0415

    return OperatorSet([self])

to_local_operator

to_local_operator(
    sites: list[int], local_dim: int = 2
) -> LocalOperator

Return a LocalOperator representing the operator acting on the given sites.

Source code in shadowsim/core/operator.py
def to_local_operator(self, sites: list[int], local_dim: int = 2) -> LocalOperator:
    """Return a LocalOperator representing the operator acting on the given sites."""
    from shadowsim.core.local_operator import LocalOperator  # noqa: PLC0415

    return LocalOperator(self.matrix, sites, local_dim)

set_name

set_name(name: str | None) -> None

Set the operator name.

Source code in shadowsim/core/operator.py
def set_name(self, name: str | None) -> None:
    """Set the operator name."""
    assert isinstance(name, str) or name is None, "name must be a string or None"
    self.name = name