lagc-quantum-photonics 1.0.3

LossAware-GraphCompiler: CPU-only loss-aware quantum graph compiler for photonic quantum computing simulation

LAGC

LossAware-GraphCompiler

A CPU-only, loss-aware quantum graph compiler for photonic quantum computing simulation

Features • Installation • Quick Start • Docs • Citation

---

🎯 What is LAGC?

LAGC is a high-performance simulation library for photonic quantum computing that runs entirely on CPU — no GPU required.

It models realistic photon loss, automatically repairs damaged graph states through graph surgery, and performs memory-efficient tensor network contraction to simulate large-scale cluster states.

Why LAGC?

Traditional Simulators	LAGC
Requires GPU	✅ CPU-only operation
Disk swap on memory overflow (100x slower)	✅ Recursive slicing within RAM
Ideal states only	✅ Realistic loss modeling + auto recovery
Low experimental accuracy	✅ Hardware-aware error mitigation

---

✨ Key Features

• 🖥️ CPU-Only: No GPU required — runs on standard hardware
• 📉 Loss-Aware: Realistic photon loss modeling with automatic graph surgery
• 💾 Memory-Efficient: Recursive tensor slicing stays within RAM limits
• 🔧 Hardware Models: Built-in noise profiles (ideal, realistic, near-term, experimental, future)
• 📊 Multiple Topologies: 3D RHG, 2D Cluster, Linear, GHZ, Ring, Complete

---

📦 Installation

pip install lagc

From Source

git clone https://github.com/quantum-dev/lagc.git
cd lagc
pip install -e ".[dev]"

Requirements

• Python ≥ 3.9
• NumPy, SciPy, opt-einsum, NetworkX (auto-installed)
• No GPU needed ✨

---

🚀 Quick Start

from lagc import LAGC

# 1. Create simulator (8GB RAM limit)
sim = LAGC(ram_limit_gb=8.0, hardware='realistic')

# 2. Build 3D RHG lattice (for fault-tolerant quantum computing)
sim.create_lattice('3d_rhg', 5, 5, 5)
print(f"Created: {sim.n_qubits} qubits")

# 3. Apply 5% photon loss with automatic recovery
sim.apply_loss(p_loss=0.05)

# 4. Run simulation
result = sim.run_simulation()

# 5. Get results
print(f"Fidelity: {result.fidelity:.4f}")
print(f"Active qubits: {result.n_active}/{result.n_qubits}")
print(f"Time: {result.execution_time:.2f}s")

---

🗺️ Supported Topologies

Topology	Use Case
'3d_rhg'	Fault-tolerant MBQC (Raussendorf-Harrington-Goyal)
'2d_cluster'	Standard cluster state
'linear'	1D chain (one-way quantum computing)
'ghz'	GHZ state (entanglement distribution)
'ring'	Cyclic protocols
'complete'	Fully connected graph

---

🔧 Hardware Models

from lagc import LAGC

# Built-in presets
sim = LAGC(hardware='ideal')        # Perfect system (no errors)
sim = LAGC(hardware='realistic')    # Current technology
sim = LAGC(hardware='near_term')    # 5-year projection
sim = LAGC(hardware='experimental') # Cutting-edge prototypes
sim = LAGC(hardware='future')       # 10-year outlook

Custom Hardware

from lagc import HardwareModel, HardwareParams

params = HardwareParams(
    source_efficiency=0.92,
    detector_efficiency=0.88,
    gate_error_cz=0.015,
    coherence_time=5e-6
)
sim = LAGC(hardware=HardwareModel(params))

---

📊 Example: Loss Threshold Analysis

from lagc import LAGC

sim = LAGC(hardware='ideal', seed=42)

results = sim.scan_loss_rates(
    loss_rates=[0.0, 0.05, 0.10, 0.15, 0.20],
    topology='2d_cluster',
    dims=(10, 10),
    n_samples=5
)

for p, f in zip(results['loss_rates'], results['fidelities']):
    bar = '█' * int(f * 30)
    print(f"p={p:.2f}: {f:.4f} |{bar}")

Output:

p=0.00: 1.0000 |██████████████████████████████
p=0.05: 0.8521 |█████████████████████████
p=0.10: 0.6234 |██████████████████
p=0.15: 0.3892 |███████████
p=0.20: 0.1847 |█████

---

🧮 Core Algorithms

Algorithm 1: Graph Surgery (XOR-based)

For each lost photon, performs Local Complementation (τ_a) to repair the graph state:

# Invert edges between neighbors of lost node a
adj_matrix[neighbors(a), neighbors(a)] ^= 1

Algorithm 2: Recursive Tensor Slicing

Automatic memory management:

Intermediate tensor > Available RAM?
├── YES → Cut highest-centrality bond
│         ├── Branch 0: index=0
│         └── Branch 1: index=1
│         → Parallel execution via ProcessPoolExecutor
└── NO  → Direct contraction

Algorithm 3: Fidelity Estimation

$$F_{final} = \prod (1 - p_{gate})^{n_{gates}} \times \exp\left(-\sum \text{loss_paths}\right)$$

---

⚡ Performance

Lattice	Qubits	Time (8-core)	Memory
4×4 Cluster	16	0.07s	< 1 GB
5×5 Cluster	25	~62s	~2 GB
3D RHG 2×2×2	18	0.21s	< 1 GB

Benchmarked on Intel Core i7

---

💻 Command Line Interface

# Show version
lagc --version

# Show library info
lagc info

# Run simulation
lagc simulate --topology 2d_cluster --size 5 5 --loss 0.05 --hardware realistic

---

📚 API Reference

Main Classes

Class	Description
LAGC	Main simulator interface
StabilizerGraph	Graph state management
TensorSlicer	Memory-efficient contraction
LossRecovery	Error mitigation
HardwareModel	Noise modeling
TopologyGenerator	Lattice creation

from lagc import (
    LAGC,
    StabilizerGraph,
    TensorSlicer,
    LossRecovery,
    HardwareModel,
    TopologyGenerator,
)

---

📖 Documentation

Full documentation: https://lagc.readthedocs.io

• Getting Started Tutorial
• API Reference
• Theoretical Background

---

📝 Citation

If you use LAGC in your research, please cite:

@software{lagc2026,
  title = {LAGC: LossAware-GraphCompiler for Photonic Quantum Computing},
  author = {LAGC Research Team},
  year = {2026},
  url = {https://github.com/quantum-dev/lagc},
  version = {1.0.0}
}

---

📚 References

1. Raussendorf, R., Harrington, J., & Goyal, K. (2007). "Topological fault-tolerance in cluster state quantum computation." New Journal of Physics.

2. Bartolucci, S., et al. (2023). "Fusion-based quantum computation." Nature Communications.

3. Bombin, H., et al. (2021). "Interleaving: Modular architectures for fault-tolerant photonic quantum computing." arXiv:2103.08612.

---

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# Development setup
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Format code
black lagc/
isort lagc/

---

📄 License

MIT License - see LICENSE for details.

---

LAGC v1.0.0
Accelerating Photonic Quantum Computing Research

⭐ Star us on GitHub if LAGC helps your research!