Skip to content

density_operator

Density operators (mixed quantum states).

DensityOperator

Bases: Operator

Represent a density operator (mixed quantum state).

The matrix must be square, Hermitian, positive semidefinite, and unit-trace.

Source code in shadowsim/core/density_operator.py
class DensityOperator(Operator):
    """Represent a density operator (mixed quantum state).

    The matrix must be square, Hermitian, positive semidefinite, and unit-trace.
    """

    def __init__(self, matrix: npt.NDArray[np.complexfloating]) -> None:
        """Initialize a DensityOperator.

        Parameter matrix: Dense density matrix.
        """
        if not isinstance(matrix, np.ndarray):
            raise TypeError(f"matrix must be a numpy array; got {type(matrix)!r}")
        super().__init__(_as_valid_density_matrix(matrix))

    @classmethod
    def from_state(cls, state: State) -> Self:
        """Build the pure-state projector ``|ψ⟩⟨ψ|`` from a ``State``."""
        if not isinstance(state, State):
            raise TypeError(f"state must be a State; got {type(state)!r}")
        ket = np.asarray(state.state, dtype=np.complex128).reshape(-1, 1)
        return cls(ket @ ket.conj().T)

    def trace(self) -> complex:
        """Return the trace of the density matrix."""
        return complex(np.trace(self.matrix))

    def purity(self) -> float:
        """Return the purity ``Tr(ρ²)`` as a real float.

        For a valid density operator on a ``d``-dimensional space the value
        lies in ``[1/d, 1]``: ``1`` for a pure state and ``1/d`` for the
        maximally mixed state ``I/d``. Because a density operator is
        Hermitian, this equals the squared Frobenius norm of the matrix.
        """
        return float(np.trace(self.matrix @ self.matrix).real)

    def __str__(self) -> str:
        """Return a string representation of the density operator."""
        return f"DensityOperator(matrix={self.matrix})"

    def __repr__(self) -> str:
        """Return a string representation of the density operator."""
        return f"DensityOperator(matrix={self.matrix!r})"

    def __eq__(self, other: object) -> bool:
        """Return whether the density operator equals another.

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

    __hash__ = None  # matrix equality uses allclose; instances are not hashable

    def __ne__(self, other: object) -> bool:
        """Return whether the density operator differs from another.

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

__init__

__init__(matrix: NDArray[complexfloating]) -> None

Initialize a DensityOperator.

Parameter matrix: Dense density matrix.

Source code in shadowsim/core/density_operator.py
def __init__(self, matrix: npt.NDArray[np.complexfloating]) -> None:
    """Initialize a DensityOperator.

    Parameter matrix: Dense density matrix.
    """
    if not isinstance(matrix, np.ndarray):
        raise TypeError(f"matrix must be a numpy array; got {type(matrix)!r}")
    super().__init__(_as_valid_density_matrix(matrix))

from_state classmethod

from_state(state: State) -> Self

Build the pure-state projector |ψ⟩⟨ψ| from a State.

Source code in shadowsim/core/density_operator.py
@classmethod
def from_state(cls, state: State) -> Self:
    """Build the pure-state projector ``|ψ⟩⟨ψ|`` from a ``State``."""
    if not isinstance(state, State):
        raise TypeError(f"state must be a State; got {type(state)!r}")
    ket = np.asarray(state.state, dtype=np.complex128).reshape(-1, 1)
    return cls(ket @ ket.conj().T)

trace

trace() -> complex

Return the trace of the density matrix.

Source code in shadowsim/core/density_operator.py
def trace(self) -> complex:
    """Return the trace of the density matrix."""
    return complex(np.trace(self.matrix))

purity

purity() -> float

Return the purity Tr(ρ²) as a real float.

For a valid density operator on a d-dimensional space the value lies in [1/d, 1]: 1 for a pure state and 1/d for the maximally mixed state I/d. Because a density operator is Hermitian, this equals the squared Frobenius norm of the matrix.

Source code in shadowsim/core/density_operator.py
def purity(self) -> float:
    """Return the purity ``Tr(ρ²)`` as a real float.

    For a valid density operator on a ``d``-dimensional space the value
    lies in ``[1/d, 1]``: ``1`` for a pure state and ``1/d`` for the
    maximally mixed state ``I/d``. Because a density operator is
    Hermitian, this equals the squared Frobenius norm of the matrix.
    """
    return float(np.trace(self.matrix @ self.matrix).real)

__str__

__str__() -> str

Return a string representation of the density operator.

Source code in shadowsim/core/density_operator.py
def __str__(self) -> str:
    """Return a string representation of the density operator."""
    return f"DensityOperator(matrix={self.matrix})"

__repr__

__repr__() -> str

Return a string representation of the density operator.

Source code in shadowsim/core/density_operator.py
def __repr__(self) -> str:
    """Return a string representation of the density operator."""
    return f"DensityOperator(matrix={self.matrix!r})"

__eq__

__eq__(other: object) -> bool

Return whether the density operator equals another.

Density operators whose matrices have different shapes compare unequal.

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

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

__ne__

__ne__(other: object) -> bool

Return whether the density operator differs from another.

Density operators whose matrices have different shapes compare unequal.

Source code in shadowsim/core/density_operator.py
def __ne__(self, other: object) -> bool:
    """Return whether the density operator differs from another.

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