quantum-debugger 0.9.0__tar.gz → 1.0.0__tar.gz

{quantum_debugger-0.9.0 → quantum_debugger-1.0.0}/CHANGELOG.md

@@ -5,6 +5,172 @@ All notable changes to QuantumDebugger will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0]
+
+Theme: scale & tensor networks — breaking the exponential state-vector wall. The
+headline is a full **matrix product state** engine (`quantum_debugger.mps.MPS`):
+construction from a state vector or a `QuantumCircuit`, exact single-qubit and
+SVD-truncated two-qubit gates (nearest-neighbour and long-range via SWAP networks),
+and a complete `O(n·chi^2)` readout toolkit — expectation values, arbitrary
+Pauli-string and Pauli-sum-Hamiltonian energies, correlations, entanglement entropy
+across every bond, overlap/fidelity between states, and exact Born-rule sampling —
+none of which ever forms the dense state. On top of it, TEBD gives real-time dynamics
+and imaginary-time DMRG-style ground states. Every MPS operation is verified against
+the state-vector simulator; the engine scales to 100-qubit GHZ states, 40-qubit
+quenches, and 24-qubit ground states — moving the library from "≤25 qubits exactly"
+to "hundreds of qubits when entanglement allows." (The major-version bump the
+tensor-network capability earns.)
+
+### Added
+- **MPS two-site expectation** (`MPS.two_site_expectation`) — the expectation of any
+  two-qubit operator (4x4) via the two-qubit reduced density matrix `Tr(O rho_ab)`,
+  matching the dense value and `<ZZ>` correlations — the primitive for bond energies.
+- **MPS truncation error & normalization** (`MPS.truncation_error`, `MPS.normalize`) —
+  the weight lost when compressing to a target bond dimension (`1 - fidelity`, exactly
+  0 for a GHZ at bond ≥ 2, decreasing as the bond grows) and in-place unit
+  normalization — the diagnostics that make bond-dimension choices principled.
+- **MPS two-qubit correlations** (`MPS.two_qubit_rdm`, `MPS.mutual_information`,
+  `MPS.concurrence`) — the reduced density matrix of any qubit pair assembled from
+  their 16 two-qubit Pauli expectations (scalable, matching the dense partial trace),
+  and the pairwise mutual information and Wootters concurrence from it (a Bell pair
+  giving 2 bits and concurrence 1, a product pair giving 0).
+- **MPS amplitudes & basis states** (`MPS.amplitude`, `MPS.probability`,
+  `MPS.from_bitstring`, `MPS.most_probable`) — the amplitude `<bits|psi>` of any
+  computational-basis string by contracting fixed-bit tensor slices (`O(n·chi^2)`,
+  matching the dense value, probabilities summing to 1), a basis-state constructor,
+  and the most-probable outcome from sampling (a GHZ returning `0000`/`1111` at
+  probability 0.5).
+- **Heisenberg MPO** (`mpo.heisenberg_mpo`) — the bond-dimension-5 matrix product
+  operator for `H = J sum (XX + YY + ZZ)`, verified to contract to the exact dense
+  Heisenberg Hamiltonian.
+- **MPS Bloch vectors & purity profile** (`MPS.bloch_vector`, `MPS.purity_profile`) —
+  each qubit's `(<X>,<Y>,<Z>)` and its purity `Tr(rho_i^2)` (a GHZ giving zero Bloch
+  vectors and 0.5 purity everywhere, a product state giving unit purity) — a local
+  read of how entangled each site is.
+- **MPS structure factor & magnetization** (`MPS.structure_factor`,
+  `MPS.total_magnetization`, `MPS.schmidt_gap`) — the static structure factor
+  `S(k) = (1/n) sum e^{ik(i-j)} <O_i O_j>` (verified against the dense computation and
+  peaking at `S(0)=n` for a ferromagnet), the summed magnetization, and the
+  entanglement-spectrum Schmidt gap (an order parameter that closes at a transition).
+- **Apply an MPO to an MPS** (`MPS.apply_mpo`, `MPS.expectation_mpo`) — compute
+  `H|psi>` by contracting a matrix product operator into the state (bond dimensions
+  multiply, optionally recompressed), verified to match the dense `H·psi`; plus a
+  convenience `expectation_mpo` matching `MPS.energy`.
+- **MPS reduced density matrix & entanglement spectrum** (`MPS.single_qubit_rdm`,
+  `MPS.entanglement_spectrum`) — a qubit's reduced density matrix from its Pauli
+  expectations (scalable, matching the dense partial trace) and the full Schmidt
+  spectrum across any bond (a Bell cut giving `[0.707, 0.707]`, squares summing to 1).
+- **Matrix Product Operators** (`quantum_debugger.mpo`: `tfim_mpo`, `mpo_expectation`,
+  `mpo_to_matrix`) — the operator analogue of an MPS: a Hamiltonian as a chain of
+  rank-4 tensors (the TFIM needs only bond dimension 3), so `<psi|H|psi>` on a large
+  MPS costs `O(n·chi^2·D^2)` with no dense operator. Verified: the MPO contracts to the
+  exact dense TFIM Hamiltonian, its expectation matches both the dense and the
+  `MPS.energy` value, and a 30-qubit GHZ gives the exact `-J(n-1)`.
+- **MPS construction helpers** (`MPS.from_product`, `MPS.random`) — build a product
+  state from per-qubit amplitudes (bond dimension 1) or a reproducible random MPS at a
+  target bond dimension; verified normalized with the expected structure.
+- **MPS linear algebra** (`MPS.add`, `MPS.compress`) — sum two MPS by the
+  direct-sum-of-bonds construction (matching the dense `(a+b)`), and recompress to a
+  smaller bond dimension (a GHZ compresses to bond 2 losslessly, fidelity 1).
+- **MPS magnetization & correlation profiles** (`MPS.magnetization_profile`,
+  `MPS.correlation_profile`) — `<O_i>` on every site and the spatial correlation
+  function `<O_a(ref) O_b(j)>` by contraction; a GHZ gives zero magnetization and unit
+  correlation across the chain.
+- **MPS energy variance** (`MPS.variance`) — `<H^2> - <H>^2` of a Pauli-sum
+  Hamiltonian, exactly 0 on an eigenstate and positive off it — the convergence check
+  for tensor-network ground-state methods.
+- **MPS Renyi entanglement entropy** (`MPS.renyi_entropy`) — Renyi-`alpha` entropy
+  across any bond from the canonicalized Schmidt spectrum (`alpha=1` recovers von
+  Neumann, `alpha=2` the collision entropy), verified non-increasing in `alpha`.
+- **MPS Hamiltonian energy** (`MPS.energy`) — evaluate `<psi|H|psi>` for any
+  Hamiltonian given as `(coefficient, pauli_string)` terms (the `pauli_decompose` /
+  VQE format) on a matrix product state, summing Pauli-string expectations by
+  contraction. Verified against dense for TFIM and a Pauli-decomposed Fermi-Hubbard
+  Hamiltonian, and a GHZ gives the exact `-J(n-1)` — connecting the chemistry/spin
+  Hamiltonians of 0.9 to the large-scale MPS engine.
+- **MPS Pauli-string expectation** (`MPS.expectation_pauli`) — the expectation of any
+  multi-qubit Pauli observable `<psi|P|psi>` on a matrix product state by
+  `O(n·chi^3)` contraction. Verified against the dense value for all 256 Pauli strings
+  on 4 qubits, and a 20-qubit GHZ correctly returns `<X^20> = 1` (its stabilizer) —
+  measuring arbitrary observables on systems too large to store densely.
+- **Circuit → MPS runner** (`MPS.from_circuit`) — run an existing `QuantumCircuit` on
+  the tensor-network engine: single-qubit gates applied exactly, two-qubit gates via
+  the long-range SWAP path (either control/target ordering handled by re-indexing the
+  4x4 matrix), three-plus-qubit gates rejected with a clear message to decompose first.
+  Verified to reproduce the state-vector result exactly on mixed random circuits and
+  reversed-control CNOTs, with a GHZ circuit staying at bond dimension 2. (Note: the
+  scale ceiling here is the `QuantumCircuit` object itself, which allocates a dense
+  state; to exceed it, drive the `MPS` directly.)
+- **MPS long-range two-qubit gates** (`MPS.apply_two_long_range`) — apply a two-qubit
+  gate to *any* pair of qubits (not just neighbours) via a nearest-neighbour SWAP
+  ladder: swap the qubits together, apply the gate, swap back. Verified against the
+  state-vector simulator for all pairs and asymmetric random unitaries, correctly
+  delegating for adjacent qubits, and building a long-range Bell pair between qubits 0
+  and 9 — so arbitrary-connectivity circuits run on the MPS engine.
+- **MPS overlap & fidelity** (`MPS.overlap`, `MPS.fidelity`) — the inner product
+  `<phi|psi>` of two matrix product states by the double-layer `O(n·chi^3)`
+  contraction, and the state fidelity from it. Verified to match the dense inner
+  product exactly, self-fidelity is 1 (including a 40-qubit GHZ), and orthogonal states
+  give zero overlap — comparing tensor-network states without ever forming them
+  densely.
+- **MPS entanglement entropy** (`MPS.bond_entropies`, `MPS.entanglement_entropy`) —
+  the entanglement entropy across every bond, read from the Schmidt spectrum by
+  canonicalizing the network (right-to-left then left-to-right SVD sweeps), scaling to
+  large `n` with no dense state. Verified to match the dense density-matrix
+  entanglement entropy exactly at every cut; a product state gives 0, a GHZ exactly 1
+  bit across every bond — including a 60-qubit GHZ whose full entropy profile is
+  computed instantly.
+- **MPS measurement sampling** (`MPS.sample`) — draw computational-basis shots from a
+  matrix product state by exact sequential conditional sampling with precomputed right
+  environments, `O(shots·n·chi^2)`, never forming the dense state. Verified: the
+  empirical distribution matches the dense Born rule to within shot noise on random
+  states, Bell/GHZ give only their correlated outcomes, a product state is
+  deterministic, and shot counts are conserved — measurement statistics from systems
+  far too large to store as a state vector.
+- **Imaginary-time TEBD ground states** (`algorithms.imaginary_tebd_ground_state`,
+  `tfim_mps_energy`) — DMRG-style ground-state search on the MPS: apply imaginary-time
+  bond gates `e^{-h dtau}` (cooling), renormalize, and settle into the ground state.
+  Verified against exact diagonalization (error < 5e-3 for n = 4/6/8, improving with
+  finer steps), respects the variational lower bound, and finds the ground state of a
+  **24-qubit** chain that no dense diagonalizer could reach — with the energy per site
+  extensive across sizes. `tfim_mps_energy` reads the TFIM energy off any MPS by
+  contraction, matching the dense value exactly.
+- **TEBD time evolution** (`algorithms.tebd_tfim`, `tebd_magnetization`,
+  `tfim_bond_gate`) — real-time many-body dynamics on the MPS: Trotterize
+  `e^{-iHt}` into two-site gates, apply them even-then-odd, and let the SVD truncation
+  bound the bond dimension. Verified to match exact state-vector evolution to fidelity
+  > 0.9999 on small TFIM chains (finer Trotter steps improving it), runs a 30-qubit
+  quench beyond the dense simulator's reach, keeps the bond capped at `max_bond`, and
+  reproduces the physics — a vanishing field freezes the magnetization (`|0...0>` is an
+  eigenstate) while a transverse field tilts the spins.
+- **Matrix Product State simulator** (`quantum_debugger.mps.MPS`) — the 1.0 flagship:
+  a tensor-network engine that breaks the exponential state-vector wall for
+  low-entanglement states. Represents an n-qubit state as a chain of rank-3 tensors
+  with bond dimension `chi` (`O(n·chi^2)` memory instead of `2^n`), applies
+  single-qubit gates exactly and neighbouring two-qubit gates by SVD with truncation
+  to `max_bond` (the DMRG/TEBD approximation), and computes norms, expectation values,
+  and two-point correlations by `O(n·chi^3)` contraction — never forming the dense
+  state. Verified: exact state-vector roundtrip, single- and two-qubit gates
+  (including asymmetric random unitaries) match the state-vector simulator to 1e-10,
+  bond dimensions correctly detect structure (product → 1, GHZ → 2), and a **100-qubit
+  GHZ** builds instantly at bond dimension 2 with correct `<Z0 Z99> = 1`, `<X0> = 0` —
+  a `2^100`-amplitude state held in a handful of small tensors.
+
+## [0.9.1]
+
+Theme: correctness patch for the depolarizing noise channel.
+
+### Fixed
+- **`DepolarizingNoise.get_kraus_operators()`** now implements the same channel as
+  `DepolarizingNoise.apply()` and the class docstring — the Pauli-error convention
+  `ρ → (1−p)ρ + (p/3)(XρX + YρY + ZρZ)`, giving `K₀ = √(1−p)·I` and `K₁₋₃ = √(p/3)·{X, Y, Z}`.
+  It previously used a `√(p/4)` weighting (the uniform `ρ → (1−p)ρ + pI/2` convention), which
+  agrees with `apply()` only under the substitution `p → 4p/3`. Because
+  `StochasticNoiseSampler` consumes the Kraus path, Monte-Carlo–sampled depolarizing noise was
+  silently `4/3×` too strong for a given `p`. The operators remain trace-preserving
+  (`Σ Kᵢ†Kᵢ = I`). Added channel-equivalence, trace-preservation, edge-case, and sampler
+  regression tests. (Present in 0.8.0 and 0.9.0; fixed here.)
+
 ## [0.9.0]
 
 Theme: quantum chemistry, many-body physics & advanced simulation. Fermionic systems

{quantum_debugger-0.9.0 → quantum_debugger-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantum-debugger
-Version: 0.9.0
+Version: 1.0.0
 Summary: A quantum simulation and debugging toolkit: state-vector, Clifford/stabilizer, and density-matrix (open-systems) engines, with a broad algorithm library, error correction under noise, quantum machine learning, GPU acceleration, and multi-framework support (Qiskit, PennyLane, Cirq, TensorFlow, PyTorch).
 Home-page: https://github.com/Raunakg2005/quantum-debugger
 Author: Raunak Kumar Gupta
@@ -84,7 +84,28 @@ Dynamic: summary
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-A powerful Python library for quantum circuit debugging, state inspection, performance analysis, and quantum machine learning. From basic circuits to QML with one-line AutoML.
+## What's New in v1.0.0
+
+Scale & tensor networks — **breaking the exponential state-vector wall**:
+
+- **Matrix Product State Simulator (`MPS`)** — `O(n·χ²)` memory instead of `2ⁿ`. Represents large, lightly-entangled quantum systems (e.g. **100-qubit GHZ states**, area-law ground states) with exact single-qubit gates, SVD-truncated two-qubit gates, and long-range connectivity via SWAP networks.
+- **Matrix Product Operators (`MPO`)** — compact tensor chains for TFIM (`tfim_mpo`) and Heisenberg (`heisenberg_mpo`) models; evaluate `<ψ|H|ψ>` in `O(n·χ²·D²)` time without dense matrices.
+- **TEBD Real-Time Dynamics** (`tebd_tfim`, `tebd_magnetization`) — Trotterized time evolution on the MPS engine with automatic SVD bond truncation.
+- **Imaginary-Time DMRG-Style Ground States** (`imaginary_tebd_ground_state`) — cool MPS into true ground states on 24+ qubit chains unreachable by dense diagonalizers.
+- **Arbitrary Pauli & Energy Readout** — `MPS.expectation_pauli` and `MPS.energy` evaluate arbitrary Pauli strings and Hamiltonians by tensor contraction.
+- **Born-Rule Measurement Sampling** (`MPS.sample`) — sequential conditional sampling with precomputed environments, drawing shots directly from the MPS.
+- **Circuit-to-MPS Converter** (`MPS.from_circuit`) — execute `QuantumCircuit` instances directly on the tensor-network engine.
+
+See the [Matrix Product States Guide](docs/mps_guide.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## What's New in v0.9.1
+
+Correctness patch: **`DepolarizingNoise.get_kraus_operators()`** now implements the same
+channel as `apply()` and the class docstring — the Pauli-error convention
+`ρ → (1−p)ρ + (p/3)(XρX + YρY + ZρZ)` (`K₀ = √(1−p)·I`, `K₁₋₃ = √(p/3)·{X, Y, Z}`). The old
+`√(p/4)` weighting made `StochasticNoiseSampler`'s Monte-Carlo depolarizing noise `4/3×` too
+strong for a given `p`. Trace preservation is unchanged; channel-equivalence and sampler
+regression tests added. See [CHANGELOG.md](CHANGELOG.md).
 
 ## What's New in v0.9.0
 
@@ -490,5 +511,5 @@ If you use quantum-debugger in your research, please cite:
 
 ---
 
-**Version:** 0.9.0 (latest on PyPI) · 0.8.0, 0.7.1 (previous)  
-**Last Updated:** August 2026
+**Version:** 1.0.0 (latest on PyPI) · 0.9.1, 0.9.0, 0.8.0 (previous)  
+**Last Updated:** September 2026

{quantum_debugger-0.9.0 → quantum_debugger-1.0.0}/README.md

@@ -9,7 +9,28 @@
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-A powerful Python library for quantum circuit debugging, state inspection, performance analysis, and quantum machine learning. From basic circuits to QML with one-line AutoML.
+## What's New in v1.0.0
+
+Scale & tensor networks — **breaking the exponential state-vector wall**:
+
+- **Matrix Product State Simulator (`MPS`)** — `O(n·χ²)` memory instead of `2ⁿ`. Represents large, lightly-entangled quantum systems (e.g. **100-qubit GHZ states**, area-law ground states) with exact single-qubit gates, SVD-truncated two-qubit gates, and long-range connectivity via SWAP networks.
+- **Matrix Product Operators (`MPO`)** — compact tensor chains for TFIM (`tfim_mpo`) and Heisenberg (`heisenberg_mpo`) models; evaluate `<ψ|H|ψ>` in `O(n·χ²·D²)` time without dense matrices.
+- **TEBD Real-Time Dynamics** (`tebd_tfim`, `tebd_magnetization`) — Trotterized time evolution on the MPS engine with automatic SVD bond truncation.
+- **Imaginary-Time DMRG-Style Ground States** (`imaginary_tebd_ground_state`) — cool MPS into true ground states on 24+ qubit chains unreachable by dense diagonalizers.
+- **Arbitrary Pauli & Energy Readout** — `MPS.expectation_pauli` and `MPS.energy` evaluate arbitrary Pauli strings and Hamiltonians by tensor contraction.
+- **Born-Rule Measurement Sampling** (`MPS.sample`) — sequential conditional sampling with precomputed environments, drawing shots directly from the MPS.
+- **Circuit-to-MPS Converter** (`MPS.from_circuit`) — execute `QuantumCircuit` instances directly on the tensor-network engine.
+
+See the [Matrix Product States Guide](docs/mps_guide.md) and [CHANGELOG.md](CHANGELOG.md).
+
+## What's New in v0.9.1
+
+Correctness patch: **`DepolarizingNoise.get_kraus_operators()`** now implements the same
+channel as `apply()` and the class docstring — the Pauli-error convention
+`ρ → (1−p)ρ + (p/3)(XρX + YρY + ZρZ)` (`K₀ = √(1−p)·I`, `K₁₋₃ = √(p/3)·{X, Y, Z}`). The old
+`√(p/4)` weighting made `StochasticNoiseSampler`'s Monte-Carlo depolarizing noise `4/3×` too
+strong for a given `p`. Trace preservation is unchanged; channel-equivalence and sampler
+regression tests added. See [CHANGELOG.md](CHANGELOG.md).
 
 ## What's New in v0.9.0
 
@@ -415,5 +436,5 @@ If you use quantum-debugger in your research, please cite:
 
 ---
 
-**Version:** 0.9.0 (latest on PyPI) · 0.8.0, 0.7.1 (previous)  
-**Last Updated:** August 2026
+**Version:** 1.0.0 (latest on PyPI) · 0.9.1, 0.9.0, 0.8.0 (previous)  
+**Last Updated:** September 2026

{quantum_debugger-0.9.0 → quantum_debugger-1.0.0}/quantum_debugger/__init__.py

@@ -13,7 +13,7 @@ Features:
 - Hardware profile support
 """
 
-__version__ = "0.9.0"
+__version__ = "1.0.0"
 __author__ = "Raunak Kumar Gupta"
 __license__ = "MIT"
 
@@ -58,6 +58,9 @@ from .mitigation import (
     adaptive_fold,
 )
 
+# Tensor Networks / Matrix Product States (v1.0.0)
+from .mps import MPS
+
 # Optional integrations
 try:
     from .integrations import QiskitAdapter
@@ -79,6 +82,8 @@ __all__ = [
     "CircuitMetrics",
     "StateVisualizer",
     "BlochSphere",
+    # Tensor Networks (v1.0.0)
+    "MPS",
     # Noise Models (v0.3.0)
     "DepolarizingNoise",
     "AmplitudeDamping",

{quantum_debugger-0.9.0 → quantum_debugger-1.0.0}/quantum_debugger/algorithms/__init__.py

@@ -208,6 +208,13 @@ from .schmidt import (
     truncation_fidelity,
     area_law_compressibility,
 )
+from .tebd import (
+    tfim_bond_gate,
+    tebd_tfim,
+    tebd_magnetization,
+    tfim_mps_energy,
+    imaginary_tebd_ground_state,
+)
 from .ssh_model import (
     ssh_hamiltonian,
     ssh_winding_number,
@@ -440,6 +447,11 @@ __all__ = [
     "schmidt_decomposition",
     "truncation_fidelity",
     "area_law_compressibility",
+    "tfim_bond_gate",
+    "tebd_tfim",
+    "tebd_magnetization",
+    "tfim_mps_energy",
+    "imaginary_tebd_ground_state",
     # SSH topological insulator
     "ssh_hamiltonian",
     "ssh_winding_number",

quantum_debugger-1.0.0/quantum_debugger/algorithms/tebd.py

@@ -0,0 +1,141 @@
+"""
+TEBD -- Time-Evolving Block Decimation (dynamics on a matrix product state)
+
+Real-time evolution of a many-body state under a nearest-neighbour Hamiltonian, done
+directly on a matrix product state. Trotterize ``e^{-i H t}`` into two-site gates
+``e^{-i h_{j,j+1} dt}``, apply them to the MPS (even bonds, then odd bonds), and let
+the built-in SVD truncation keep the bond dimension bounded. As long as the state
+stays lightly entangled, this simulates the dynamics of far more qubits than the dense
+state-vector engine can hold.
+
+This module provides TEBD for the transverse-field Ising model; the same pattern works
+for any nearest-neighbour Hamiltonian by supplying its two-site gates.
+"""
+
+import numpy as np
+from scipy.linalg import expm
+
+from ..mps import MPS
+
+_X = np.array([[0, 1], [1, 0]], dtype=complex)
+_Z = np.array([[1, 0], [0, -1]], dtype=complex)
+_I = np.eye(2, dtype=complex)
+
+
+def tfim_bond_gate(n: int, i: int, dt: float, j_coupling: float, field: float) -> np.ndarray:
+    """
+    Two-site Trotter gate ``exp(-i h_{i,i+1} dt)`` for the transverse-field Ising model
+    ``H = -J sum Z Z - h sum X`` on a chain of ``n`` sites. The single-site field is
+    split evenly between the bonds it belongs to (full weight at the two chain ends).
+    """
+    hx_i = field * (0.5 if i > 0 else 1.0)
+    hx_j = field * (0.5 if i < n - 2 else 1.0)
+    h_local = (
+        -j_coupling * np.kron(_Z, _Z)
+        - hx_i * np.kron(_I, _X)
+        - hx_j * np.kron(_X, _I)
+    )
+    return expm(-1j * h_local * dt)
+
+
+def tebd_tfim(n: int, time: float, steps: int = 100, j_coupling: float = 1.0,
+              field: float = 1.0, max_bond: int = 16, initial: "MPS" = None) -> "MPS":
+    """
+    Evolve a TFIM chain of ``n`` sites for total ``time`` with ``steps`` Trotter steps,
+    on an MPS truncated to ``max_bond``. Starts from ``|0...0>`` unless an ``initial``
+    MPS is supplied. Returns the evolved MPS.
+    """
+    mps = initial if initial is not None else MPS.zero_state(n, max_bond=max_bond)
+    mps.max_bond = max_bond
+    dt = time / steps
+    even = [tfim_bond_gate(n, i, dt, j_coupling, field) for i in range(0, n - 1, 2)]
+    odd = [tfim_bond_gate(n, i, dt, j_coupling, field) for i in range(1, n - 1, 2)]
+    for _ in range(steps):
+        for idx, i in enumerate(range(0, n - 1, 2)):
+            mps.apply_two(even[idx], i)
+        for idx, i in enumerate(range(1, n - 1, 2)):
+            mps.apply_two(odd[idx], i)
+    return mps
+
+
+def tfim_mps_energy(mps: "MPS", j_coupling: float = 1.0, field: float = 1.0) -> float:
+    """
+    Energy ``<H>`` of the transverse-field Ising Hamiltonian
+    ``H = -J sum Z Z - h sum X`` for an MPS, from its bond correlations and site
+    expectations (contraction, no dense state).
+    """
+    n = mps.n
+    energy = 0.0
+    for i in range(n - 1):
+        energy += -j_coupling * mps.correlation(_Z, i, _Z, i + 1)
+    for i in range(n):
+        energy += -field * mps.expectation(_X, i)
+    return float(energy)
+
+
+def _imag_bond_gate(n, i, dtau, j_coupling, field):
+    hx_i = field * (0.5 if i > 0 else 1.0)
+    hx_j = field * (0.5 if i < n - 2 else 1.0)
+    h_local = (
+        -j_coupling * np.kron(_Z, _Z)
+        - hx_i * np.kron(_I, _X)
+        - hx_j * np.kron(_X, _I)
+    )
+    return expm(-h_local * dtau)  # imaginary time -> real exponential (cooling)
+
+
+def imaginary_tebd_ground_state(n: int, j_coupling: float = 1.0, field: float = 1.0,
+                                dtau: float = 0.05, steps: int = 300,
+                                max_bond: int = 16) -> dict:
+    """
+    Find the TFIM ground state of an ``n``-site chain by imaginary-time TEBD -- apply
+    ``e^{-h_{j,j+1} dtau}`` bond gates (cooling), renormalizing each step, until the
+    state settles into the ground state. Scales to chains far beyond the dense
+    simulator.
+
+    Returns dict with ``energy`` (variational ground energy), ``bond`` (bond dimension
+    reached), and -- when ``n`` is small enough to diagonalize -- ``exact_energy`` and
+    ``error``.
+    """
+    from ..core.gates import GateLibrary
+
+    mps = MPS.zero_state(n, max_bond=max_bond)
+    for q in range(n):  # start from |+...+> for good ground-state overlap
+        mps.apply_single(GateLibrary.H, q)
+
+    for _ in range(steps):
+        for i in range(0, n - 1, 2):
+            mps.apply_two(_imag_bond_gate(n, i, dtau, j_coupling, field), i)
+        for i in range(1, n - 1, 2):
+            mps.apply_two(_imag_bond_gate(n, i, dtau, j_coupling, field), i)
+        norm = mps.norm()
+        mps.tensors[0] = mps.tensors[0] / norm
+
+    energy = tfim_mps_energy(mps, j_coupling, field)
+    result = {"energy": energy, "bond": mps.max_bond_dimension()}
+    if n <= 12:
+        from .hamiltonian_simulation import hamiltonian_matrix
+        from .vqe_solver import tfim_hamiltonian
+
+        H = hamiltonian_matrix(tfim_hamiltonian(n, field, j_coupling), n)
+        exact = float(np.linalg.eigvalsh(H).real.min())
+        result["exact_energy"] = exact
+        result["error"] = abs(energy - exact)
+    return result
+
+
+def tebd_magnetization(n: int, time: float, steps: int = 100, j_coupling: float = 1.0,
+                       field: float = 1.0, max_bond: int = 16) -> dict:
+    """
+    Quench a TFIM chain from the all-up state and read out the transverse magnetization.
+
+    Returns dict with ``z_profile`` (``<Z_i>`` on each site), ``mean_z``, and
+    ``max_bond`` (the bond dimension reached -- the cost of the entanglement generated).
+    """
+    mps = tebd_tfim(n, time, steps, j_coupling, field, max_bond)
+    z_profile = [mps.expectation(_Z, q) for q in range(n)]
+    return {
+        "z_profile": z_profile,
+        "mean_z": float(np.mean(z_profile)),
+        "max_bond": mps.max_bond_dimension(),
+    }

quantum_debugger-1.0.0/quantum_debugger/mpo.py

@@ -0,0 +1,97 @@
+"""
+Matrix Product Operators (MPO)
+
+The operator analogue of a matrix product state: a many-body operator ``H`` written as
+a chain of rank-4 tensors ``W[i]`` of shape ``(D_left, 2, 2, D_right)`` (bond, physical
+out, physical in, bond). Local Hamiltonians have a *small* MPO bond dimension -- the
+transverse-field Ising model needs only 3 -- so ``<psi|H|psi>`` on a matrix product
+state costs ``O(n * chi^2 * D^2)`` with no dense operator ever formed. MPOs are the
+operator input to DMRG and MPS-based time evolution.
+"""
+
+import numpy as np
+
+_I = np.eye(2, dtype=complex)
+_Z = np.array([[1, 0], [0, -1]], dtype=complex)
+_X = np.array([[0, 1], [1, 0]], dtype=complex)
+
+
+def tfim_mpo(n: int, j_coupling: float = 1.0, field: float = 1.0) -> list:
+    """
+    Bond-dimension-3 MPO for the transverse-field Ising Hamiltonian
+    ``H = -J sum Z Z - h sum X`` on ``n`` sites. Returns the list of ``W`` tensors.
+    """
+    W = np.zeros((3, 2, 2, 3), dtype=complex)
+    W[0, :, :, 0] = _I
+    W[1, :, :, 0] = _Z
+    W[2, :, :, 0] = -field * _X
+    W[2, :, :, 1] = -j_coupling * _Z
+    W[2, :, :, 2] = _I
+    tensors = []
+    for i in range(n):
+        if i == 0:
+            tensors.append(W[2:3, :, :, :])   # left boundary row
+        elif i == n - 1:
+            tensors.append(W[:, :, :, 0:1])   # right boundary column
+        else:
+            tensors.append(W)
+    return tensors
+
+
+def heisenberg_mpo(n: int, j_coupling: float = 1.0) -> list:
+    """
+    Bond-dimension-5 MPO for the Heisenberg Hamiltonian
+    ``H = J sum (X X + Y Y + Z Z)`` on ``n`` sites.
+    """
+    Y = np.array([[0, -1j], [1j, 0]], dtype=complex)
+    W = np.zeros((5, 2, 2, 5), dtype=complex)
+    W[0, :, :, 0] = _I
+    W[4, :, :, 4] = _I
+    W[1, :, :, 0] = _X
+    W[2, :, :, 0] = Y
+    W[3, :, :, 0] = _Z
+    W[4, :, :, 1] = j_coupling * _X
+    W[4, :, :, 2] = j_coupling * Y
+    W[4, :, :, 3] = j_coupling * _Z
+    tensors = []
+    for i in range(n):
+        if i == 0:
+            tensors.append(W[4:5, :, :, :])
+        elif i == n - 1:
+            tensors.append(W[:, :, :, 0:1])
+        else:
+            tensors.append(W)
+    return tensors
+
+
+def mpo_expectation(mps, mpo) -> float:
+    """
+    Expectation ``<psi|H|psi>`` of an MPO ``mpo`` for a matrix product state ``mps``, by
+    sweeping the three-layer (bra, operator, ket) contraction -- no dense operator.
+    """
+    E = np.ones((1, 1, 1), dtype=complex)  # (bra bond, mpo bond, ket bond)
+    for A, W in zip(mps.tensors, mpo):
+        E = np.einsum("lmn,nSr->lmSr", E, A)        # absorb ket tensor
+        E = np.einsum("lmSr,mSTw->lTrw", E, W)      # apply operator tensor
+        E = np.einsum("lTrw,lTb->wrb", E, np.conj(A))  # absorb bra tensor
+        E = E.transpose(2, 0, 1)
+    return float(np.real(E[0, 0, 0]))
+
+
+def mpo_to_matrix(mpo) -> np.ndarray:
+    """Contract an MPO into its dense ``2^n x 2^n`` operator (small ``n``, for checking)."""
+    n = len(mpo)
+    T = mpo[0]
+    for W in mpo[1:]:
+        T = np.tensordot(T, W, axes=(T.ndim - 1, 0))
+    # T axes: bond_l, (out,in) per site, bond_r -> reshape
+    T = T[0, ..., 0]  # drop trivial boundary bonds
+    outs = list(range(0, 2 * n, 2))
+    ins = list(range(1, 2 * n, 2))
+    T = T.transpose(outs + ins)
+    dim = 2**n
+    M = T.reshape(dim, dim)
+    # little-endian reordering to match the rest of the library
+    perm = list(range(n - 1, -1, -1))
+    Mt = M.reshape([2] * (2 * n)).transpose(perm + [n + p for p in perm]).reshape(dim, dim)
+    return Mt