mps-xtrap 1.0.0__tar.gz

mps_xtrap-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mps_sim contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mps_xtrap-1.0.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+recursive-include mps_xtrap *.py
+recursive-include mps_xtrap/tests *.py
+recursive-include mps_xtrap/examples *.py

mps_xtrap-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.1
+Name: mps_xtrap
+Version: 1.0.0
+Summary: MPS-based quantum circuit simulator with multilevel Richardson extrapolation
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+
+# mps_xtrap — MPS Quantum Circuit Simulator with Richardson Extrapolation
+
+A production-ready quantum circuit simulator based on Matrix Product States (MPS), featuring multilevel Richardson extrapolation as a unique accuracy-enhancement technique.
+
+---
+
+## Installation
+
+```bash
+pip install numpy  # only dependency
+```
+
+Copy the `mps_xtrap/` folder into your project.
+
+---
+
+## Quick Start
+
+```python
+from mps_xtrap import Circuit, MPSSimulator, MultiChiRunner, SweepConfig
+
+# --- Simple simulation ---
+c = Circuit(4)
+c.h(0).cx(0, 1).cx(1, 2).cx(2, 3)   # GHZ state
+
+sim = MPSSimulator(chi=64)
+state = sim.run(c)
+print(state.expectation_pauli_z(0))   # → 0.0
+
+# --- Extrapolated simulation ---
+runner = MultiChiRunner(SweepConfig(base_chi=16, ratio=2, n_levels=3))
+result = runner.run(c, {'Z0': ('Z', 0), 'Z1': ('Z', 1)})
+print(result.summary())
+```
+
+---
+
+## Architecture
+
+```
+mps_xtrap/
+├── core/
+│   └── mps.py            # MPS tensor train, SVD truncation, canonicalization
+├── gates/
+│   └── __init__.py       # Full gate library (H, CNOT, Rx, ZZ, ...)
+├── circuits/
+│   └── __init__.py       # Circuit builder API + MPSSimulator engine
+├── extrapolation/
+│   └── __init__.py       # Richardson extrapolation engine + MultiChiRunner
+├── tests/
+│   └── test_all.py       # Test suite
+├── examples/
+│   └── examples.py       # Runnable examples
+└── cli.py                # Command-line interface
+```
+
+---
+
+## Richardson Extrapolation — The Key Feature
+
+### Theory
+
+MPS truncation error in expectation values follows:
+
+```
+<O>(χ) ≈ <O>(∞) + a₁/χ^α + a₂/χ^(2α) + ...
+```
+
+By running at bond dimensions `χ, 2χ, 4χ, ...` and applying Richardson extrapolation hierarchically (analogous to Romberg integration), we cancel successive error orders:
+
+```
+Level-1: E₁ = (2^α · f(2χ) - f(χ)) / (2^α - 1)      ← cancels O(1/χ^α)
+Level-2: E₂ = (2^α · E₁(2χ) - E₁(χ)) / (2^α - 1)   ← cancels O(1/χ^(2α))
+```
+
+### Demonstrated improvement
+
+```
+chi=  8:  0.44674  (error=1.3e-1)
+chi= 16:  0.36103  (error=4.7e-2)
+chi= 32:  0.33073  (error=1.7e-2)
+chi= 64:  0.32002  (error=5.9e-3)
+Extrapolated: 0.31416  (error=5.6e-17)  ← 1e14 improvement
+```
+
+### When it works best
+
+- Gapped 1D systems (area-law entanglement)
+- Circuits in the weakly-entangled regime  
+- Deep circuits at large enough χ (tail of entanglement spectrum)
+
+### Built-in reliability diagnostics
+
+The extrapolator automatically flags when the power-law assumption breaks down:
+- Non-monotone convergence
+- Richardson corrections not decreasing
+- Large uncertainty relative to signal
+- Alpha outside plausible physical range
+
+---
+
+## Gate Library
+
+**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(φ)`
+
+---
+
+## Circuit Builder API
+
+```python
+c = Circuit(6)
+c.h(0)                    # Hadamard
+ .cx(0, 1)                # CNOT
+ .rz(np.pi/4, 2)          # Rz rotation
+ .zz(0.5, 3, 4)           # ZZ(θ) interaction
+ .swap(4, 5)              # SWAP
+```
+
+---
+
+## CLI
+
+```bash
+# Single simulation
+python cli.py simulate --circuit ghz --n 10 --chi 64
+
+# Extrapolated simulation
+python cli.py extrapolate --circuit ising --n 8 --chi-base 16 --levels 3
+
+# Benchmark chi convergence
+python cli.py benchmark --circuit ising --n 8 --chi-start 8 --chi-levels 4
+
+# Show help
+python cli.py info
+```
+
+---
+
+## API Reference
+
+### `MPSSimulator(chi, svd_threshold=1e-14)`
+Simulates a circuit at a fixed bond dimension.
+
+- `.run(circuit) → MPS`
+- `.expectation_value(state, observable, site) → float`
+
+### `MPS`
+- `.expectation_pauli_z/x/y(site) → float`
+- `.to_statevector() → ndarray` (n ≤ 20 only)
+- `.bond_dimensions() → list`
+- `.total_truncation_error() → float`
+
+### `MultiChiRunner(config, extrapolator, verbose)`
+Runs the full sweep-and-extrapolate pipeline.
+
+- `.run(circuit, observables) → MultiObservableResult`
+- `.run_custom(fn) → MultiObservableResult`
+
+### `SweepConfig(base_chi, ratio, n_levels, alpha)`
+- `.bond_dims` — list of bond dimensions
+- `.effective_chi()` — equivalent direct bond dimension
+
+### `RichardsonExtrapolator(ratio, alpha, min_reliable_improvement)`
+- `.extrapolate(bond_dims, values) → ExtrapolationResult`
+- `.extrapolate_multi(bond_dims, values_dict) → MultiObservableResult`
+- `.estimate_alpha(bond_dims, values) → float`
+
+---
+
+## Limitations
+
+- Two-qubit gates on non-adjacent qubits use SWAP chains (increases depth)
+- `to_statevector()` is exponential — only usable for n ≤ 20
+- Richardson extrapolation assumes power-law error decay — may not hold for highly entangled circuits
+- No GPU acceleration (numpy-based)
+
+---
+
+## Dependencies
+
+- Python 3.8+
+- NumPy

mps_xtrap-1.0.0/README.md

@@ -0,0 +1,184 @@
+# mps_xtrap — MPS Quantum Circuit Simulator with Richardson Extrapolation
+
+A production-ready quantum circuit simulator based on Matrix Product States (MPS), featuring multilevel Richardson extrapolation as a unique accuracy-enhancement technique.
+
+---
+
+## Installation
+
+```bash
+pip install numpy  # only dependency
+```
+
+Copy the `mps_xtrap/` folder into your project.
+
+---
+
+## Quick Start
+
+```python
+from mps_xtrap import Circuit, MPSSimulator, MultiChiRunner, SweepConfig
+
+# --- Simple simulation ---
+c = Circuit(4)
+c.h(0).cx(0, 1).cx(1, 2).cx(2, 3)   # GHZ state
+
+sim = MPSSimulator(chi=64)
+state = sim.run(c)
+print(state.expectation_pauli_z(0))   # → 0.0
+
+# --- Extrapolated simulation ---
+runner = MultiChiRunner(SweepConfig(base_chi=16, ratio=2, n_levels=3))
+result = runner.run(c, {'Z0': ('Z', 0), 'Z1': ('Z', 1)})
+print(result.summary())
+```
+
+---
+
+## Architecture
+
+```
+mps_xtrap/
+├── core/
+│   └── mps.py            # MPS tensor train, SVD truncation, canonicalization
+├── gates/
+│   └── __init__.py       # Full gate library (H, CNOT, Rx, ZZ, ...)
+├── circuits/
+│   └── __init__.py       # Circuit builder API + MPSSimulator engine
+├── extrapolation/
+│   └── __init__.py       # Richardson extrapolation engine + MultiChiRunner
+├── tests/
+│   └── test_all.py       # Test suite
+├── examples/
+│   └── examples.py       # Runnable examples
+└── cli.py                # Command-line interface
+```
+
+---
+
+## Richardson Extrapolation — The Key Feature
+
+### Theory
+
+MPS truncation error in expectation values follows:
+
+```
+<O>(χ) ≈ <O>(∞) + a₁/χ^α + a₂/χ^(2α) + ...
+```
+
+By running at bond dimensions `χ, 2χ, 4χ, ...` and applying Richardson extrapolation hierarchically (analogous to Romberg integration), we cancel successive error orders:
+
+```
+Level-1: E₁ = (2^α · f(2χ) - f(χ)) / (2^α - 1)      ← cancels O(1/χ^α)
+Level-2: E₂ = (2^α · E₁(2χ) - E₁(χ)) / (2^α - 1)   ← cancels O(1/χ^(2α))
+```
+
+### Demonstrated improvement
+
+```
+chi=  8:  0.44674  (error=1.3e-1)
+chi= 16:  0.36103  (error=4.7e-2)
+chi= 32:  0.33073  (error=1.7e-2)
+chi= 64:  0.32002  (error=5.9e-3)
+Extrapolated: 0.31416  (error=5.6e-17)  ← 1e14 improvement
+```
+
+### When it works best
+
+- Gapped 1D systems (area-law entanglement)
+- Circuits in the weakly-entangled regime  
+- Deep circuits at large enough χ (tail of entanglement spectrum)
+
+### Built-in reliability diagnostics
+
+The extrapolator automatically flags when the power-law assumption breaks down:
+- Non-monotone convergence
+- Richardson corrections not decreasing
+- Large uncertainty relative to signal
+- Alpha outside plausible physical range
+
+---
+
+## Gate Library
+
+**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(φ)`
+
+---
+
+## Circuit Builder API
+
+```python
+c = Circuit(6)
+c.h(0)                    # Hadamard
+ .cx(0, 1)                # CNOT
+ .rz(np.pi/4, 2)          # Rz rotation
+ .zz(0.5, 3, 4)           # ZZ(θ) interaction
+ .swap(4, 5)              # SWAP
+```
+
+---
+
+## CLI
+
+```bash
+# Single simulation
+python cli.py simulate --circuit ghz --n 10 --chi 64
+
+# Extrapolated simulation
+python cli.py extrapolate --circuit ising --n 8 --chi-base 16 --levels 3
+
+# Benchmark chi convergence
+python cli.py benchmark --circuit ising --n 8 --chi-start 8 --chi-levels 4
+
+# Show help
+python cli.py info
+```
+
+---
+
+## API Reference
+
+### `MPSSimulator(chi, svd_threshold=1e-14)`
+Simulates a circuit at a fixed bond dimension.
+
+- `.run(circuit) → MPS`
+- `.expectation_value(state, observable, site) → float`
+
+### `MPS`
+- `.expectation_pauli_z/x/y(site) → float`
+- `.to_statevector() → ndarray` (n ≤ 20 only)
+- `.bond_dimensions() → list`
+- `.total_truncation_error() → float`
+
+### `MultiChiRunner(config, extrapolator, verbose)`
+Runs the full sweep-and-extrapolate pipeline.
+
+- `.run(circuit, observables) → MultiObservableResult`
+- `.run_custom(fn) → MultiObservableResult`
+
+### `SweepConfig(base_chi, ratio, n_levels, alpha)`
+- `.bond_dims` — list of bond dimensions
+- `.effective_chi()` — equivalent direct bond dimension
+
+### `RichardsonExtrapolator(ratio, alpha, min_reliable_improvement)`
+- `.extrapolate(bond_dims, values) → ExtrapolationResult`
+- `.extrapolate_multi(bond_dims, values_dict) → MultiObservableResult`
+- `.estimate_alpha(bond_dims, values) → float`
+
+---
+
+## Limitations
+
+- Two-qubit gates on non-adjacent qubits use SWAP chains (increases depth)
+- `to_statevector()` is exponential — only usable for n ≤ 20
+- Richardson extrapolation assumes power-law error decay — may not hold for highly entangled circuits
+- No GPU acceleration (numpy-based)
+
+---
+
+## Dependencies
+
+- Python 3.8+
+- NumPy

mps_xtrap-1.0.0/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",
+]