Skip to content

shadow_state

Shadow states from operator expectation values.

ShadowState

Bases: State

Shadow state whose amplitudes are normalized operator expectations.

For a state |ψ⟩ and operators O_m, the amplitude weight is A = Σ_m |⟨O_m⟩|². The shadow vector is ⟨O_m⟩ / √A, which has Euclidean norm 1 whenever A > 0, then zero-padded to the next power of two or to 2**num_qubits.

Source code in shadowsim/shadow/shadow_state.py
class ShadowState(State):
    """Shadow state whose amplitudes are normalized operator expectations.

    For a state ``|ψ⟩`` and operators ``O_m``, the amplitude weight is
    ``A = Σ_m |⟨O_m⟩|²``. The shadow vector is ``⟨O_m⟩ / √A``, which has
    Euclidean norm 1 whenever ``A > 0``, then zero-padded to the next power
    of two or to ``2**num_qubits``.
    """

    def __init__(
        self,
        state: State,
        operator_set: OperatorSet,
        *,
        num_qubits: int | None = None,
    ) -> None:
        """Initialize a ShadowState from a state and operator set.

        Raises:
            ValueError: If ``A = Σ|⟨O⟩|²`` is zero, so no unit shadow vector
                exists, or if ``num_qubits`` cannot hold the components.
        """
        self.A = 0.0
        exp_vals: list[complex] = []

        psi = state.get_state()
        for op in operator_set.operators:
            exp_Om = np.vdot(psi, op.matrix @ psi)
            self.A += float(np.abs(exp_Om) ** 2)
            exp_vals.append(exp_Om)

        shadow_state = np.asarray(exp_vals, dtype=np.complex128)
        if self.A == 0:
            raise ValueError(
                "cannot build a shadow state when A = Σ|⟨O⟩|² is zero; every operator expectation vanished"
            )
        shadow_state = shadow_state / np.sqrt(self.A)

        n = int(shadow_state.shape[0])
        if num_qubits is not None:
            nq = int(num_qubits)
            if nq < 0:
                raise ValueError("num_qubits must be non-negative")
            need = 2**nq
            if n > need:
                raise ValueError(f"not enough room in 2**num_qubits={need} for {n} shadow components")
            padded_len = need
        else:
            padded_len = next_power_of_two(n)
        num_qubits_out = padded_len.bit_length() - 1
        if int(shadow_state.shape[0]) < padded_len:
            out = np.zeros(padded_len, dtype=np.complex128)
            out[:n] = shadow_state
            shadow_state = out

        super().__init__(shadow_state, num_qubits_out, 2)

    def __str__(self) -> str:
        """Return a string representation of the ShadowState."""
        return f"ShadowState(num_qubits={self.get_num_qubits()}, A={self.A}, shape={self.state.shape})"

    def __repr__(self) -> str:
        """Return a string representation of the ShadowState."""
        return f"ShadowState(state={self.state!r}, A={self.A!r}, num_qubits={self.get_num_qubits()})"

__init__

__init__(
    state: State,
    operator_set: OperatorSet,
    *,
    num_qubits: int | None = None,
) -> None

Initialize a ShadowState from a state and operator set.

Raises:

  • ValueError –

    If A = Σ|⟨O⟩|² is zero, so no unit shadow vector exists, or if num_qubits cannot hold the components.

Source code in shadowsim/shadow/shadow_state.py
def __init__(
    self,
    state: State,
    operator_set: OperatorSet,
    *,
    num_qubits: int | None = None,
) -> None:
    """Initialize a ShadowState from a state and operator set.

    Raises:
        ValueError: If ``A = Σ|⟨O⟩|²`` is zero, so no unit shadow vector
            exists, or if ``num_qubits`` cannot hold the components.
    """
    self.A = 0.0
    exp_vals: list[complex] = []

    psi = state.get_state()
    for op in operator_set.operators:
        exp_Om = np.vdot(psi, op.matrix @ psi)
        self.A += float(np.abs(exp_Om) ** 2)
        exp_vals.append(exp_Om)

    shadow_state = np.asarray(exp_vals, dtype=np.complex128)
    if self.A == 0:
        raise ValueError(
            "cannot build a shadow state when A = Σ|⟨O⟩|² is zero; every operator expectation vanished"
        )
    shadow_state = shadow_state / np.sqrt(self.A)

    n = int(shadow_state.shape[0])
    if num_qubits is not None:
        nq = int(num_qubits)
        if nq < 0:
            raise ValueError("num_qubits must be non-negative")
        need = 2**nq
        if n > need:
            raise ValueError(f"not enough room in 2**num_qubits={need} for {n} shadow components")
        padded_len = need
    else:
        padded_len = next_power_of_two(n)
    num_qubits_out = padded_len.bit_length() - 1
    if int(shadow_state.shape[0]) < padded_len:
        out = np.zeros(padded_len, dtype=np.complex128)
        out[:n] = shadow_state
        shadow_state = out

    super().__init__(shadow_state, num_qubits_out, 2)

__str__

__str__() -> str

Return a string representation of the ShadowState.

Source code in shadowsim/shadow/shadow_state.py
def __str__(self) -> str:
    """Return a string representation of the ShadowState."""
    return f"ShadowState(num_qubits={self.get_num_qubits()}, A={self.A}, shape={self.state.shape})"

__repr__

__repr__() -> str

Return a string representation of the ShadowState.

Source code in shadowsim/shadow/shadow_state.py
def __repr__(self) -> str:
    """Return a string representation of the ShadowState."""
    return f"ShadowState(state={self.state!r}, A={self.A!r}, num_qubits={self.get_num_qubits()})"