mps-xtrap 1.0.0__py3-none-any.whl

mps_xtrap/__init__.py

@@ -0,0 +1,44 @@
+"""
+mps_xtrap — MPS-based quantum circuit simulator with Richardson extrapolation.
+
+Quick start
+-----------
+>>> from mps_xtrap import Circuit, MPSSimulator, MultiChiRunner, SweepConfig
+>>>
+>>> # Simple simulation at a fixed bond dimension
+>>> c = Circuit(4)
+>>> c.h(0).cx(0,1).cx(1,2).cx(2,3)
+>>> sim = MPSSimulator(chi=64)
+>>> state = sim.run(c)
+>>> print(state.expectation_pauli_z(0))
+>>>
+>>> # Extrapolated simulation — just set base_chi, scaling_factor, n_levels
+>>> # Bond dimensions are auto-generated: [16, 32, 64]
+>>> runner = MultiChiRunner(SweepConfig(base_chi=16, scaling_factor=2, n_levels=3))
+>>> result = runner.run(c, {'Z0': ('Z', 0), 'Z1': ('Z', 1)})
+>>> print(result.summary())
+"""
+
+from .core.mps import MPS
+from .circuits import Circuit, MPSSimulator
+from .extrapolation import (
+    MultiChiRunner,
+    SweepConfig,
+    ExtrapolationResult,
+    MultiObservableResult,
+)
+from .gates import get_gate
+
+__version__ = "1.0.0"
+__author__ = "MPS Sim"
+
+__all__ = [
+    "MPS",
+    "Circuit",
+    "MPSSimulator",
+    "MultiChiRunner",
+    "SweepConfig",
+    "ExtrapolationResult",
+    "MultiObservableResult",
+    "get_gate",
+]

mps_xtrap/circuits/__init__.py

@@ -0,0 +1,336 @@
+"""
+Quantum circuit representation and gate application on MPS.
+
+A Circuit is an ordered list of gate instructions. The Simulator
+applies these instructions to an MPS, performing SVD truncations
+at two-qubit gates.
+"""
+
+from __future__ import annotations
+import numpy as np
+from numpy.typing import NDArray
+from dataclasses import dataclass, field
+from typing import List, Tuple, Optional, Union, Dict, Any
+import logging
+
+from ..core.mps import MPS
+from ..gates import get_gate, SINGLE_QUBIT_GATES, TWO_QUBIT_GATES
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Gate instruction
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GateInstruction:
+    """
+    A single gate application.
+
+    Attributes
+    ----------
+    name : str
+        Gate name (e.g., 'H', 'CNOT', 'Rx').
+    qubits : list of int
+        Target qubits. Length 1 for single-qubit gates, 2 for two-qubit.
+    params : list of float
+        Gate parameters (e.g., rotation angles).
+    matrix : ndarray or None
+        Explicit gate matrix (overrides name lookup if provided).
+    label : str
+        Human-readable label for circuit diagrams.
+    """
+    name: str
+    qubits: List[int]
+    params: List[float] = field(default_factory=list)
+    matrix: Optional[NDArray] = None
+    label: str = ""
+
+    def __post_init__(self):
+        if not self.label:
+            self.label = self.name
+        if not isinstance(self.qubits, list):
+            self.qubits = list(self.qubits)
+
+    def get_matrix(self) -> NDArray:
+        if self.matrix is not None:
+            return self.matrix
+        return get_gate(self.name, *self.params)
+
+    def __repr__(self) -> str:
+        q = ",".join(map(str, self.qubits))
+        p = f"({','.join(f'{x:.4f}' for x in self.params)})" if self.params else ""
+        return f"{self.name}{p}[{q}]"
+
+
+# ---------------------------------------------------------------------------
+# Circuit
+# ---------------------------------------------------------------------------
+
+class Circuit:
+    """
+    A quantum circuit as an ordered list of gate instructions.
+
+    Supports a fluent builder API:
+        c = Circuit(4)
+        c.h(0).cx(0,1).rz(np.pi/4, 2).measure_all()
+    """
+
+    def __init__(self, n_qubits: int):
+        self.n = n_qubits
+        self.instructions: List[GateInstruction] = []
+
+    # ------------------------------------------------------------------
+    # Builder API
+    # ------------------------------------------------------------------
+
+    def _add(self, name: str, qubits, params=None, matrix=None) -> 'Circuit':
+        if isinstance(qubits, int):
+            qubits = [qubits]
+        inst = GateInstruction(
+            name=name,
+            qubits=list(qubits),
+            params=list(params) if params else [],
+            matrix=matrix,
+        )
+        self.instructions.append(inst)
+        return self
+
+    # Single-qubit gates
+    def i(self, q): return self._add('I', [q])
+    def x(self, q): return self._add('X', [q])
+    def y(self, q): return self._add('Y', [q])
+    def z(self, q): return self._add('Z', [q])
+    def h(self, q): return self._add('H', [q])
+    def s(self, q): return self._add('S', [q])
+    def t(self, q): return self._add('T', [q])
+    def sdg(self, q): return self._add('Sdg', [q])
+    def tdg(self, q): return self._add('Tdg', [q])
+
+    def rx(self, theta: float, q: int): return self._add('Rx', [q], [theta])
+    def ry(self, theta: float, q: int): return self._add('Ry', [q], [theta])
+    def rz(self, theta: float, q: int): return self._add('Rz', [q], [theta])
+    def p(self, phi: float, q: int): return self._add('P', [q], [phi])
+    def u(self, theta, phi, lam, q): return self._add('U', [q], [theta, phi, lam])
+
+    # Two-qubit gates
+    def cx(self, ctrl, tgt): return self._add('CNOT', [ctrl, tgt])
+    def cnot(self, ctrl, tgt): return self._add('CNOT', [ctrl, tgt])
+    def cz(self, q1, q2): return self._add('CZ', [q1, q2])
+    def swap(self, q1, q2): return self._add('SWAP', [q1, q2])
+    def iswap(self, q1, q2): return self._add('iSWAP', [q1, q2])
+    def xx(self, theta, q1, q2): return self._add('XX', [q1, q2], [theta])
+    def yy(self, theta, q1, q2): return self._add('YY', [q1, q2], [theta])
+    def zz(self, theta, q1, q2): return self._add('ZZ', [q1, q2], [theta])
+    def crz(self, theta, ctrl, tgt): return self._add('CRz', [ctrl, tgt], [theta])
+    def cp(self, phi, ctrl, tgt): return self._add('CP', [ctrl, tgt], [phi])
+
+    # Custom matrix
+    def unitary(self, matrix: NDArray, qubits): return self._add('U_custom', qubits, matrix=matrix)
+
+    # ------------------------------------------------------------------
+    # Helpers for common circuit patterns
+    # ------------------------------------------------------------------
+
+    def barrier(self, *qubits):
+        """Barrier is a no-op for simulation but marks a layer boundary."""
+        return self  # no-op
+
+    def __len__(self):
+        return len(self.instructions)
+
+    def depth(self) -> int:
+        """Estimate circuit depth (number of non-overlapping gate layers)."""
+        last_use = [-1] * self.n
+        max_layer = -1
+        for inst in self.instructions:
+            d = max(last_use[q] for q in inst.qubits) + 1
+            max_layer = max(max_layer, d)
+            for q in inst.qubits:
+                last_use[q] = d
+        return max_layer + 1  # convert 0-indexed layer to count
+
+    def two_qubit_count(self) -> int:
+        return sum(1 for inst in self.instructions if len(inst.qubits) == 2)
+
+    def __repr__(self) -> str:
+        return (f"Circuit(n={self.n}, gates={len(self.instructions)}, "
+                f"depth≈{self.depth()}, 2q={self.two_qubit_count()})")
+
+    def draw(self) -> str:
+        """Simple text-based circuit diagram."""
+        lines = [f"q{i}: " for i in range(self.n)]
+        for inst in self.instructions:
+            label = str(inst)
+            for i, q in enumerate(inst.qubits):
+                lines[q] += f"──{label}──"
+            # Pad other qubits
+            max_len = max(len(l) for l in lines)
+            lines = [l + '─' * (max_len - len(l)) for l in lines]
+        return '\n'.join(lines)
+
+
+# ---------------------------------------------------------------------------
+# MPS Simulator
+# ---------------------------------------------------------------------------
+
+class MPSSimulator:
+    """
+    Applies a Circuit to an MPS state.
+
+    Two-qubit gates on non-adjacent qubits are handled by first
+    swapping qubits into adjacent positions, applying the gate,
+    then swapping back.
+    """
+
+    def __init__(self, chi: int, svd_threshold: float = 1e-14):
+        """
+        Parameters
+        ----------
+        chi : int
+            Maximum bond dimension for SVD truncation.
+        svd_threshold : float
+            Singular values below this are discarded before bond-dim cap.
+        """
+        self.chi = chi
+        self.svd_threshold = svd_threshold
+
+    def run(self, circuit: Circuit) -> MPS:
+        """
+        Simulate circuit from |0...0> and return final MPS state.
+
+        Returns
+        -------
+        MPS
+            Final state after all gates applied.
+        """
+        state = MPS(circuit.n, self.chi)
+        self._apply_circuit(circuit, state)
+        return state
+
+    def run_from(self, circuit: Circuit, state: MPS) -> MPS:
+        """Apply circuit to an existing MPS state (modifies a copy)."""
+        new_state = state.copy()
+        new_state.chi = self.chi
+        self._apply_circuit(circuit, new_state)
+        return new_state
+
+    def _apply_circuit(self, circuit: Circuit, state: MPS):
+        for inst in circuit.instructions:
+            if len(inst.qubits) == 1:
+                self._apply_single(inst, state)
+            elif len(inst.qubits) == 2:
+                self._apply_two(inst, state)
+            else:
+                raise ValueError(f"Gates on >2 qubits not yet supported: {inst}")
+
+    def _apply_single(self, inst: GateInstruction, state: MPS):
+        """Apply single-qubit gate via matrix multiplication on physical index."""
+        q = inst.qubits[0]
+        gate = inst.get_matrix()  # (2,2)
+        t = state.get_tensor(q)   # (chi_l, 2, chi_r)
+        # Contract: new[l,s',r] = sum_s gate[s',s] * t[l,s,r]
+        new_t = np.einsum('sp,lpr->lsr', gate, t)
+        state.set_tensor(q, new_t)
+        state.center = None  # Canonicality violated
+
+    def _apply_two(self, inst: GateInstruction, state: MPS):
+        """Apply two-qubit gate with SVD truncation."""
+        q1, q2 = inst.qubits
+
+        # Handle non-adjacent qubits via SWAP chain
+        if abs(q1 - q2) != 1:
+            self._apply_two_nonlocal(inst, state)
+            return
+
+        # Ensure q1 < q2
+        if q1 > q2:
+            q1, q2 = q2, q1
+            gate = inst.get_matrix()  # (2,2,2,2): op[s1',s2',s1,s2]
+            # Swap qubit ordering
+            gate = gate.transpose(1, 0, 3, 2)
+        else:
+            gate = inst.get_matrix()
+
+        # Build theta: two-site tensor
+        A = state.get_tensor(q1)  # (chi_l, 2, chi_m)
+        B = state.get_tensor(q2)  # (chi_m, 2, chi_r)
+        theta = np.einsum('lir,rjs->lijs', A, B)  # (chi_l, 2, 2, chi_r)
+
+        # Apply gate: theta'[l,s1',s2',r] = sum_{s1,s2} gate[s1',s2',s1,s2] * theta[l,s1,s2,r]
+        theta = np.einsum('abij,lijs->labs', gate, theta)
+
+        # SVD truncation
+        state.apply_svd_truncation(q1, theta, chi=self.chi,
+                                    svd_threshold=self.svd_threshold)
+        state.center = None
+
+    def _apply_two_nonlocal(self, inst: GateInstruction, state: MPS):
+        """
+        Apply a gate on non-adjacent qubits via SWAP chain.
+        Brings qubits adjacent, applies gate, swaps back.
+        """
+        from ..gates import SWAP as make_swap
+        q1, q2 = inst.qubits
+        if q1 > q2:
+            q1, q2 = q2, q1
+
+        # Bubble q2 adjacent to q1
+        swap_gate = make_swap()
+        swap_inst = GateInstruction('SWAP', [0, 1], matrix=swap_gate)
+
+        for pos in range(q2, q1 + 1, -1):
+            swap_inst.qubits = [pos - 1, pos]
+            swap_inst.matrix = swap_gate
+            self._apply_two(swap_inst, state)
+
+        # Now apply actual gate at (q1, q1+1)
+        modified_inst = GateInstruction(
+            inst.name, [q1, q1 + 1],
+            inst.params, inst.matrix, inst.label
+        )
+        self._apply_two(modified_inst, state)
+
+        # Swap back
+        for pos in range(q1 + 1, q2):
+            swap_inst.qubits = [pos, pos + 1]
+            self._apply_two(swap_inst, state)
+
+    def expectation_value(
+        self,
+        state: MPS,
+        observable: str,
+        site: int,
+        site2: Optional[int] = None,
+    ) -> float:
+        """
+        Convenience wrapper to compute expectation values.
+
+        Parameters
+        ----------
+        state : MPS
+        observable : str
+            'X', 'Y', 'Z', 'ZZ', 'XX', etc.
+        site : int
+            Primary site.
+        site2 : int, optional
+            Second site for two-qubit observables.
+        """
+        if observable == 'Z':
+            return state.expectation_pauli_z(site)
+        elif observable == 'X':
+            return state.expectation_pauli_x(site)
+        elif observable == 'Y':
+            return state.expectation_pauli_y(site)
+        elif observable in ('ZZ', 'XX', 'YY') and site2 is not None:
+            from ..gates import Z, X, Y
+            ops = {'ZZ': Z, 'XX': X, 'YY': Y}
+            op1 = ops[observable]()
+            op = np.einsum('ij,kl->ikjl', op1, op1)
+            if abs(site - site2) == 1:
+                return float(np.real(state.expectation_two(op, min(site, site2))))
+            else:
+                raise NotImplementedError("Non-adjacent two-site observables not implemented")
+        else:
+            raise ValueError(f"Unknown observable: {observable}")

mps_xtrap/cli.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""
+mps_xtrap CLI — MPS quantum circuit simulator with Richardson extrapolation.
+
+Usage
+-----
+  python cli.py simulate --circuit bell --chi 64
+  python cli.py extrapolate --circuit ising --chi-base 16 --levels 3
+  python cli.py benchmark --circuit ghz --n 10
+  python cli.py info
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import argparse
+import numpy as np
+import time
+from mps_xtrap import Circuit, MPSSimulator, MultiChiRunner, SweepConfig
+from mps_xtrap import RichardsonExtrapolator
+
+
+# ---------------------------------------------------------------------------
+# Built-in circuit library
+# ---------------------------------------------------------------------------
+
+def make_bell(n=2) -> Circuit:
+    c = Circuit(max(2, n))
+    c.h(0).cx(0, 1)
+    return c
+
+def make_ghz(n=6) -> Circuit:
+    c = Circuit(n)
+    c.h(0)
+    for i in range(n - 1):
+        c.cx(i, i + 1)
+    return c
+
+def make_ising(n=8, steps=5, J=1.0, h=0.5, dt=0.05) -> Circuit:
+    c = Circuit(n)
+    for _ in range(steps):
+        for q in range(n):
+            c.rx(2 * h * dt, q)
+        for q in range(n - 1):
+            c.zz(2 * J * dt, q, q + 1)
+    return c
+
+def make_qft(n=6) -> Circuit:
+    """Quantum Fourier Transform."""
+    c = Circuit(n)
+    for i in range(n):
+        c.h(i)
+        for j in range(i + 1, n):
+            c.cp(np.pi / 2 ** (j - i), i, j)
+    # Bit reversal swaps
+    for i in range(n // 2):
+        c.swap(i, n - 1 - i)
+    return c
+
+def make_random(n=8, depth=10, seed=42) -> Circuit:
+    np.random.seed(seed)
+    c = Circuit(n)
+    for _ in range(depth):
+        for q in range(n):
+            c.ry(np.random.uniform(0, np.pi), q)
+        for q in range(n - 1):
+            if np.random.random() < 0.5:
+                c.cx(q, q + 1)
+    return c
+
+CIRCUITS = {
+    'bell': make_bell,
+    'ghz': make_ghz,
+    'ising': make_ising,
+    'qft': make_qft,
+    'random': make_random,
+}
+
+
+# ---------------------------------------------------------------------------
+# CLI commands
+# ---------------------------------------------------------------------------
+
+def cmd_simulate(args):
+    print(f"\n── Simulation ──────────────────────────────────────────")
+    circuit_fn = CIRCUITS.get(args.circuit)
+    if circuit_fn is None:
+        print(f"Unknown circuit '{args.circuit}'. Available: {list(CIRCUITS)}")
+        return
+
+    c = circuit_fn(n=args.n)
+    print(f"Circuit: {c}")
+    print(f"Bond dim: χ={args.chi}")
+
+    t0 = time.time()
+    sim = MPSSimulator(chi=args.chi)
+    state = sim.run(c)
+    elapsed = time.time() - t0
+
+    print(f"\nResults (time: {elapsed:.2f}s):")
+    for q in range(min(c.n, 10)):
+        z = state.expectation_pauli_z(q)
+        x = state.expectation_pauli_x(q)
+        print(f"  q{q}: <Z>={z:+.6f}  <X>={x:+.6f}")
+
+    print(f"\nBond dims: {state.bond_dimensions()}")
+    print(f"Max bond dim reached: {state.max_bond_dim()} / {args.chi}")
+    print(f"Total truncation error: {state.total_truncation_error():.2e}")
+    print(f"State: {state}")
+
+
+def cmd_extrapolate(args):
+    print(f"\n── Richardson Extrapolation ────────────────────────────")
+    circuit_fn = CIRCUITS.get(args.circuit)
+    if circuit_fn is None:
+        print(f"Unknown circuit '{args.circuit}'. Available: {list(CIRCUITS)}")
+        return
+
+    c = circuit_fn(n=args.n)
+    print(f"Circuit: {c}")
+
+    cfg = SweepConfig(
+        base_chi=args.chi_base,
+        ratio=args.ratio,
+        n_levels=args.levels,
+    )
+    print(f"Bond dims: {cfg.bond_dims}")
+    print(f"Effective equivalent χ: {cfg.effective_chi()}")
+    print()
+
+    observables = {f'Z{q}': ('Z', q) for q in range(min(c.n, args.obs_qubits))}
+    runner = MultiChiRunner(cfg, verbose=True)
+
+    t0 = time.time()
+    result = runner.run(c, observables)
+    elapsed = time.time() - t0
+
+    print(f"\n{result.summary()}")
+    print(f"Total runtime: {elapsed:.2f}s")
+
+
+def cmd_benchmark(args):
+    print(f"\n── Benchmark ───────────────────────────────────────────")
+    circuit_fn = CIRCUITS.get(args.circuit)
+    if circuit_fn is None:
+        print(f"Unknown circuit '{args.circuit}'. Available: {list(CIRCUITS)}")
+        return
+
+    c = circuit_fn(n=args.n)
+    print(f"Circuit: {c}")
+    print(f"{'χ':>6}  {'Time(s)':>10}  {'<Z0>':>12}  {'TruncErr':>12}  {'MaxBond':>8}")
+    print("-" * 60)
+
+    chi_list = [args.chi_start * (2 ** i) for i in range(args.chi_levels)]
+    results = []
+
+    for chi in chi_list:
+        t0 = time.time()
+        sim = MPSSimulator(chi=chi)
+        state = sim.run(c)
+        elapsed = time.time() - t0
+        z0 = state.expectation_pauli_z(0)
+        trunc = state.total_truncation_error()
+        maxb = state.max_bond_dim()
+        results.append((chi, elapsed, z0, trunc, maxb))
+        print(f"{chi:>6}  {elapsed:>10.3f}  {z0:>+12.8f}  {trunc:>12.2e}  {maxb:>8}")
+
+    if len(results) >= 2:
+        print("\nRichardson extrapolation from all points:")
+        chi_vals = [r[0] for r in results]
+        z0_vals = [r[2] for r in results]
+        ext = RichardsonExtrapolator()
+        res = ext.extrapolate(chi_vals, z0_vals)
+        print(f"  Extrapolated <Z0> = {res.extrapolated:.8f} ± {res.uncertainty:.2e}")
+        print(f"  Alpha (error exponent) = {res.alpha:.3f}")
+        print(f"  Reliable: {res.is_reliable}")
+
+
+def cmd_info(args):
+    print("""
+mps_xtrap — MPS Quantum Circuit Simulator with Richardson Extrapolation
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ABOUT
+  Simulates quantum circuits using Matrix Product States (MPS).
+  Unique feature: multilevel Richardson extrapolation to estimate
+  expectation values at arbitrarily high bond dimensions from
+  simulations at a geometric sequence of modest bond dimensions.
+
+GATES SUPPORTED
+  Single-qubit: I, X, Y, Z, H, S, T, Sdg, Tdg, Rx, Ry, Rz, P, U
+  Two-qubit:    CNOT/CX, CZ, SWAP, iSWAP, XX, YY, ZZ, CRz, CP
+
+BUILT-IN CIRCUITS
+  bell    — 2-qubit Bell state
+  ghz     — N-qubit GHZ state
+  ising   — Transverse-field Ising Trotterized evolution
+  qft     — Quantum Fourier Transform
+  random  — Random brick-layer circuit
+
+EXTRAPOLATION THEORY
+  Truncation error scales as: ε(χ) ≈ a₁/χ^α + a₂/χ^2α + ...
+  Richardson extrapolation cancels successive error orders using
+  simulations at χ, 2χ, 4χ, ..., analogous to Romberg integration.
+  Reliability diagnostics flag when the power-law assumption breaks down.
+
+EXAMPLES
+  python cli.py simulate  --circuit ghz   --n 10 --chi 64
+  python cli.py extrapolate --circuit ising --n 8 --chi-base 16 --levels 3
+  python cli.py benchmark --circuit ising --n 8 --chi-start 8 --chi-levels 4
+""")
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='mps_xtrap — MPS Quantum Simulator with Richardson Extrapolation'
+    )
+    sub = parser.add_subparsers(dest='command')
+
+    # simulate
+    p_sim = sub.add_parser('simulate', help='Run a single simulation')
+    p_sim.add_argument('--circuit', default='ghz', choices=list(CIRCUITS))
+    p_sim.add_argument('--n', type=int, default=8, help='Number of qubits')
+    p_sim.add_argument('--chi', type=int, default=64, help='Bond dimension')
+
+    # extrapolate
+    p_ext = sub.add_parser('extrapolate', help='Run multi-chi sweep with extrapolation')
+    p_ext.add_argument('--circuit', default='ising', choices=list(CIRCUITS))
+    p_ext.add_argument('--n', type=int, default=8)
+    p_ext.add_argument('--chi-base', type=int, default=16)
+    p_ext.add_argument('--ratio', type=float, default=2.0)
+    p_ext.add_argument('--levels', type=int, default=3)
+    p_ext.add_argument('--obs-qubits', type=int, default=4, help='Number of qubits to measure')
+
+    # benchmark
+    p_bench = sub.add_parser('benchmark', help='Benchmark across chi values')
+    p_bench.add_argument('--circuit', default='ising', choices=list(CIRCUITS))
+    p_bench.add_argument('--n', type=int, default=8)
+    p_bench.add_argument('--chi-start', type=int, default=8)
+    p_bench.add_argument('--chi-levels', type=int, default=4)
+
+    # info
+    sub.add_parser('info', help='Show package info and supported gates')
+
+    args = parser.parse_args()
+
+    if args.command == 'simulate':
+        cmd_simulate(args)
+    elif args.command == 'extrapolate':
+        cmd_extrapolate(args)
+    elif args.command == 'benchmark':
+        cmd_benchmark(args)
+    elif args.command == 'info':
+        cmd_info(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == '__main__':
+    main()

mps_xtrap/core/__init__.py

@@ -0,0 +1 @@
+from .mps import MPS