# ATLAS-Q: GPU-Accelerated Quantum Tensor Network Simulator
**Adaptive Tensor Learning And Simulation – Quantum**
**Version 0.6.1** | **October 2025**
> **High-performance quantum simulation using GPU-accelerated tensor networks with molecular chemistry, circuit cutting, and cuQuantum integration**
[]()
[]()
[]()
[]()
[](https://www.buymeacoffee.com/FollowTheSapper)
---
## ⚡ Performance Highlights
- **77K+ ops/sec** gate throughput (GPU-optimized)
- **626,000× memory compression** vs full statevector (30 qubits)
- **20× speedup** on Clifford circuits (Stabilizer backend)
- **1.5-3× speedup** on gate operations (custom Triton kernels)
- **All 46/46 integration tests passing** (Priority 1 + 2 features)
---
## 🚀 Quick Start
### Option 1: Interactive Notebook (No Install!)
Try ATLAS-Q instantly in Google Colab or Jupyter:
**[📓 Open ATLAS_Q_Demo.ipynb in Colab](https://colab.research.google.com/github/followthesapper/ATLAS-Q/blob/ATLAS-Q/ATLAS_Q_Demo.ipynb)**
Or download and run locally:
```bash
wget https://github.com/followthesapper/ATLAS-Q/raw/ATLAS-Q/ATLAS_Q_Demo.ipynb
jupyter notebook ATLAS_Q_Demo.ipynb
```
---
### Option 2: Python Package (Recommended)
```bash
# Install from PyPI
pip install atlas-quantum
# With GPU support
pip install atlas-quantum[gpu]
# Verify installation
python -c "from atlas_q import get_quantum_sim; print('✅ ATLAS-Q installed!')"
```
**First example:**
```python
from atlas_q import get_quantum_sim
QCH, _, _, _ = get_quantum_sim()
sim = QCH()
factors = sim.factor_number(221)
print(f"221 = {factors[0]} × {factors[1]}") # 221 = 13 × 17
```
---
### Option 3: Docker
**GPU version (recommended):**
```bash
docker pull ghcr.io/followthesapper/atlas-q:cuda
docker run --rm -it --gpus all ghcr.io/followthesapper/atlas-q:cuda python3
```
**CPU version:**
```bash
docker pull ghcr.io/followthesapper/atlas-q:cpu
docker run --rm -it ghcr.io/followthesapper/atlas-q:cpu python3
```
**Run benchmarks in Docker:**
```bash
docker run --rm --gpus all ghcr.io/followthesapper/atlas-q:cuda \
python3 /opt/atlas-q/scripts/benchmarks/validate_all_features.py
```
---
### Option 4: From Source
```bash
# Clone repository
git clone https://github.com/followthsapper/ATLAS-Q.git
cd ATLAS-Q
# Install ATLAS-Q
pip install -e .[gpu]
# Setup GPU acceleration (auto-detects your GPU)
./setup_triton.sh
# Run benchmarks
python scripts/benchmarks/validate_all_features.py
```
---
### GPU Acceleration Setup
The `setup_triton.sh` script automatically detects your GPU and configures Triton kernels:
- **Auto-detects:** V100, A100, H100, GB100/GB200, and future architectures
- **Configures:** `TORCH_CUDA_ARCH_LIST` and `TRITON_PTXAS_PATH`
- **Persists:** Adds settings to `~/.bashrc`
**Performance gains:** 1.5-3× faster gate operations, 100-1000× faster period-finding
---
### Command-Line Interface
ATLAS-Q includes a CLI for quick operations:
```bash
# Show help
python -m atlas_q --help
# Factor a number
python -m atlas_q factor 221
# Run all benchmarks
python -m atlas_q benchmark
# Show system info
python -m atlas_q info
# Interactive demo
python -m atlas_q demo
```
See [COMPLETE_GUIDE.md](docs/COMPLETE_GUIDE.md#command-line-interface) for full CLI documentation.
---
## 💡 Examples
### Tensor Network Simulation
```python
from atlas_q.adaptive_mps import AdaptiveMPS
import torch
# Create 10-qubit system with adaptive bond dimensions
mps = AdaptiveMPS(10, bond_dim=8, device='cuda')
# Apply Hadamard gates
H = torch.tensor([[1,1],[1,-1]], dtype=torch.complex64)/torch.sqrt(torch.tensor(2.0))
for q in range(10):
mps.apply_single_qubit_gate(q, H.to('cuda'))
# Apply CNOT gates
CNOT = torch.tensor([[1,0,0,0],[0,1,0,0],[0,0,0,1],[0,0,1,0]],
dtype=torch.complex64).reshape(4,4).to('cuda')
for q in range(0, 9, 2):
mps.apply_two_site_gate(q, CNOT)
print(f"Max bond dimension: {mps.stats_summary()['max_chi']}")
print(f"Memory usage: {mps.memory_usage() / (1024**2):.2f} MB")
```
### Period-Finding & Factorization
```python
from atlas_q import get_quantum_sim
# Get quantum classical hybrid simulator
QuantumClassicalHybrid, _, _, _ = get_quantum_sim()
qc = QuantumClassicalHybrid()
# Factor semiprimes
factors = qc.factor_number(143) # Returns [11, 13]
print(f"143 = {factors[0]} × {factors[1]}")
# Verified against canonical benchmarks:
# - IBM 2001 (N=15): ✅ Pass
# - Photonic 2012 (N=21): ✅ Pass
# - NMR 2012 (N=143): ✅ Pass
```
---
## 📊 Performance vs Competition
| Feature | ATLAS-Q | Qiskit Aer | Cirq | Winner |
|---------|---------|------------|------|--------|
| **Memory (30q)** | 0.03 MB | 16 GB | 16 GB | **ATLAS-Q** (626k×) |
| **GPU Support** | ✅ Triton | ✅ cuQuantum | ❌ | **ATLAS-Q** |
| **Stabilizer** | 20× speedup | Standard | Standard | **ATLAS-Q** |
| **Tensor Networks** | ✅ Native | ❌ | ❌ | **ATLAS-Q** |
| **Ease of Use** | Good | Excellent | Excellent | Qiskit/Cirq |
**Note**: Run `python scripts/benchmarks/compare_with_competitors.py` for detailed performance comparisons
---
## 🎯 What is ATLAS-Q?
ATLAS-Q is a **GPU-accelerated quantum simulator** with two complementary capabilities:
### Tensor Network Simulation
1. **Adaptive MPS**: Memory-efficient quantum state representation (O(n·χ²) vs O(2ⁿ))
2. **NISQ Algorithms**: VQE, QAOA with noise models
3. **Time Evolution**: TDVP for Hamiltonian dynamics
4. **Specialized Backends**: Stabilizer for Clifford circuits, MPO for observables
5. **Hamiltonians**: Ising, Heisenberg, Molecular (PySCF), MaxCut (QAOA)
6. **GPU Acceleration**: Custom Triton kernels + cuBLAS tensor cores
### Period-Finding & Factorization
1. **Shor's Algorithm**: Integer factorization via quantum period-finding
2. **Compressed States**: Periodic states (O(1) memory), product states (O(n) memory)
3. **Verified Results**: Matches canonical benchmarks (N=15, 21, 143)
### Key Innovations
- ✅ **Custom Triton Kernels**: Fused gate operations for 1.5-3× speedup
- ✅ **Adaptive Bond Dimensions**: Dynamic memory management based on entanglement
- ✅ **Hybrid Stabilizer/MPS**: 20× faster Clifford circuits with automatic switching
- ✅ **GPU-Optimized Einsums**: cuBLAS + tensor cores for tensor contractions
- ✅ **Specialized Representations**: O(1) memory for periodic states, O(n) for product states
---
## 📚 Documentation
### Interactive Tutorial
- **[📓 Jupyter Notebook](ATLAS_Q_Demo.ipynb)** - Complete interactive demo (works in Colab!)
### Online Documentation
- **[📖 Documentation Site](https://followthsapper.github.io/ATLAS-Q/)** - Browse all docs online
### Guides & References
- **[Complete Guide](docs/COMPLETE_GUIDE.md)** - Installation, tutorials, API reference (start here!)
- **[Feature Status](docs/FEATURE_STATUS.md)** - What's actually implemented
- **[Research Paper](docs/RESEARCH_PAPER.md)** - Mathematical foundations and algorithms
- **[Whitepaper](docs/WHITEPAPER.md)** - Technical architecture and implementation
- **[Overview](docs/OVERVIEW.md)** - High-level explanation for all audiences
---
## 🏗️ Architecture
### Core Components
```
ATLAS-Q/
├── src/atlas_q/
│ ├── adaptive_mps.py # Adaptive MPS with GPU support
│ ├── quantum_hybrid_system.py # Period-finding & factorization
│ ├── mpo_ops.py # MPO operations (Hamiltonians)
│ ├── tdvp.py # Time evolution (TDVP)
│ ├── vqe_qaoa.py # Variational algorithms
│ ├── stabilizer_backend.py # Fast Clifford simulation
│ ├── noise_models.py # NISQ noise models
│ ├── peps.py # 2D tensor networks
│ └── tools_qih/ # Quantum-inspired ML
├── triton_kernels/
│ ├── mps_complex.py # Custom Triton kernels (1.5-3× faster)
│ ├── mps_ops.py # MPS tensor operations
│ └── modpow.py # Modular exponentiation
├── scripts/benchmarks/
│ ├── validate_all_features.py # 7/7 tensor network benchmarks
│ ├── compare_with_competitors.py # vs Qiskit/Cirq/ITensor
│ └── max_qubits_scaling_test.py # Maximum qubits scaling
├── tests/
│ ├── integration/ # Integration & API tests
│ └── legacy/ # Legacy quantum-inspired tests
└── docs/ # Documentation & guides
```
### Technology Stack
- **PyTorch 2.10+** (CUDA backend)
- **Triton** (custom GPU kernels)
- **cuBLAS/CUTLASS** (tensor cores)
- **NumPy/SciPy** (linear algebra)
---
## 🎓 Use Cases
### ✅ BEST FOR:
- **Tensor Networks**: 20-50 qubits with moderate entanglement
- **VQE/QAOA**: Optimization on NISQ devices with noise
- **Grover Search**: Unstructured database search with quadratic speedup
- **Time Evolution**: Hamiltonian dynamics via TDVP
- **Period-Finding**: Shor's algorithm for integer factorization
- **Memory-Constrained**: 626,000× compression vs statevector
- **GPU Workloads**: Custom Triton kernels + cuBLAS
### ⚠️ NOT IDEAL FOR:
- Highly entangled states (use full statevector)
- Arbitrary connectivity (MPS assumes 1D/2D structure)
- CPU-only environments
---
## 📈 Benchmark Results
### Internal Benchmarks (All Passing)
```
✅ Benchmark 1: Noise Models - 3/3 passing
✅ Benchmark 2: Stabilizer Backend - 3/3 passing (20× speedup)
✅ Benchmark 3: MPO Operations - 3/3 passing
✅ Benchmark 4: TDVP Time Evolution - 2/2 passing
✅ Benchmark 5: VQE/QAOA - 2/2 passing
✅ Benchmark 6: 2D Circuits - 2/2 passing
✅ Benchmark 7: Integration Tests - 2/2 passing
```
### Key Metrics
| Metric | Value | Notes |
|--------|-------|-------|
| Gate throughput | 77,304 ops/sec | GPU-optimized |
| Stabilizer speedup | 20.4× | vs generic MPS |
| MPO evaluations | 1,372/sec | Hamiltonian expectations |
| VQE time (6q) | 1.68s | 50 iterations |
| Memory (30q) | 0.03 MB | vs 16 GB statevector |
---
## 🔬 Example Applications
### VQE for Quantum Chemistry
```python
from atlas_q import get_mpo_ops, get_vqe_qaoa
# Build molecular Hamiltonian (requires: pip install pyscf)
mpo = get_mpo_ops()
H = mpo['MPOBuilder'].molecular_hamiltonian_from_specs(
molecule='H2',
basis='sto-3g',
device='cuda'
)
# Run VQE to find ground state energy
vqe_mod = get_vqe_qaoa()
vqe = vqe_mod['VQE'](H, ansatz_depth=3, device='cuda')
energy, params = vqe.optimize(max_iter=50)
print(f"Ground state energy: {energy.real:.6f} Ha")
```
### Grover's Quantum Search
```python
from atlas_q.grover import grover_search
# Search for state 7 in 4-qubit space (16 states total)
result = grover_search(
n_qubits=4,
marked_states={7}, # Mark state |0111⟩
device='cpu'
)
print(f"Found state: {result['measured_state']}") # Found state: 7
print(f"Success probability: {result['success_probability']:.3f}") # ~0.96
print(f"Iterations: {result['iterations_used']}") # 3 iterations (O(√N))
# Search using function oracle (e.g., find even numbers)
result = grover_search(
n_qubits=4,
marked_states=lambda x: x % 2 == 0,
device='cpu'
)
print(f"Found even number: {result['measured_state']}")
```
### TDVP Time Evolution
```python
from atlas_q.tdvp import TDVP1Site, TDVPConfig
from atlas_q.mpo_ops import MPOBuilder
from atlas_q.adaptive_mps import AdaptiveMPS
# Create Hamiltonian and initial state
H = MPOBuilder.ising_hamiltonian(n_sites=10, J=1.0, h=0.5, device='cuda')
mps = AdaptiveMPS(10, bond_dim=8, device='cuda')
# Configure TDVP
config = TDVPConfig(dt=0.01, t_final=1.0, use_gpu_optimized=True)
tdvp = TDVP1Site(H, mps, config)
# Run time evolution
times, energies = tdvp.run()
```
---
## 🚧 Roadmap
### Current Status (v0.6.1)
- ✅ GPU-accelerated tensor networks with custom Triton kernels
- ✅ Adaptive MPS with error tracking
- ✅ Stabilizer backend (20× speedup)
- ✅ TDVP, VQE/QAOA implementations
- ✅ **NEW:** Grover's quantum search (MPO-based oracles, 94-100% accuracy)
- ✅ **NEW:** Molecular Hamiltonians (PySCF integration)
- ✅ **NEW:** MaxCut QAOA Hamiltonians
- ✅ **NEW:** Circuit Cutting & partitioning
- ✅ **NEW:** PEPS 2D tensor networks
- ✅ **NEW:** Distributed MPS (multi-GPU ready)
- ✅ **NEW:** cuQuantum 25.x backend integration
- ✅ All 46/46 integration tests passing
### Planned Features
- [ ] Integration adapters for Qiskit/Cirq circuits
- [ ] Additional tutorial notebooks
- [ ] PyPI package update to v0.6.1 (currently at v0.6.0)
---
## 🤝 Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
### Development Setup
```bash
# Clone with submodules
git clone --recursive https://github.com/followthsapper/ATLAS-Q.git
# Install dev dependencies
pip install -r requirements.txt
pip install pytest pytest-cov black isort
# Run tests
pytest tests/ -v
# Run benchmarks
python scripts/benchmarks/validate_all_features.py
```
---
## 📝 Citation
If you use ATLAS-Q in your research, please cite:
```bibtex
@software{atlasq2025,
title={ATLAS-Q: Adaptive Tensor Learning And Simulation – Quantum},
author={ATLAS-Q Development Team},
year={2025},
url={https://github.com/followthsapper/ATLAS-Q},
version={0.5.0}
}
```
---
## 📄 License
MIT License - see [LICENSE](LICENSE) for details
---
## 🙏 Acknowledgments
- **PyTorch** team for GPU infrastructure
- **Triton** team for custom kernel framework
- **ITensor/TeNPy** for tensor network inspiration
- **Qiskit/Cirq** for quantum computing ecosystem
---
## 📞 Contact
- **Issues**: [GitHub Issues](https://github.com/followthsapper/ATLAS-Q/issues)
- **Discussions**: [GitHub Discussions](https://github.com/followthsapper/ATLAS-Q/discussions)
---
**ATLAS-Q**: GPU-accelerated tensor network simulator achieving 626,000× memory compression through adaptive MPS, custom Triton kernels, and specialized quantum state representations.
Raw data
{
"_id": null,
"home_page": null,
"name": "atlas-quantum",
"maintainer": "ATLAS-Q Development Team",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "quantum, simulation, tensor-networks, mps, peps, vqe, qaoa, tdvp, period-finding, molecular-chemistry, circuit-cutting, gpu-acceleration, cuquantum, nisq",
"author": "ATLAS-Q Development Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/87/e5/12adc942f802c8e1aa8eeee0cc42a618c6af19b82c1131bc48276ac0c10e/atlas_quantum-0.6.2.tar.gz",
"platform": null,
"description": "# ATLAS-Q: GPU-Accelerated Quantum Tensor Network Simulator\n**Adaptive Tensor Learning And Simulation \u2013 Quantum**\n\n**Version 0.6.1** | **October 2025**\n\n> **High-performance quantum simulation using GPU-accelerated tensor networks with molecular chemistry, circuit cutting, and cuQuantum integration**\n\n[]()\n[]()\n[]()\n[]()\n\n[](https://www.buymeacoffee.com/FollowTheSapper)\n\n---\n\n## \u26a1 Performance Highlights\n\n- **77K+ ops/sec** gate throughput (GPU-optimized)\n- **626,000\u00d7 memory compression** vs full statevector (30 qubits)\n- **20\u00d7 speedup** on Clifford circuits (Stabilizer backend)\n- **1.5-3\u00d7 speedup** on gate operations (custom Triton kernels)\n- **All 46/46 integration tests passing** (Priority 1 + 2 features)\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Option 1: Interactive Notebook (No Install!)\n\nTry ATLAS-Q instantly in Google Colab or Jupyter:\n\n**[\ud83d\udcd3 Open ATLAS_Q_Demo.ipynb in Colab](https://colab.research.google.com/github/followthesapper/ATLAS-Q/blob/ATLAS-Q/ATLAS_Q_Demo.ipynb)**\n\nOr download and run locally:\n```bash\nwget https://github.com/followthesapper/ATLAS-Q/raw/ATLAS-Q/ATLAS_Q_Demo.ipynb\njupyter notebook ATLAS_Q_Demo.ipynb\n```\n\n---\n\n### Option 2: Python Package (Recommended)\n\n```bash\n# Install from PyPI\npip install atlas-quantum\n\n# With GPU support\npip install atlas-quantum[gpu]\n\n# Verify installation\npython -c \"from atlas_q import get_quantum_sim; print('\u2705 ATLAS-Q installed!')\"\n```\n\n**First example:**\n```python\nfrom atlas_q import get_quantum_sim\n\nQCH, _, _, _ = get_quantum_sim()\nsim = QCH()\nfactors = sim.factor_number(221)\nprint(f\"221 = {factors[0]} \u00d7 {factors[1]}\") # 221 = 13 \u00d7 17\n```\n\n---\n\n### Option 3: Docker\n\n**GPU version (recommended):**\n```bash\ndocker pull ghcr.io/followthesapper/atlas-q:cuda\ndocker run --rm -it --gpus all ghcr.io/followthesapper/atlas-q:cuda python3\n```\n\n**CPU version:**\n```bash\ndocker pull ghcr.io/followthesapper/atlas-q:cpu\ndocker run --rm -it ghcr.io/followthesapper/atlas-q:cpu python3\n```\n\n**Run benchmarks in Docker:**\n```bash\ndocker run --rm --gpus all ghcr.io/followthesapper/atlas-q:cuda \\\n python3 /opt/atlas-q/scripts/benchmarks/validate_all_features.py\n```\n\n---\n\n### Option 4: From Source\n\n```bash\n# Clone repository\ngit clone https://github.com/followthsapper/ATLAS-Q.git\ncd ATLAS-Q\n\n# Install ATLAS-Q\npip install -e .[gpu]\n\n# Setup GPU acceleration (auto-detects your GPU)\n./setup_triton.sh\n\n# Run benchmarks\npython scripts/benchmarks/validate_all_features.py\n```\n\n---\n\n### GPU Acceleration Setup\n\nThe `setup_triton.sh` script automatically detects your GPU and configures Triton kernels:\n\n- **Auto-detects:** V100, A100, H100, GB100/GB200, and future architectures\n- **Configures:** `TORCH_CUDA_ARCH_LIST` and `TRITON_PTXAS_PATH`\n- **Persists:** Adds settings to `~/.bashrc`\n\n**Performance gains:** 1.5-3\u00d7 faster gate operations, 100-1000\u00d7 faster period-finding\n\n---\n\n### Command-Line Interface\n\nATLAS-Q includes a CLI for quick operations:\n\n```bash\n# Show help\npython -m atlas_q --help\n\n# Factor a number\npython -m atlas_q factor 221\n\n# Run all benchmarks\npython -m atlas_q benchmark\n\n# Show system info\npython -m atlas_q info\n\n# Interactive demo\npython -m atlas_q demo\n```\n\nSee [COMPLETE_GUIDE.md](docs/COMPLETE_GUIDE.md#command-line-interface) for full CLI documentation.\n\n---\n\n## \ud83d\udca1 Examples\n\n### Tensor Network Simulation\n\n```python\nfrom atlas_q.adaptive_mps import AdaptiveMPS\nimport torch\n\n# Create 10-qubit system with adaptive bond dimensions\nmps = AdaptiveMPS(10, bond_dim=8, device='cuda')\n\n# Apply Hadamard gates\nH = torch.tensor([[1,1],[1,-1]], dtype=torch.complex64)/torch.sqrt(torch.tensor(2.0))\nfor q in range(10):\n mps.apply_single_qubit_gate(q, H.to('cuda'))\n\n# Apply CNOT gates\nCNOT = torch.tensor([[1,0,0,0],[0,1,0,0],[0,0,0,1],[0,0,1,0]],\n dtype=torch.complex64).reshape(4,4).to('cuda')\nfor q in range(0, 9, 2):\n mps.apply_two_site_gate(q, CNOT)\n\nprint(f\"Max bond dimension: {mps.stats_summary()['max_chi']}\")\nprint(f\"Memory usage: {mps.memory_usage() / (1024**2):.2f} MB\")\n```\n\n### Period-Finding & Factorization\n\n```python\nfrom atlas_q import get_quantum_sim\n\n# Get quantum classical hybrid simulator\nQuantumClassicalHybrid, _, _, _ = get_quantum_sim()\nqc = QuantumClassicalHybrid()\n\n# Factor semiprimes\nfactors = qc.factor_number(143) # Returns [11, 13]\nprint(f\"143 = {factors[0]} \u00d7 {factors[1]}\")\n\n# Verified against canonical benchmarks:\n# - IBM 2001 (N=15): \u2705 Pass\n# - Photonic 2012 (N=21): \u2705 Pass\n# - NMR 2012 (N=143): \u2705 Pass\n```\n\n---\n\n## \ud83d\udcca Performance vs Competition\n\n| Feature | ATLAS-Q | Qiskit Aer | Cirq | Winner |\n|---------|---------|------------|------|--------|\n| **Memory (30q)** | 0.03 MB | 16 GB | 16 GB | **ATLAS-Q** (626k\u00d7) |\n| **GPU Support** | \u2705 Triton | \u2705 cuQuantum | \u274c | **ATLAS-Q** |\n| **Stabilizer** | 20\u00d7 speedup | Standard | Standard | **ATLAS-Q** |\n| **Tensor Networks** | \u2705 Native | \u274c | \u274c | **ATLAS-Q** |\n| **Ease of Use** | Good | Excellent | Excellent | Qiskit/Cirq |\n\n**Note**: Run `python scripts/benchmarks/compare_with_competitors.py` for detailed performance comparisons\n\n---\n\n## \ud83c\udfaf What is ATLAS-Q?\n\nATLAS-Q is a **GPU-accelerated quantum simulator** with two complementary capabilities:\n\n### Tensor Network Simulation\n1. **Adaptive MPS**: Memory-efficient quantum state representation (O(n\u00b7\u03c7\u00b2) vs O(2\u207f))\n2. **NISQ Algorithms**: VQE, QAOA with noise models\n3. **Time Evolution**: TDVP for Hamiltonian dynamics\n4. **Specialized Backends**: Stabilizer for Clifford circuits, MPO for observables\n5. **Hamiltonians**: Ising, Heisenberg, Molecular (PySCF), MaxCut (QAOA)\n6. **GPU Acceleration**: Custom Triton kernels + cuBLAS tensor cores\n\n### Period-Finding & Factorization\n1. **Shor's Algorithm**: Integer factorization via quantum period-finding\n2. **Compressed States**: Periodic states (O(1) memory), product states (O(n) memory)\n3. **Verified Results**: Matches canonical benchmarks (N=15, 21, 143)\n\n### Key Innovations\n\n- \u2705 **Custom Triton Kernels**: Fused gate operations for 1.5-3\u00d7 speedup\n- \u2705 **Adaptive Bond Dimensions**: Dynamic memory management based on entanglement\n- \u2705 **Hybrid Stabilizer/MPS**: 20\u00d7 faster Clifford circuits with automatic switching\n- \u2705 **GPU-Optimized Einsums**: cuBLAS + tensor cores for tensor contractions\n- \u2705 **Specialized Representations**: O(1) memory for periodic states, O(n) for product states\n\n---\n\n## \ud83d\udcda Documentation\n\n### Interactive Tutorial\n- **[\ud83d\udcd3 Jupyter Notebook](ATLAS_Q_Demo.ipynb)** - Complete interactive demo (works in Colab!)\n\n### Online Documentation\n- **[\ud83d\udcd6 Documentation Site](https://followthsapper.github.io/ATLAS-Q/)** - Browse all docs online\n\n### Guides & References\n- **[Complete Guide](docs/COMPLETE_GUIDE.md)** - Installation, tutorials, API reference (start here!)\n- **[Feature Status](docs/FEATURE_STATUS.md)** - What's actually implemented\n- **[Research Paper](docs/RESEARCH_PAPER.md)** - Mathematical foundations and algorithms\n- **[Whitepaper](docs/WHITEPAPER.md)** - Technical architecture and implementation\n- **[Overview](docs/OVERVIEW.md)** - High-level explanation for all audiences\n\n---\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Core Components\n\n```\nATLAS-Q/\n\u251c\u2500\u2500 src/atlas_q/\n\u2502 \u251c\u2500\u2500 adaptive_mps.py # Adaptive MPS with GPU support\n\u2502 \u251c\u2500\u2500 quantum_hybrid_system.py # Period-finding & factorization\n\u2502 \u251c\u2500\u2500 mpo_ops.py # MPO operations (Hamiltonians)\n\u2502 \u251c\u2500\u2500 tdvp.py # Time evolution (TDVP)\n\u2502 \u251c\u2500\u2500 vqe_qaoa.py # Variational algorithms\n\u2502 \u251c\u2500\u2500 stabilizer_backend.py # Fast Clifford simulation\n\u2502 \u251c\u2500\u2500 noise_models.py # NISQ noise models\n\u2502 \u251c\u2500\u2500 peps.py # 2D tensor networks\n\u2502 \u2514\u2500\u2500 tools_qih/ # Quantum-inspired ML\n\u251c\u2500\u2500 triton_kernels/\n\u2502 \u251c\u2500\u2500 mps_complex.py # Custom Triton kernels (1.5-3\u00d7 faster)\n\u2502 \u251c\u2500\u2500 mps_ops.py # MPS tensor operations\n\u2502 \u2514\u2500\u2500 modpow.py # Modular exponentiation\n\u251c\u2500\u2500 scripts/benchmarks/\n\u2502 \u251c\u2500\u2500 validate_all_features.py # 7/7 tensor network benchmarks\n\u2502 \u251c\u2500\u2500 compare_with_competitors.py # vs Qiskit/Cirq/ITensor\n\u2502 \u2514\u2500\u2500 max_qubits_scaling_test.py # Maximum qubits scaling\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 integration/ # Integration & API tests\n\u2502 \u2514\u2500\u2500 legacy/ # Legacy quantum-inspired tests\n\u2514\u2500\u2500 docs/ # Documentation & guides\n```\n\n### Technology Stack\n\n- **PyTorch 2.10+** (CUDA backend)\n- **Triton** (custom GPU kernels)\n- **cuBLAS/CUTLASS** (tensor cores)\n- **NumPy/SciPy** (linear algebra)\n\n---\n\n## \ud83c\udf93 Use Cases\n\n### \u2705 BEST FOR:\n- **Tensor Networks**: 20-50 qubits with moderate entanglement\n- **VQE/QAOA**: Optimization on NISQ devices with noise\n- **Grover Search**: Unstructured database search with quadratic speedup\n- **Time Evolution**: Hamiltonian dynamics via TDVP\n- **Period-Finding**: Shor's algorithm for integer factorization\n- **Memory-Constrained**: 626,000\u00d7 compression vs statevector\n- **GPU Workloads**: Custom Triton kernels + cuBLAS\n\n### \u26a0\ufe0f NOT IDEAL FOR:\n- Highly entangled states (use full statevector)\n- Arbitrary connectivity (MPS assumes 1D/2D structure)\n- CPU-only environments\n\n---\n\n## \ud83d\udcc8 Benchmark Results\n\n### Internal Benchmarks (All Passing)\n\n```\n\u2705 Benchmark 1: Noise Models - 3/3 passing\n\u2705 Benchmark 2: Stabilizer Backend - 3/3 passing (20\u00d7 speedup)\n\u2705 Benchmark 3: MPO Operations - 3/3 passing\n\u2705 Benchmark 4: TDVP Time Evolution - 2/2 passing\n\u2705 Benchmark 5: VQE/QAOA - 2/2 passing\n\u2705 Benchmark 6: 2D Circuits - 2/2 passing\n\u2705 Benchmark 7: Integration Tests - 2/2 passing\n```\n\n### Key Metrics\n\n| Metric | Value | Notes |\n|--------|-------|-------|\n| Gate throughput | 77,304 ops/sec | GPU-optimized |\n| Stabilizer speedup | 20.4\u00d7 | vs generic MPS |\n| MPO evaluations | 1,372/sec | Hamiltonian expectations |\n| VQE time (6q) | 1.68s | 50 iterations |\n| Memory (30q) | 0.03 MB | vs 16 GB statevector |\n\n---\n\n## \ud83d\udd2c Example Applications\n\n### VQE for Quantum Chemistry\n\n```python\nfrom atlas_q import get_mpo_ops, get_vqe_qaoa\n\n# Build molecular Hamiltonian (requires: pip install pyscf)\nmpo = get_mpo_ops()\nH = mpo['MPOBuilder'].molecular_hamiltonian_from_specs(\n molecule='H2',\n basis='sto-3g',\n device='cuda'\n)\n\n# Run VQE to find ground state energy\nvqe_mod = get_vqe_qaoa()\nvqe = vqe_mod['VQE'](H, ansatz_depth=3, device='cuda')\nenergy, params = vqe.optimize(max_iter=50)\nprint(f\"Ground state energy: {energy.real:.6f} Ha\")\n```\n\n### Grover's Quantum Search\n\n```python\nfrom atlas_q.grover import grover_search\n\n# Search for state 7 in 4-qubit space (16 states total)\nresult = grover_search(\n n_qubits=4,\n marked_states={7}, # Mark state |0111\u27e9\n device='cpu'\n)\n\nprint(f\"Found state: {result['measured_state']}\") # Found state: 7\nprint(f\"Success probability: {result['success_probability']:.3f}\") # ~0.96\nprint(f\"Iterations: {result['iterations_used']}\") # 3 iterations (O(\u221aN))\n\n# Search using function oracle (e.g., find even numbers)\nresult = grover_search(\n n_qubits=4,\n marked_states=lambda x: x % 2 == 0,\n device='cpu'\n)\nprint(f\"Found even number: {result['measured_state']}\")\n```\n\n### TDVP Time Evolution\n\n```python\nfrom atlas_q.tdvp import TDVP1Site, TDVPConfig\nfrom atlas_q.mpo_ops import MPOBuilder\nfrom atlas_q.adaptive_mps import AdaptiveMPS\n\n# Create Hamiltonian and initial state\nH = MPOBuilder.ising_hamiltonian(n_sites=10, J=1.0, h=0.5, device='cuda')\nmps = AdaptiveMPS(10, bond_dim=8, device='cuda')\n\n# Configure TDVP\nconfig = TDVPConfig(dt=0.01, t_final=1.0, use_gpu_optimized=True)\ntdvp = TDVP1Site(H, mps, config)\n\n# Run time evolution\ntimes, energies = tdvp.run()\n```\n\n---\n\n## \ud83d\udea7 Roadmap\n\n### Current Status (v0.6.1)\n- \u2705 GPU-accelerated tensor networks with custom Triton kernels\n- \u2705 Adaptive MPS with error tracking\n- \u2705 Stabilizer backend (20\u00d7 speedup)\n- \u2705 TDVP, VQE/QAOA implementations\n- \u2705 **NEW:** Grover's quantum search (MPO-based oracles, 94-100% accuracy)\n- \u2705 **NEW:** Molecular Hamiltonians (PySCF integration)\n- \u2705 **NEW:** MaxCut QAOA Hamiltonians\n- \u2705 **NEW:** Circuit Cutting & partitioning\n- \u2705 **NEW:** PEPS 2D tensor networks\n- \u2705 **NEW:** Distributed MPS (multi-GPU ready)\n- \u2705 **NEW:** cuQuantum 25.x backend integration\n- \u2705 All 46/46 integration tests passing\n\n### Planned Features\n- [ ] Integration adapters for Qiskit/Cirq circuits\n- [ ] Additional tutorial notebooks\n- [ ] PyPI package update to v0.6.1 (currently at v0.6.0)\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Setup\n\n```bash\n# Clone with submodules\ngit clone --recursive https://github.com/followthsapper/ATLAS-Q.git\n\n# Install dev dependencies\npip install -r requirements.txt\npip install pytest pytest-cov black isort\n\n# Run tests\npytest tests/ -v\n\n# Run benchmarks\npython scripts/benchmarks/validate_all_features.py\n```\n\n---\n\n## \ud83d\udcdd Citation\n\nIf you use ATLAS-Q in your research, please cite:\n\n```bibtex\n@software{atlasq2025,\n title={ATLAS-Q: Adaptive Tensor Learning And Simulation \u2013 Quantum},\n author={ATLAS-Q Development Team},\n year={2025},\n url={https://github.com/followthsapper/ATLAS-Q},\n version={0.5.0}\n}\n```\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\n- **PyTorch** team for GPU infrastructure\n- **Triton** team for custom kernel framework\n- **ITensor/TeNPy** for tensor network inspiration\n- **Qiskit/Cirq** for quantum computing ecosystem\n\n---\n\n## \ud83d\udcde Contact\n\n- **Issues**: [GitHub Issues](https://github.com/followthsapper/ATLAS-Q/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/followthsapper/ATLAS-Q/discussions)\n\n---\n\n**ATLAS-Q**: GPU-accelerated tensor network simulator achieving 626,000\u00d7 memory compression through adaptive MPS, custom Triton kernels, and specialized quantum state representations.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GPU-accelerated quantum tensor network simulator with adaptive MPS, molecular chemistry, circuit cutting, PEPS 2D networks, and cuQuantum backend",
"version": "0.6.2",
"project_urls": {
"Bug Tracker": "https://github.com/followthesapper/ATLAS-Q/issues",
"Changelog": "https://github.com/followthesapper/ATLAS-Q/blob/main/docs/CHANGELOG.md",
"Documentation": "https://github.com/followthesapper/ATLAS-Q/tree/main/docs",
"Homepage": "https://github.com/followthesapper/ATLAS-Q",
"Repository": "https://github.com/followthesapper/ATLAS-Q"
},
"split_keywords": [
"quantum",
" simulation",
" tensor-networks",
" mps",
" peps",
" vqe",
" qaoa",
" tdvp",
" period-finding",
" molecular-chemistry",
" circuit-cutting",
" gpu-acceleration",
" cuquantum",
" nisq"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ef5d5641b0e1b3b620b27a3aa88dd2e9b0a1bb8d463455f49337975f78692427",
"md5": "ab000888e6c629687e0a16382b9322ca",
"sha256": "3a8c31cb960f6a1335461c3881cf401bea83f922b543aba23e49f7e989488d65"
},
"downloads": -1,
"filename": "atlas_quantum-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ab000888e6c629687e0a16382b9322ca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 152184,
"upload_time": "2025-10-29T22:14:16",
"upload_time_iso_8601": "2025-10-29T22:14:16.636936Z",
"url": "https://files.pythonhosted.org/packages/ef/5d/5641b0e1b3b620b27a3aa88dd2e9b0a1bb8d463455f49337975f78692427/atlas_quantum-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "87e512adc942f802c8e1aa8eeee0cc42a618c6af19b82c1131bc48276ac0c10e",
"md5": "9ed4105f496a4e60b3d28d114dcae4d7",
"sha256": "fe46e627041733d2c494535cf0f885d556a5c74753de6c398c304b6ef4a1996b"
},
"downloads": -1,
"filename": "atlas_quantum-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "9ed4105f496a4e60b3d28d114dcae4d7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2788745,
"upload_time": "2025-10-29T22:14:18",
"upload_time_iso_8601": "2025-10-29T22:14:18.240217Z",
"url": "https://files.pythonhosted.org/packages/87/e5/12adc942f802c8e1aa8eeee0cc42a618c6af19b82c1131bc48276ac0c10e/atlas_quantum-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 22:14:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "followthesapper",
"github_project": "ATLAS-Q",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.22"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.6"
]
]
},
{
"name": "torch",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "triton",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.10.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.3"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"4.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "atlas-quantum"
}
JSON
