Skip to content

shadow_hamiltonian

Shadow Hamiltonian construction and closure.

ShadowHamiltonian

Store the input model H and the reduced shadow matrix H_S.

There are two objects:

  • self.H: the input model on the full qubit space. On the sparse Pauli path this is a PauliSum-backed Hamiltonian (no 2^n matrix until .matrix is accessed). On the dense fallback it is the summed (2^n, 2^n) matrix.
  • self.H_S (also .shadow / get_H_S()): the actual shadow object—commutator matrix in the closed Pauli label basis only, shape (m, m) with m = |closure|. That size does not have to equal 2^n; it is whatever the closure step produces.

When H and every observable already expose a pauli_sum, construction stays in label/coeff space (no 4^n tomography, no full-space matrix multiplies). Otherwise the dense path densifies once, expands via traces, then shares the same structure-constant assembly for H_S.

Source code in shadowsim/shadow/shadow_hamiltonian.py
class ShadowHamiltonian:
    """Store the input model ``H`` and the reduced shadow matrix ``H_S``.

    There are two objects:

    - ``self.H``: the **input** model on the full qubit space. On the sparse Pauli
      path this is a PauliSum-backed ``Hamiltonian`` (no ``2^n`` matrix until
      ``.matrix`` is accessed). On the dense fallback it is the summed
      ``(2^n, 2^n)`` matrix.
    - ``self.H_S`` (also ``.shadow`` / ``get_H_S()``): the **actual shadow
      object**—commutator matrix in the **closed Pauli label basis** only, shape
      **``(m, m)``** with **``m = |closure|``**. That size does **not** have to
      equal ``2^n``; it is whatever the closure step produces.

    When ``H`` and every observable already expose a ``pauli_sum``, construction
    stays in label/coeff space (no ``4^n`` tomography, no full-space matrix
    multiplies). Otherwise the dense path densifies once, expands via traces,
    then shares the same structure-constant assembly for ``H_S``.
    """

    def __init__(
        self,
        operator_set: OperatorSet,
        H: Hamiltonian | Sequence[Hamiltonian],
        *,
        num_qubits: int | None = None,
        tol: float = 1e-10,
        verbose: bool = False,
    ) -> None:
        """Build a shadow Hamiltonian from an operator set and Hamiltonian terms.

        ``H`` may be a single ``Hamiltonian`` or a non-empty sequence of terms.
        If every term and every observable is Pauli-backed, terms are merged as
        PauliSums without densifying. Otherwise terms are summed on the full
        ``num_qubits``-qubit space via ``combined_hamiltonian_matrix``.
        ``num_qubits`` is inferred when possible (required if every term is a
        ``LocalHamiltonian``). After closure, ``self.H_S`` is the reduced matrix.
        Set ``verbose=True`` to print Pauli-set and closure progress.
        """
        self.operator_set = operator_set
        self.tol = float(tol)
        self.verbose = verbose

        model = _pauli_model_from_inputs(
            operator_set,
            H,
            num_qubits=num_qubits,
            tol=self.tol,
        )
        self.H = model.H
        self.num_qubits = model.num_qubits
        self.used_sparse_pauli_path = model.used_sparse_pauli_path
        self.pauli_decomposition = model.pauli_decomposition
        self.pauli_set = set(model.pauli_set)
        self.operator_pauli_set = set(model.operator_pauli_set)

        if self.verbose:
            print(
                "Pauli counts -> "
                f"Hamiltonian set: {len(self.pauli_set)}, "
                f"Operator set union: {len(self.operator_pauli_set)}"
            )

        self.operator_pauli_closure = _close_operator_paulis(self.operator_pauli_set, self.pauli_set)
        if self.verbose:
            print(f"Operator closure size: {len(self.operator_pauli_closure)}")

        self.basis = sorted(self.operator_pauli_closure)
        self.H_S = _assemble_h_s(self.basis, self.pauli_decomposition)

    @property
    def shadow(self) -> npt.NDArray[np.complexfloating]:
        """The shadow Hamiltonian: ``(m, m)`` with ``m = |closure|``; not ``(2^n, 2^n)`` in general."""
        return self.H_S

    def get_H_S(self) -> npt.NDArray[np.complexfloating]:
        """Return the shadow Hamiltonian in the closed Pauli basis.

        Same as ``shadow``. Shape ``(m, m)`` with ``m = len(self.basis)``,
        independent of ``2^n`` (unless m happens to match by coincidence).
        """
        return self.H_S

    def is_unitary(self) -> bool:
        """Return whether the shadow Hamiltonian matrix is unitary."""
        return unitary(self.H_S)

    def is_hermitian(self) -> bool:
        """Return whether the shadow Hamiltonian matrix is Hermitian."""
        return hermitian(self.H_S)

    def __str__(self) -> str:
        """Return a string representation of the ShadowHamiltonian."""
        if self.used_sparse_pauli_path:
            h_part = f"pauli_terms={len(self.pauli_decomposition)}"
        else:
            h_part = f"full_H.shape={self.H.matrix.shape}"
        return f"ShadowHamiltonian({h_part}, shadow.shape={self.H_S.shape}, n_qubits={self.num_qubits})"

    def __repr__(self) -> str:
        """Return a string representation of the ShadowHamiltonian."""
        if self.used_sparse_pauli_path:
            h_part = f"pauli_terms={len(self.pauli_decomposition)}"
        else:
            h_part = f"H.shape={self.H.matrix.shape}"
        return (
            "ShadowHamiltonian("
            f"{h_part}, "
            f"H_S.shape={self.H_S.shape}, "
            f"basis_size={len(self.basis)}, "
            f"sparse={self.used_sparse_pauli_path!r}, "
            f"tol={self.tol!r}, "
            f"verbose={self.verbose!r})"
        )

shadow property

shadow: NDArray[complexfloating]

The shadow Hamiltonian: (m, m) with m = |closure|; not (2^n, 2^n) in general.

__init__

__init__(
    operator_set: OperatorSet,
    H: Hamiltonian | Sequence[Hamiltonian],
    *,
    num_qubits: int | None = None,
    tol: float = 1e-10,
    verbose: bool = False,
) -> None

Build a shadow Hamiltonian from an operator set and Hamiltonian terms.

H may be a single Hamiltonian or a non-empty sequence of terms. If every term and every observable is Pauli-backed, terms are merged as PauliSums without densifying. Otherwise terms are summed on the full num_qubits-qubit space via combined_hamiltonian_matrix. num_qubits is inferred when possible (required if every term is a LocalHamiltonian). After closure, self.H_S is the reduced matrix. Set verbose=True to print Pauli-set and closure progress.

Source code in shadowsim/shadow/shadow_hamiltonian.py
def __init__(
    self,
    operator_set: OperatorSet,
    H: Hamiltonian | Sequence[Hamiltonian],
    *,
    num_qubits: int | None = None,
    tol: float = 1e-10,
    verbose: bool = False,
) -> None:
    """Build a shadow Hamiltonian from an operator set and Hamiltonian terms.

    ``H`` may be a single ``Hamiltonian`` or a non-empty sequence of terms.
    If every term and every observable is Pauli-backed, terms are merged as
    PauliSums without densifying. Otherwise terms are summed on the full
    ``num_qubits``-qubit space via ``combined_hamiltonian_matrix``.
    ``num_qubits`` is inferred when possible (required if every term is a
    ``LocalHamiltonian``). After closure, ``self.H_S`` is the reduced matrix.
    Set ``verbose=True`` to print Pauli-set and closure progress.
    """
    self.operator_set = operator_set
    self.tol = float(tol)
    self.verbose = verbose

    model = _pauli_model_from_inputs(
        operator_set,
        H,
        num_qubits=num_qubits,
        tol=self.tol,
    )
    self.H = model.H
    self.num_qubits = model.num_qubits
    self.used_sparse_pauli_path = model.used_sparse_pauli_path
    self.pauli_decomposition = model.pauli_decomposition
    self.pauli_set = set(model.pauli_set)
    self.operator_pauli_set = set(model.operator_pauli_set)

    if self.verbose:
        print(
            "Pauli counts -> "
            f"Hamiltonian set: {len(self.pauli_set)}, "
            f"Operator set union: {len(self.operator_pauli_set)}"
        )

    self.operator_pauli_closure = _close_operator_paulis(self.operator_pauli_set, self.pauli_set)
    if self.verbose:
        print(f"Operator closure size: {len(self.operator_pauli_closure)}")

    self.basis = sorted(self.operator_pauli_closure)
    self.H_S = _assemble_h_s(self.basis, self.pauli_decomposition)

get_H_S

get_H_S() -> NDArray[complexfloating]

Return the shadow Hamiltonian in the closed Pauli basis.

Same as shadow. Shape (m, m) with m = len(self.basis), independent of 2^n (unless m happens to match by coincidence).

Source code in shadowsim/shadow/shadow_hamiltonian.py
def get_H_S(self) -> npt.NDArray[np.complexfloating]:
    """Return the shadow Hamiltonian in the closed Pauli basis.

    Same as ``shadow``. Shape ``(m, m)`` with ``m = len(self.basis)``,
    independent of ``2^n`` (unless m happens to match by coincidence).
    """
    return self.H_S

is_unitary

is_unitary() -> bool

Return whether the shadow Hamiltonian matrix is unitary.

Source code in shadowsim/shadow/shadow_hamiltonian.py
def is_unitary(self) -> bool:
    """Return whether the shadow Hamiltonian matrix is unitary."""
    return unitary(self.H_S)

is_hermitian

is_hermitian() -> bool

Return whether the shadow Hamiltonian matrix is Hermitian.

Source code in shadowsim/shadow/shadow_hamiltonian.py
def is_hermitian(self) -> bool:
    """Return whether the shadow Hamiltonian matrix is Hermitian."""
    return hermitian(self.H_S)

__str__

__str__() -> str

Return a string representation of the ShadowHamiltonian.

Source code in shadowsim/shadow/shadow_hamiltonian.py
def __str__(self) -> str:
    """Return a string representation of the ShadowHamiltonian."""
    if self.used_sparse_pauli_path:
        h_part = f"pauli_terms={len(self.pauli_decomposition)}"
    else:
        h_part = f"full_H.shape={self.H.matrix.shape}"
    return f"ShadowHamiltonian({h_part}, shadow.shape={self.H_S.shape}, n_qubits={self.num_qubits})"

__repr__

__repr__() -> str

Return a string representation of the ShadowHamiltonian.

Source code in shadowsim/shadow/shadow_hamiltonian.py
def __repr__(self) -> str:
    """Return a string representation of the ShadowHamiltonian."""
    if self.used_sparse_pauli_path:
        h_part = f"pauli_terms={len(self.pauli_decomposition)}"
    else:
        h_part = f"H.shape={self.H.matrix.shape}"
    return (
        "ShadowHamiltonian("
        f"{h_part}, "
        f"H_S.shape={self.H_S.shape}, "
        f"basis_size={len(self.basis)}, "
        f"sparse={self.used_sparse_pauli_path!r}, "
        f"tol={self.tol!r}, "
        f"verbose={self.verbose!r})"
    )