Skip to main content

ShadowSim.py

Test and coverage codecov

Overview

ShadowSim.py is an open-source Python library with two main purposes:

  1. Shadow Hamiltonian research: support analysis and further research on shadow Hamiltonian simulation.
  2. Algorithm comparison: make it easy to compare quantum simulation algorithms for open and closed systems.

Note: “Shadow” here means shadow Hamiltonian simulation (Somma et al., arXiv:2407.21775), not classical shadow tomography / randomized measurement protocols.

When to use: Use ShadowSim to build and inspect shadow Hamiltonians for small qubit systems, and to benchmark open- or closed-system simulation algorithms against a classical reference (e.g. QuTiP). The simulation builder is the local page for that work.

Installation

The core package depends only on NumPy. Product-formula simulators need the circuits extra (SciPy). QuTiP, Qiskit, Matplotlib, Julia's PauliPropagation, Qulacs, and Cirq are optional:

python -m pip install shadowsim
python -m pip install "shadowsim[qutip]"
python -m pip install "shadowsim[qiskit]"
python -m pip install "shadowsim[circuits]"
python -m pip install "shadowsim[viz]"
python -m pip install "shadowsim[pauli_propagation]"
python -m pip install "shadowsim[qulacs]"
python -m pip install "shadowsim[cirq]"
python -m pip install "shadowsim[yaml]"
python -m pip install "shadowsim[all]"
Extra Provides
qutip QutipSimulator and QuTiP interop (from_qutip / to_qutip)
qiskit AerCircuitBackend and the Qiskit translation used by PauliPropagationBackend (qiskit, qiskit-aer, and scipy)
circuits Trotterization, Split JMatrix, Hybrid WML, and run_shadow_simulation (scipy)
viz Matplotlib plots (plot_results and benchmark figures)
pauli_propagation PauliPropagationBackend (juliacall 0.9.36). Julia 1.10+ and the Julia package are a separate install; see PauliPropagation
qulacs QulacsCircuitBackend
cirq CirqCircuitBackend
yaml Load YAML experiment files with shadowsim run (pyyaml)
all qutip, qiskit, circuits, viz, qulacs, cirq, and yaml

The package can then be imported as shadowsim. Importing a backend or plot helper without its extra raises an ImportError that names the extra to install.

For a local development install (uv sync --all-extras, tests, lint, scaffolding a simulator), see CONTRIBUTING.md.

Usage

Simulation builder

shadowsim serve opens the simulation builder, a local page for assembling and running a simulation. Cards come from the same catalogs as the research commands. Drag a card into a lane, or tap it to place it. Lanes run left to right.

Lane What you set
Initial state Basis, Gray, angle, or amplitude
Model A preexisting model, or operators you add
Method One or more simulators. Circuit methods take a backend; a classical reference such as QuTiP does not. The first row is the reference when several methods are compared
Measure Pauli expectations, counts, or the measurements the model defines
Then Plot the curves, save arrays and metadata, or export runtime and shot budget as JSON

The page checks the run as you edit it and shows the version 1 document in a code preview. Run simulation runs that document, and the curves appear in the results panel. Save and export paths stay under results/ (change the root with --output-dir). Export board downloads the layout as JSON, and Import board loads one back. The page is laid out for a desktop window.

shadowsim serve
shadowsim serve --host 127.0.0.1 --port 8000 --output-dir results --no-browser

The server binds 127.0.0.1:8000, prints a one-time URL that carries a startup token, and opens that URL in the default browser. A non-loopback address requires --allow-remote together with --tls-cert and --tls-key. Anyone who has the startup token can submit a run. A method or backend whose extra is not installed is left off the page. shadowsim serve --help lists every flag, and the run-document schema is in the CLI docs.

Command-line interface

Research commands (model, simulate, compare, run) build and run the same version 1 documents as the simulation builder. Examples and the document schema are in the CLI docs.

shadowsim model ising --qubits 4 --J 1.0
shadowsim simulate --model ising --qubits 2 --simulator trotterization --time-steps 2 --num-steps 1 --backend numpy
shadowsim compare --model ising --qubits 2 --simulator trotterization --time-steps 2 --num-steps 1 --backends numpy,aer
shadowsim run experiment.json

Python API

Public objects are imported from their domain subpackages:

from shadowsim.core import DensityOperator, Hamiltonian, Operator, State
from shadowsim.encoding import AmplitudeEncoding, AngleEncoding, ComputationalBasisEncoding, GrayEncoding
from shadowsim.shadow import ShadowHamiltonian, check_invariance
from shadowsim.simulators import QutipSimulator, SimulationResult

State encoding

shadowsim.encoding turns classical data into a normalized State. Simulators take that state as initial_state.

import numpy as np
from shadowsim.encoding import AmplitudeEncoding, AngleEncoding, ComputationalBasisEncoding, GrayEncoding

basis = ComputationalBasisEncoding(2).encode([1, 0])  # |10>
gray = GrayEncoding(2).encode([1, 0])  # |11>, Gray code of binary 2
angle = AngleEncoding().encode([np.pi / 2, 0.0])
amplitude = AmplitudeEncoding().encode([1.0, 1.0, 0.0])  # zero-padded to 2 qubits

load_encoding_data reads a 1D vector from a .npy, .txt, or .csv file for an encoder, as in AmplitudeEncoding().encode(load_encoding_data("amplitudes.npy")).

examples/state_encoding.py passes an encoded state to QutipSimulator.

QuTiP interop

With the qutip extra, convert between QuTiP Qobj values and ShadowSim core types:

from shadowsim.interop.qutip import from_qutip, to_qutip

H = from_qutip(qutip_H)  # → Hamiltonian
ops = [from_qutip(c) for c in c_ops]  # → Operator
psi = from_qutip(psi0)  # → State (ket)
rho = from_qutip(qutip_rho)  # → DensityOperator (Hermitian, PSD, tr≈1)
qobj = to_qutip(H)

Override with kind= when needed (e.g. kind="hamiltonian" for a unit-trace projector).

PauliPropagation

PauliPropagationBackend returns ⟨Z⟩ and ⟨X⟩ for selected qubits of one program, following Rudolph et al., arXiv:2505.21606. It translates that program to OpenQASM 2, so the qiskit extra is required as well. The pauli_propagation extra installs juliacall 0.9.36. Julia 1.10 or newer has to be available already. That juliacall release is the one that resolves next to the PauliPropagation revision below.

In the Julia project juliacall uses for this Python environment, install the OpenQASM reader:

import juliacall
from juliacall import Main as jl

jl.seval("using Pkg")
jl.seval('Pkg.add(url="https://github.com/SparqleSim/PauliPropagation.jl", rev="6e8c1ae")')

readqasm on that revision accepts OpenQASM 2 / qelib1 gates, skips barrier and id, and rejects measure, reset, and unknown gates. Qubit indexes are 0-based, and each method returns one float per index in that order. shots and seed are accepted and ignored. max_weight defaults to inf, so every Pauli weight is kept, and min_abs_coeff defaults to 1e-10. The simulation builder card edits both before a run.

import numpy as np

from shadowsim.backends import PauliPropagationBackend
from shadowsim.backends.program import Program, Unitary

half = 0.2
rx = np.array([[np.cos(half), -1j * np.sin(half)], [-1j * np.sin(half), np.cos(half)]])
program = Program(1, 0, [Unitary(rx, (0,))])
backend = PauliPropagationBackend()
backend.z_expectations(program, [0], shots=1, seed=None)  # [cos(0.4)]
backend.x_expectations(program, [0], shots=1, seed=None)  # [0.0]

RX(0.4) applied to |0⟩ stays in the YZ plane, so ⟨X⟩ is 0. run_counts raises NotImplementedError. TrotterizationSimulator and the simulation builder can run a closed Trotter program on this backend: product states are prepared with single-qubit gates, the program is translated to Qiskit and transpiled into gates the reader accepts, and every qubit returns the expectation of its basis letter. It is an expectation backend, so it has no shot counts (see Measurements). Split JMatrix and Hybrid WML sample an ancilla and stay on Aer.

Simulation results

Each backend’s simulate() / run() returns a SimulationResult with:

  • times, observables (one curve per measurement), optional states (usually None)
  • counts: one bitstring-to-shots dict per time point from a sampling backend, otherwise None
  • seed, algorithm, runtime, and metadata (software version, grid params, backend params)

Serialize and reload with result.save(path) / SimulationResult.load(path) (directory of times.npy, numeric .npz archives, counts.json when there are counts, and meta.json). Loading does not unpickle array files. Low-level curves remain on simulator.results for plotting and benchmarking.

Measurements

Circuit simulators stop at the measurement. Before measuring, they rotate each qubit into its letter of basis (default all Z; X adds a Hadamard, Y adds S†, stored as a 2×2 unitary, then a Hadamard). What comes back depends on the circuit backend:

  • Sampling backends such as AerCircuitBackend have a shots budget and return counts. result.counts holds one dict per time point, and observables stays empty until you measure. Any Measurement can read them.
  • Expectation backends such as PauliPropagationBackend, NumpyCircuitBackend, QulacsCircuitBackend, and CirqCircuitBackend have no shot budget. Trotterization fills observables with each qubit's ⟨P⟩ for its basis letter and leaves counts empty. A one-qubit measurement is read from that distribution: counts["0"] is (1 + ⟨P⟩) / 2, counts["1"] is (1 - ⟨P⟩) / 2, and shots is 1. Dividing by shots gives the infinite-shot value. An expression that uses raw counts without shots reads those probabilities. Two or more qubits need a sampling backend, because the result has no correlations between qubits.

In every counts key, bit i is system qubit i (Qiskit's order is reversed before the counts are stored). Split JMatrix drops its ancilla bit, so its keys cover the system qubits only.

A Measurement names some qubits and an arithmetic expression on their counts. Keys list those qubits in the order given, and shots is the total for that time point. Expressions may use numbers, parentheses, + - * / **, shots, and counts["01"]; a bitstring that never appeared is 0. simulator.measure(...) evaluates a list of measurements at every time point and returns a result with one curve per measurement. apply_measurements(result, ...) does the same for a result you already have.

from shadowsim.backends import AerCircuitBackend
from shadowsim.models import ising
from shadowsim.simulators import Measurement, TrotterizationSimulator

model = ising(n_qubits=3)
simulator = TrotterizationSimulator(
    model.local_hamiltonians,
    [],
    model.psi0,
    num_qubits=model.num_qubits,
    total_time=1.0,
    time_steps=11,
    num_steps=4,
    basis="ZZX",
    circuit_backend=AerCircuitBackend(shots=1000),
)
simulator.simulate()
result = simulator.measure(
    [
        Measurement((2,), '(counts["0"] - counts["1"]) / shots', "expectation on 2"),  # ⟨X⟩ on qubit 2
        Measurement((0, 1), '(counts["00"] + counts["11"]) / shots', "qubits 0 and 1 agree"),
    ]
)

counts["1"] / shots is the fraction of shots where that qubit read 1. A Tavis–Cummings cavity stored on two qubits uses (3 * counts["11"] + 2 * counts["10"] + counts["01"]) / shots for its mean photon number.

start() runs that same simulate() call on a worker thread and returns a SimulationJob immediately. Poll status (pending, running, succeeded, or failed). result() waits for the SimulationResult; pass timeout to stop waiting while the job is still running, which raises TimeoutError. If simulate() raised, result() raises that exception. Split J and Trotter jobs count finished time points in completed_steps and total_steps. A QuTiP job leaves both as None.

The following simulators are supported by the package:

Name Type Can handle open systems
Qutip simulator classical reference true
Split JMatrix quantum-inspired true
Trotterization quantum-inspired false
Hybrid wave-matrix Lindbladization quantum-inspired true

Backends

The circuit simulators hand each time point's program to a circuit backend, passed as circuit_backend=. QuTiP integrates the master equation itself and takes no backend. The following backends are supported:

Backend Kind Simulators Extra
AerCircuitBackend sampling: returns shot counts from a shots budget Split JMatrix, Trotterization, Hybrid WML qiskit
NumpyCircuitBackend expectation: exact Pauli expectations from a NumPy statevector. run_counts can still sample Trotterization (closed systems) core
PauliPropagationBackend expectation: returns exact Pauli expectations, no counts Trotterization (closed systems) qiskit and pauli_propagation
QulacsCircuitBackend expectation: exact Pauli expectations from a Qulacs statevector. run_counts can still sample Trotterization (closed systems) qulacs
CirqCircuitBackend expectation: exact Pauli expectations from a Cirq statevector. run_counts can still sample Trotterization (closed systems) cirq

AerCircuitBackend is the default for the circuit simulators. Split JMatrix and Hybrid WML sample an ancilla, so they need a sampling backend. See Measurements for what each kind returns and PauliPropagation for the Julia setup.

NumpyCircuitBackend is the reference for small circuits. Correctness and readability come before performance. It stores no shots attribute, so Trotterization reads exact ⟨Z⟩ and ⟨X⟩. run_counts still samples the computational basis, and the same seed repeats those counts. Reset and a measurement followed by a gate are rejected. Split JMatrix and Hybrid WML sample an ancilla with Reset, so they use Aer.

Checked circuits agree with Aer statevector probabilities to 1e-8. One local Hamiltonian makes the Trotter product exact: that ⟨Z⟩ curve matches cos(2t) to 1e-8 and QuTiP to 1e-6. A seeded Hadamard of 4000 shots stays within 0.05 of Aer and of 1/2.

import numpy as np

from shadowsim.backends import NumpyCircuitBackend
from shadowsim.backends.program import Program, Unitary

half = 0.2
rx = np.array([[np.cos(half), -1j * np.sin(half)], [-1j * np.sin(half), np.cos(half)]])
program = Program(1, 0, [Unitary(rx, (0,))])
backend = NumpyCircuitBackend()
backend.z_expectations(program, [0], shots=1, seed=None)  # [cos(0.4)]
backend.x_expectations(program, [0], shots=1, seed=None)  # [0.0]

QulacsCircuitBackend is the same kind of expectation backend, with the statevector evolved by Qulacs. It does not need Qiskit. It stores no shots attribute, so Trotterization reads exact ⟨Z⟩ and ⟨X⟩. run_counts still samples the computational basis, and the same seed repeats those counts. Reset and a measurement followed by a gate are rejected. Split JMatrix and Hybrid WML sample an ancilla with Reset, so they use Aer.

Statevectors agree with NumpyCircuitBackend to 1e-8. One local Hamiltonian makes the Trotter product exact: that ⟨Z⟩ curve matches cos(2t) to 1e-8. A seeded Hadamard of 4000 shots stays within 0.05 of NumPy and of 1/2. examples/qulacs_benchmark.py times the two backends on one closed Trotter circuit. That script is not part of the test run.

import numpy as np

from shadowsim.backends import QulacsCircuitBackend
from shadowsim.backends.program import Program, Unitary

half = 0.2
rx = np.array([[np.cos(half), -1j * np.sin(half)], [-1j * np.sin(half), np.cos(half)]])
program = Program(1, 0, [Unitary(rx, (0,))])
backend = QulacsCircuitBackend()
backend.z_expectations(program, [0], shots=1, seed=None)  # [cos(0.4)]
backend.x_expectations(program, [0], shots=1, seed=None)  # [0.0]

CirqCircuitBackend is the same kind of expectation backend, with the statevector evolved by Cirq. It does not need Qiskit. It stores no shots attribute, so Trotterization reads exact ⟨Z⟩ and ⟨X⟩. run_counts still samples the computational basis, and the same seed repeats those counts. Reset, a measurement followed by a gate, and circuit metrics are rejected. Split JMatrix and Hybrid WML sample an ancilla with Reset, so they use Aer.

Statevectors agree with NumpyCircuitBackend to 1e-8. One local Hamiltonian makes the Trotter product exact: that ⟨Z⟩ curve matches cos(2t) to 1e-8. A seeded Hadamard of 4000 shots stays within 0.05 of NumPy and of 1/2.

import numpy as np

from shadowsim.backends import CirqCircuitBackend
from shadowsim.backends.program import Program, Unitary

half = 0.2
rx = np.array([[np.cos(half), -1j * np.sin(half)], [-1j * np.sin(half), np.cos(half)]])
program = Program(1, 0, [Unitary(rx, (0,))])
backend = CirqCircuitBackend()
backend.z_expectations(program, [0], shots=1, seed=None)  # [cos(0.4)]
backend.x_expectations(program, [0], shots=1, seed=None)  # [0.0]

Sparse / Pauli-label shadow construction

Pass Pauli labels (or PauliSums) for both the Hamiltonian and the observables so ShadowHamiltonian can build H_S in label space—no 4^n tomography and no full 2^n × 2^n matrix multiplies during construction:

from shadowsim.core import Hamiltonian, OperatorSet
from shadowsim.shadow import ShadowHamiltonian

shadow = ShadowHamiltonian(
    OperatorSet(["XII", "YII", "ZII", "IIX"]),
    [Hamiltonian("XII"), Hamiltonian("IIX")],
)
assert shadow.used_sparse_pauli_path
print(shadow.H_S.shape)  # (|closure|, |closure|)

Dense matrices and LocalHamiltonian terms still work; they take the densifying fallback (used_sparse_pauli_path is False). See also examples/simple_shadow.py.

To check whether a given operator set already satisfies the invariance property (closed under [H, ·]) without building a full shadow simulation, use check_invariance. It reports whether the set is closed, how many Pauli labels must be added to close it, and whether the closed-basis H_S is Hermitian:

from shadowsim.core import Hamiltonian, OperatorSet
from shadowsim.shadow import check_invariance

report = check_invariance(
    OperatorSet(["Z"]),
    Hamiltonian("X"),
)
assert not report.is_closed
assert report.growth == 1
assert report.added_paulis == frozenset({"Y"})

For practical scale limits (sparse vs dense, closure size, simulators), see Scalability / practical limits.

Scalability / practical limits

Shadow construction

  • Prefer Pauli labels / PauliSum so ShadowHamiltonian takes the sparse path (used_sparse_pauli_path). Cost then tracks Hamiltonian Pauli terms × closure size m, not 4^n.
  • Dense fallback (dense matrices / LocalHamiltonian): practical for small n (roughly ≤3–4 as historically exercised). Bottleneck is 4^n Pauli tomography plus dense 2^n linear algebra.
  • Closure size m can grow independently of Hilbert-space dimension; H_S is always m×m (not 2^n×2^n).
  • Inspect cost before a long run: ShadowHamiltonian(..., verbose=True) prints Hamiltonian Pauli count, operator-set union size, and closure size.

What works today

Path Practical scale today Bottleneck
ShadowHamiltonian (Pauli labels) few-term models; n past ~3–4 when closure stays small Pauli terms × closure size m
ShadowHamiltonian (dense / local) small n (~≤3–4) 4^n tomography + dense mats
QuTiP simulator small truncated models stiff ODEs / Hilbert dim
Split JMatrix + Aer tiny time grids / shot budgets for smoke; set seed for reproducible Aer shots circuit per timestep × shots
Trotterization + Aer closed systems only; tiny time grids / shot budgets; set seed for reproducible Aer shots circuit per timestep × shots
Trotterization + NumPy small closed systems used as a reference one statevector of length 2^n per time point

Not yet / still heavy

For shadow construction, use the sparse / Pauli-label path whenever you already have a Pauli decomposition.

Examples

Example 1: Exploring a simple shadow simulation

The complete example is in examples/simple_shadow.py and can be run after uv sync --all-extras:

uv run python examples/simple_shadow.py

That example uses Pauli labels (sparse construction path) and run_shadow_simulation for the reduced shadow dynamics. Pass a circuit backend: NumpyCircuitBackend, QulacsCircuitBackend, and CirqCircuitBackend give exact curves, and a sampling backend such as AerCircuitBackend estimates them from its shots.

from shadowsim.backends.numpy import NumpyCircuitBackend

shadow = run_shadow_simulation(
    hamiltonians,
    observables,
    initial_state,
    total_time=5.0,
    time_steps=400,
    circuit_backend=NumpyCircuitBackend(),
)

shadow.expectations holds the signed ⟨O_k⟩(t) for each operator in the closure basis, labeled by shadow.basis, so the curves line up with a QuTiP run on the physical system. Pass shadow_observables (for example computational_basis_projectors) to also get quadratic shadow-space curves in shadow.shadow_observable_expectations. The returned result can save and load the shadow traces, and plot_results draws them. Pass verbose=True to run_shadow_simulation if you want Pauli-set and closure sizes printed.

Example 2: Comparing a quantum algorithm against a classical solver

This is a paper-scale QuTiP vs Split JMatrix + Aer comparison (301 time points and a non-trivial shot budget)—expect long wall time and nontrivial Aer cost; it is not a CI smoke test. The runnable script examples/simple_algo_benchmark.py uses the same scale; there is no reduced smoke grid yet. See Scalability / practical limits.

Imagine a scenario in which you want to compare the results of a new quantum simulation algorithm against a source of truth like QuTiP.

We build the open cavity–emitter (Tavis–Cummings–like) model with the shared factory. Defaults match the historical Example 2 parameters; pass n_emitters, g, kappa, and friends to change the physics without rewriting operator embeddings.

from shadowsim.backends import AerCircuitBackend
from shadowsim.benchmarking import Benchmark
from shadowsim.models import tavis_cummings
from shadowsim.simulators import QutipSimulator, SplitJMatrixSimulator

model = tavis_cummings()

Next, we create two simulators, one for the new algorithm and one for the source of truth.

# Qutip simulator
qutip_simulator = QutipSimulator(
    model.full_hamiltonians,
    model.c_ops_full,
    model.psi0,
    model.e_ops,
    num_qubits=model.num_qubits,
    total_time=0.25,
    time_steps=301,
)
# Split JMatrix simulator
splitjmatrix_simulator = SplitJMatrixSimulator(
    model.local_hamiltonians,
    model.c_ops_local,
    model.psi0,
    num_qubits=model.num_qubits,
    total_time=0.25,
    time_steps=301,
    num_steps=40,
    circuit_backend=AerCircuitBackend(shots=10000),
)

To easily compare results, we initialize a benchmark with a reference simulator and one or more challengers. All simulators must share the same time grid. We run the benchmark, which runs the underlying simulations. Split JMatrix only records counts, so we then apply model.measurements, which estimate the same quantities as the QuTiP e_ops: the cavity population on qubits 0 and 1, and the emitter population on qubit 2. Every model lists measurements that match its e_ops this way. Numeric L∞ / L2 / MAE / RMSE error metrics vs the reference are available via error_metrics. Wall-clock time, shot budget (when the circuit backend stores shots), and circuit metrics are available via resource_metrics. Those metrics are the depth, qubit width, gate count, T count, and Toffoli count of the final-time circuit after the backend transpiles it. Each is N/A when the backend cannot report it, including QuTiP and Pauli propagation. Error and resource rows are exported together by save_error_metrics as {"errors": ..., "resources": ...}. save_result_plot saves a plot per simulator and an absolute-difference plot vs the reference for each challenger. The third figure below shows L∞, MAE, and RMSE from error_metrics. Those three share a per-time-point scale.

QuTiP is deterministic. Split JMatrix estimates populations from the finite shots budget on AerCircuitBackend, so the comparison moves run to run unless you set seed (wired into Aer’s seed_simulator). Residual disagreement also includes systematic split-J / Trotter bias that does not vanish with more shots. Use a lower shots value on that backend for smoke checks and a higher budget for publication figures; pass verbose=True or a progress(step, total) callback for long-run feedback. workers=1 (the default) runs each time point serially. A larger workers value runs those independent points on a process pool; traces stay in tlist order.

benchmark = Benchmark(qutip_simulator, splitjmatrix_simulator)
benchmark.run()
splitjmatrix_simulator.measure(model.measurements)
print(benchmark.error_metrics())
print(benchmark.resource_metrics())
metrics_path = benchmark.save_error_metrics()
paths = benchmark.save_result_plot(labels=["cavity population", "emitter population"])
for path in [metrics_path, *paths]:
    print(f"Saved: {path}")

Output

QuTiP (reference):

QuTiP expectations

Split JMatrix:

Split JMatrix expectations

L∞, MAE, and RMSE vs QuTiP:

L∞, MAE, and RMSE versus QuTiP

Example 3: Classical and transverse-field Ising models

examples/ising_chain.py builds Ising Hamiltonians with the shared factory and evolves a small open transverse-field chain in QuTiP.

uv run python examples/ising_chain.py
from shadowsim.models import ising
from shadowsim.simulators import QutipSimulator

# Transverse-field Ising: H = J Σ Z_i Z_j + h Σ X_i
model = ising(
    n_qubits=4,
    J=1.0,
    h=0.5,
    field="transverse",  # or "classical" for a Z field
    topology="chain",
    boundary="open",  # or "periodic"
)

# Custom connectivity (overrides chain presets)
custom = ising(
    n_qubits=4,
    J=1.0,
    h=0.5,
    field="classical",
    edges=[(0, 1), (1, 2), (2, 3), (0, 2)],
)

simulator = QutipSimulator(
    model.full_hamiltonians,
    model.c_ops_full,  # empty; closed system
    model.psi0,
    model.e_ops,
    num_qubits=model.num_qubits,
    total_time=2.0,
    time_steps=101,
)
result = simulator.simulate()

Use model.hamiltonian or model.pauli_sum when you only need the combined Hamiltonian (for example with run_shadow_simulation). Every ZZ edge and every single-site field is also available as model.local_hamiltonians. A long-range edge, including the periodic wrap, is a two-site term on its endpoints.

Example 4: Encoding classical data as an initial state

examples/state_encoding.py prepares computational-basis, angle, and amplitude states, then evolves the amplitude state with QuTiP.

uv run python examples/state_encoding.py

Example 5: Coupled oscillators on a smaller register

examples/coupled_oscillators.py evolves a three-mass spring network four ways. Newton's equations are the reference. The block encoding of Babbush et al. and the shadow Hamiltonian of Somma et al. (change_of_basis) both have dimension 6 and pad to 3 qubits. The same means from a truncated Fock-space QuTiP run use cutoff 8, which is 9 qubits. The script prints the position, momentum, and first-mass kinetic-fraction deviations, then plots that fraction. It needs the qutip and viz extras.

uv run python examples/coupled_oscillators.py

Documentation

Contributing

See CONTRIBUTING.md for development setup, tests, linting, simulator scaffolding, and pull-request guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.

Citing

Cite this software with the metadata in CITATION.cff. The DOI is added there after the GitHub release mints it. See the changelog for what 1.0.0 keeps stable.

References

See the documentation bibliography.

Metadata

Release files for shadowsim 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shadowsim 1.0.0
File Size Uploaded Provenance Actions
shadowsim-1.0.0.tar.gz 218.4 kB With provenance Details for shadowsim-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for shadowsim 1.0.0
File Interpreter ABI Platform Actions
shadowsim-1.0.0-py3-none-any.whl Python 3 none any Details for shadowsim-1.0.0-py3-none-any.whl

Total release size: 470.8 kB

Release files / shadowsim-1.0.0.tar.gz

Download URL shadowsim-1.0.0.tar.gz
Size 218.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7f02d3a578d358e9b8a0af9acb4d9dad03c07316682247e92aa529659dbe2132
BLAKE2b-256 checksum
How to use checksums
8b905fc862a2337aa6922b7b9474c28b27a6abe7e5dacdaed6b325c6f68073c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / shadowsim-1.0.0-py3-none-any.whl

Download URL shadowsim-1.0.0-py3-none-any.whl
Size 252.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a4fc7628102e9abfce154df16b6190eeb5a037f82c7dd7aa7982a846be314822
BLAKE2b-256 checksum
How to use checksums
29d5f052278317c36089eefaf10e8defaaff5fb42fba08a7d245d681e29ade78
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for shadowsim 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for shadowsim-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page