Examples

Sixteen 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, the Qiskit integration, and gate-by-gate simulation. Each is deterministic for a fixed seed. The two 00_ scripts run without a licence, on the public wheel; the rest need the licensed one.

Where they are

The examples are bundled inside the installed package:

import tensorweaver as tw
print(tw.examples_dir())   # .../site-packages/tensorweaver/examples

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
00	00_mock_backend	MockTensorWeaver: checking what a MIMIQ backend accepts and returns, with no simulation and no licence.
00	00_mps_structure	The MPS itself, with no gates: constructors, reading and writing site tensors, the gauge, overlaps, the entanglement read-outs and serialisation.
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", "cmpo", "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 linear-algebra engine with linalg ("openblas", "mkl", "faer"). Unset, it resolves to whichever engine the platform's wheel carries; the engines agree for a fixed seed and run side by side where both exist; 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, exact and averaged over trajectories. 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.
14	14_direct_simulator	TwDirectSimulator: gates applied one at a time with swap routing and no MPO, compared with MPO fusion on a QFT-like circuit; the two routings; the routed state and sorting it back.

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.