run_shadow_simulation
¶
Helpers and result type for running shadow dynamics.
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
computational_basis_projectors
¶
computational_basis_projectors(
num_qubits: int,
) -> OperatorSet
Return computational-basis projectors on a num_qubits-qubit space.
For n qubits this yields 2**n rank-1 projectors |k⟩⟨k| labeled
P_{bits} (e.g. P_00, P_01, …).
Source code in shadowsim/shadow/run_shadow_simulation.py
pad_h_s
¶
Embed H_S in the top-left of the next power-of-two square matrix.
Returns:
-
NDArray[complexfloating]–(H_S_padded, shadow_num_qubits)whereH_S_paddedhas shape -
int–(D, D)withD = next_power_of_two(m)for anm×minput, and -
tuple[NDArray[complexfloating], int]–shadow_num_qubits = log2(D)(0whenD == 1).
Source code in shadowsim/shadow/run_shadow_simulation.py
run_shadow_simulation
¶
run_shadow_simulation(
hamiltonians: Hamiltonian | Sequence[Hamiltonian],
observables: OperatorSet | Sequence[Operator | str],
initial_state: State,
*,
total_time: float,
time_steps: int,
circuit_backend: CircuitBackend,
num_qubits: int | None = None,
shadow_observables: OperatorSet | None = None,
seed: int | None = None,
tol: float = 1e-10,
verbose: bool = False,
) -> ShadowSimulationResult
Build the shadow model and evolve it on circuit_backend.
Constructs ShadowHamiltonian on the physical system, builds a
ShadowState ordered to match the closure basis of H_S, and pads
H_S to a power-of-two Hilbert space. Component k of the evolved
shadow state is ⟨O_k⟩(t) / √A, so it is read with a Hadamard test: an
ancilla interferes exp(-i H_S t)|ψ_S(0)⟩ with |k⟩, and its ⟨X⟩
is that component. expectations holds √A times each reading, the
signed ⟨O_k⟩(t) in basis order, labeled by basis.
One circuit runs per closure-basis operator per time point. A backend with
a shots budget estimates each reading from that many shots, so each
point carries an error of about √(A / shots). A backend without one,
such as NumpyCircuitBackend, returns exact readings. The circuits use
initialize and dense unitaries, so the backend must accept both.
shadow_observables are optional quadratic diagnostics on the shadow
register, such as computational_basis_projectors(shadow_num_qubits).
Each curve is ⟨ψ_S(t)|M|ψ_S(t)⟩, computed from the signed readings
without extra circuits, so it carries their shot noise. The curves fill
shadow_observable_expectations and do not change expectations.
Example
import numpy as np
from shadowsim.backends.numpy import NumpyCircuitBackend
from shadowsim.core import Hamiltonian, OperatorSet, State
from shadowsim.shadow import run_shadow_simulation
result = run_shadow_simulation(
Hamiltonian("X"),
OperatorSet(["Z"]),
State(np.array([1.0, 0.0], dtype=np.complex128), 1),
total_time=1.0,
time_steps=11,
circuit_backend=NumpyCircuitBackend(),
)
print(result.labels) # ['Y', 'Z']: ⟨Y⟩ = -sin(2t), ⟨Z⟩ = cos(2t)
Source code in shadowsim/shadow/run_shadow_simulation.py
423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | |