Examples¶
Thirteen runnable scripts ship with the package, ordered so each builds on the ones before it. They cover the simulator from a first Bell pair through noise, qubit layout, the low-level MPS/MPO API, engine selection, qudits, and the Qiskit integration. Each is deterministic for a fixed seed.
Where they are¶
The examples are bundled inside the installed package:
From a source checkout they live in
tensorweaver-python/python/tensorweaver/examples/.
Running¶
import subprocess, sys, tensorweaver as tw
script = tw.examples_dir() / "01_bell_pair" / "main.py"
subprocess.run([sys.executable, str(script)])
Or directly from a source checkout. Build both engines first, since the default
engine is OpenBLAS and maturin develop alone does not compile it:
cd tensorweaver-python
scripts/dev-build.sh
uv run python python/tensorweaver/examples/01_bell_pair/main.py
Most scripts take flags such as --seed, --n, --shots, and --depth. Run
one with --help for its options.
Index¶
| # | Folder | What it covers |
|---|---|---|
| 01 | 01_bell_pair |
The simplest entangled circuit: Circuit, execute, cstates, amplitudes, and ExpectationValue / SchmidtRank through the z-register. |
| 02 | 02_ghz_scaling |
GHZ(n) for n up to 300 at χ = 2. Bond dimension as the resource that decides feasibility, probed with BondDim z-vars. |
| 03 | 03_observables |
A depth-2 brickwork ansatz. ExpectationValue on single-qubit operators and Pauli strings, plus BondDim and SchmidtRank at every cut. |
| 04 | 04_qft |
Quantum Fourier Transform from H, controlled phases, and a final bit reversal, checked against the analytic Fourier amplitudes. |
| 05 | 05_bond_sweep |
Random brickwork at fixed depth, sweeping χ over {2, 4, 8, 16, 64}. Reported fidelity, ℓ² distance to a high-χ reference, and timings side by side. |
| 06 | 06_noise_trajectories |
AmplitudeDamping and Depolarizing after gates. Trajectory mode is selected automatically; the histogram is compared against the noiseless run. |
| 07 | 07_layout_and_serialize |
Long-range-pair circuits under reorderqubits=False, "greedy", and "sa", checking all three agree while χ and timings differ. Plus MPS.serialize / MPS.deserialize. |
| 08 | 08_low_level_mps |
Driving an MPS without Circuit or execute: apply_gate_1q, apply_gate_2q, compress, sample, measure_qubit, expectation_1q, von_neumann_entropy. |
| 09 | 09_mpo_algorithms |
Build a circuit as one MPO, then apply it with each of "dmpo", "vmpoa", and "vmpob", comparing fidelity and runtime. Plus dagger() and MPO serialisation. |
| 10 | 10_two_sided_mpo |
The side= argument: build the same operator all-output, interleaved, and by direct gate-by-gate evolution, then check the three agree. |
| 11 | 11_engine_selection |
Choosing the BLAS engine with usemkl. OpenBLAS and MKL agree for a fixed seed and run side by side; objects are engine-specific, so state moves across via serialize / deserialize. |
| 12 | 12_qiskit_backend |
Driving TensorWeaver from Qiskit: TensorWeaverBackend as a BackendV2, sampling through BackendSamplerV2, and expectation values with TensorWeaverEstimator. Needs the qiskit extra. |
| 13 | 13_qudits |
d-level sites on the low-level API: zero_state_qudits / product_state_qudits, d×d gates and expectation values, a qutrit Kraus channel, and fusing two qubits into one d = 4 site. |
Reading order¶
The examples are written to be read in order. If you already know what an MPS is, useful entry points are:
- 05 for the χ-versus-fidelity trade-off.
- 06 for noise and trajectory mode.
- 07 for qubit layout.
- 08 to 10 for the low-level surface that
execute()uses internally. - 13 for qudits.