rasidi3112/quantum-ai-lab

Shor, Grover, BB84, QAOA, VQE, quantum kernels, quantum RL, quantum chaos and more.
Eight modules. Every algorithm is a readable statevector simulation you can step through,
and every headline number below is checked by the test suite.

Quick start · Gallery · Modules · Verified results · Python API · Contributing

Why this repo

• No black boxes. No Qiskit, no PennyLane, no hidden simulator: gates are NumPy arrays, circuits are loops you can read and step through.
• Breadth. Algorithms, cryptography, ML, many-body physics, optimization, reinforcement learning, computer vision and quantum chaos, all behind one consistent API.
• Tested against physics. 100+ tests compare results with exact solutions: the free-fermion Ising energy, the Hubbard dimer, Tsirelson's bound, Trotter error scaling, GOE level statistics and parameter-shift gradients.
• Documented and typed. Every public module, class and function has a NumPy-style docstring with references to the original papers, and the code is fully type-annotated. Ruff and mypy enforce both in CI.
• Fast enough to play with. The whole tour runs in about 3 seconds on a laptop CPU.

Quick start

pip install git+https://github.com/rasidi3112/quantum-ai-lab.git
qailab tour

Then dive into any module:

qailab list                 # all demos
qailab demo crypto          # BB84 vs. an eavesdropper, E91 Bell test, quantum one-time pad
qailab demo optimization    # constraint-preserving QAOA for portfolio selection
qailab demo rl              # a 4-qubit policy learns to balance CartPole

git clone https://github.com/rasidi3112/quantum-ai-lab.git
cd quantum-ai-lab
pip install -e ".[dev]"
ruff check . && mypy        # lint, docstrings and types
pytest                      # ~20 s
python scripts/make_figures.py   # regenerate the README figures
python scripts/make_banner.py    # regenerate the animated banner

Gallery

Every image and animation is produced from the library itself by scripts/make_figures.py, make_banner.py and make_terminal_gif.py.

Grover search: amplitude amplification peaks at ⌊π/4·√N⌋ oracle calls.	Entanglement: simulated singlet correlations follow −cos θ, the source of the CHSH violation in E91.
QAOA landscape: approximation ratio over (γ, β) for MaxCut on 8 nodes.	Quantum phase transition: long-range order of the transverse-field Ising chain melts at h = J.
Quantum RL: a 16-parameter data-re-uploading circuit learns to balance CartPole.	Quantum chaos: the kicked top's Husimi function stays localized when regular and fills the sphere when chaotic. The animated banner is the same simulation, run forward and then time-reversed.

Modules

Verified results

Each row is asserted in tests/, so CI fails if it ever stops being true.

Constraint-preserving QAOA in one table

From qailab demo optimization: choosing 3 of 6 assets (20 valid portfolios out of 64).

Python API

from quantum_algorithms import ShorFactoring, GroverSearch
from quantum_crypto import BB84Protocol, QuantumOTP
from quantum_optimization import QAOA, MaxCutSolver
from quantum_simulation import IsingModel

result = ShorFactoring(seed=1).factor(21)
print(result.factors, result.period_found, result.method)    # (7, 3) 6 quantum period finding

key, stats = BB84Protocol(seed=0).run_protocol(n_qubits=2000, eve_present=True)
print(f"QBER={stats.qber:.1%} secure={stats.protocol_secure}")  # QBER≈25% secure=False

msg = QuantumOTP(seed=0).secure_communicate("Halo dunia, ünïcödé ok", protocol="e91")
print(msg.decrypted_text, msg.success)                        # Halo dunia, ünïcödé ok True

graph = MaxCutSolver.random_graph(8, edge_prob=0.5, seed=1)
print(MaxCutSolver(8).qaoa_solve(graph, p_layers=2, seed=0)["best_cut"])  # 12.0

E0, psi0 = IsingModel(n_sites=8, J=1.0, h=1.0).get_ground_state()
print(f"E0 = {E0:.6f}")                                        # E0 = -10.251662

Constraint-preserving QAOA on any diagonal cost function:

import numpy as np
from quantum_optimization import QAOA

costs = np.random.default_rng(0).normal(size=2**6)           # one cost per bitstring
result = QAOA(6, seed=0).optimize_hamiltonian(
    costs, p_layers=4, mixer="xy", hamming_weight=3, method="L-BFGS-B"
)
samples = QAOA.sample_solution(result["state"], n_samples=1000, seed=0)

Architecture

flowchart TB
    subgraph core["Shared foundation: NumPy statevectors · SciPy linear algebra & optimizers"]
    end
    core --> ALG["quantum_algorithms<br/>Shor · Grover · QFT · QPE · DJ"]
    core --> SIM["quantum_simulation<br/>Ising · Hubbard · Trotter"]
    core --> CHAOS["quantum_chaos<br/>kicked top · level statistics · OTOC"]
    core --> CRYPTO["quantum_crypto<br/>BB84 · E91 · OTP"]
    core --> ML["quantum_ml<br/>kernels · VQC · QNN"]
    core --> OPT["quantum_optimization<br/>QAOA · VQE · MaxCut"]
    core --> RL["quantum_rl<br/>quantum policy · hybrid agent"]
    core --> VIS["quantum_vision<br/>encoders · quanvolution · hybrid classifier"]
    CRYPTO -. keys .-> OTP["quantum one-time pad"]
    SIM -. Hamiltonians .-> OPT
    CLI["qailab CLI"] --> ALG & CRYPTO & ML & CHAOS & SIM & OPT & RL & VIS

Each package is self-contained, so you can read one module without the others. More detail in docs/architecture.md.

Under the hood

Statevector simulation scales as 2ⁿ, so the demos stay at 4–12 qubits. That is the point: small enough to inspect every amplitude.

Roadmap

• Noise models (depolarizing, amplitude damping) and error-mitigation demos
• Optional Qiskit / PennyLane backends to run the same circuits on real hardware
• Interactive notebooks for every module
• Publish to PyPI

Ideas and pull requests are welcome: see the good first issues.

Contributing

Contributions of new algorithms, demos, tests and docs are welcome. Read CONTRIBUTING.md, then run ruff check . && pytest before opening a pull request.

If this project helped you learn or teach quantum computing, consider giving it a star. It helps others find it.

Citation

If you use Quantum AI Lab in research or teaching, please cite it via the CITATION.cff file (GitHub's "Cite this repository" button).

References

1. Nielsen & Chuang, Quantum Computation and Quantum Information (2010).
2. Shor, Polynomial-time algorithms for prime factorization and discrete logarithms, SIAM J. Comput. 26 (1997).
3. Grover, A fast quantum mechanical algorithm for database search, STOC (1996).
4. Bennett & Brassard, Quantum cryptography: public key distribution and coin tossing (1984); Ekert, PRL 67, 661 (1991).
5. Farhi, Goldstone & Gutmann, A quantum approximate optimization algorithm, arXiv:1411.4028 (2014).
6. Hadfield et al., From the quantum approximate optimization algorithm to a quantum alternating operator ansatz, Algorithms 12, 34 (2019).
7. Havlíček et al., Supervised learning with quantum-enhanced feature spaces, Nature 567, 209 (2019).
8. Pérez-Salinas et al., Data re-uploading for a universal quantum classifier, Quantum 4, 226 (2020).
9. Jerbi et al., Parametrized quantum policies for reinforcement learning, NeurIPS (2021).
10. Henderson et al., Quanvolutional neural networks, Quantum Mach. Intell. 2, 2 (2020).
11. Haake, Quantum Signatures of Chaos (2010); Atas et al., PRL 110, 084101 (2013).

License

MIT