shadow
¶
Shadow Hamiltonian, shadow state, and shadow simulation helpers.
ChangeOfBasis
dataclass
¶
Factors and shadow matrices for a quadratic change of basis.
Attributes:
-
A(NDArray[complexfloating]) –Change-of-basis matrix
A = B†. New operators areO = A Y. -
B(NDArray[complexfloating]) –Factor with
Γ = B B†. -
H_S(NDArray[complexfloating]) –Shadow matrix
i B† Ω Bin the new basis. -
quadrature_H_S(NDArray[complexfloating]) –Shadow matrix
i Ω Γbefore the change of basis. -
omega(NDArray[floating]) –Commutator matrix used, with
[Y_j, Y_k] = i Ω_jk.
Source code in shadowsim/shadow/change_of_basis.py
InvarianceReport
dataclass
¶
Diagnostic for whether H and an operator set satisfy the IP.
Attributes:
-
is_closed(bool) –Whether the original Pauli support of
Salready equals its closure under commutators withH. -
original_size(int) –Number of Pauli labels in the original operator set.
-
closure_size(int) –Number of Pauli labels after ad_H closure.
-
growth(int) –closure_size - original_size. -
original_paulis(frozenset[str]) –Pauli labels appearing in the original operator set.
-
closure_paulis(frozenset[str]) –Pauli labels after closure.
-
added_paulis(frozenset[str]) –Labels in the closure that were not in the original set.
-
h_s_is_hermitian(bool) –Whether
H_Son the closed basis is Hermitian (needed for unitary shadow Schrödinger evolution). -
num_qubits(int) –Qubit count used for the Pauli presentation.
-
used_sparse_pauli_path(bool) –Whether the sparse Pauli path was used.
Source code in shadowsim/shadow/invariance.py
ShadowSimulationResult
dataclass
¶
Outputs from a shadow-space dynamics run.
save writes times.npy, expectations.npy, and meta.json.
load restores times, curves, labels, basis, and padding, and leaves
shadow_hamiltonian, shadow_state, and H_S_padded as None.
The shadow-observable curves are not saved, so load leaves them empty.
plot_results draws one expectation curve per label.
Attributes:
-
times(NDArray[float64]) –Simulation time grid.
-
expectations(list[NDArray[float64]]) –Signed
⟨O_k⟩(t)for each closure-basis operator, inbasisorder. -
labels(list[str]) –Names for each trajectory in
expectations. A fresh run usesbasis. -
basis(list[str]) –Closure basis order (Pauli labels).
-
shadow_num_qubits(int) –Qubit count of the padded shadow Hilbert space.
-
h_s_dimension(int) –Unpadded
H_Sdimension,len(basis). -
shadow_hamiltonian(ShadowHamiltonian | None) –Constructed shadow Hamiltonian (includes unpadded
H_S).Nonewhen this result was not produced by a fresh run. -
shadow_state(ShadowState | None) –Shadow state aligned to the closure basis order.
Nonewhen this result was not produced by a fresh run. -
H_S_padded(NDArray[complexfloating] | None) –H_Sembedded in the top-left of a2**shadow_num_qubitsmatrix.Nonewhen this result was not produced by a fresh run. -
shadow_observable_expectations(list[NDArray[float64]]) –⟨ψ_S(t)|M|ψ_S(t)⟩for eachMpassed asshadow_observables, in that order. Empty when none were passed. -
shadow_observable_labels(list[str]) –Names for each trajectory in
shadow_observable_expectations.
Source code in shadowsim/shadow/run_shadow_simulation.py
24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 | |
save
¶
Write times, expectation curves, and metadata to a directory.
Layout::
path/
times.npy
expectations.npy
meta.json
expectations.npy is a float64 array of shape
(len(labels), len(times)), one curve per row. meta.json records
labels, basis, shadow_num_qubits, and h_s_dimension.
The shadow Hamiltonian, shadow state, padded H_S, and shadow-observable
curves are not written.
Arrays are saved with allow_pickle=False.
Source code in shadowsim/shadow/run_shadow_simulation.py
load
classmethod
¶
load(path: str | Path) -> ShadowSimulationResult
Reload a result previously written by save.
Restores times, expectation curves, labels, basis, and padding.
shadow_hamiltonian, shadow_state, and H_S_padded are
None. Array files are read with allow_pickle=False. A pickle
payload is rejected and not executed.
Source code in shadowsim/shadow/run_shadow_simulation.py
plot_results
¶
Plot expectation traces against time in an interactive window.
One curve is drawn per entry of labels. Axis labels are Time and
Expectation. Matplotlib is imported through the viz extra.
Source code in shadowsim/shadow/run_shadow_simulation.py
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-backedHamiltonian(no2^nmatrix until.matrixis 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)withm = |closure|. That size does not have to equal2^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
240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 | |
shadow
property
¶
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
get_H_S
¶
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
is_unitary
¶
is_hermitian
¶
__str__
¶
Return a string representation of the ShadowHamiltonian.
Source code in shadowsim/shadow/shadow_hamiltonian.py
__repr__
¶
Return a string representation of the ShadowHamiltonian.
Source code in shadowsim/shadow/shadow_hamiltonian.py
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
__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 ifnum_qubitscannot hold the components.
Source code in shadowsim/shadow/shadow_state.py
__str__
¶
__repr__
¶
check_invariance
¶
check_invariance(
operator_set: OperatorSet,
H: Hamiltonian | Sequence[Hamiltonian],
*,
num_qubits: int | None = None,
tol: float = 1e-10,
) -> InvarianceReport
Check whether H and operator_set satisfy the invariance property.
Uses the same sparse/dense Pauli presentation as ShadowHamiltonian.
Reports whether the original Pauli support of S is already closed under
commutators with H, and how many labels must be added to close it.
Also reports whether the closed-basis H_S is Hermitian.
Parameters:
-
operator_set(OperatorSet) –Observables whose Pauli support defines
S. -
H(Hamiltonian | Sequence[Hamiltonian]) –A single
Hamiltonianor a non-empty sequence of terms. -
num_qubits(int | None, default:None) –Qubit count; inferred when possible (required if every term is a
LocalHamiltonian). -
tol(float, default:1e-10) –Magnitude threshold for keeping Pauli coefficients.
Returns:
-
InvarianceReport–An
InvarianceReportsummarizing closure and Hermiticity.