⚛️ quant-gameth
Quantum-Game Theory Framework
Solve combinatorial optimization & game theory problems with quantum-inspired algorithms
🏗️ Architecture
┌─────────────────────────────────────────────────────────────────────────┐
│ quant-gameth Framework │
├──────────────────────┬────────────────────────┬─────────────────────────┤
│ ⚛️ QUANTUM ENGINE │ 🎯 GAME THEORY ENGINE │ 🔗 PROBLEM ENCODERS │
│ │ │ │
│ state.py │ normal_form.py │ qubo.py │
│ gates.py │ extensive_form.py │ constraints.py │
│ circuit.py │ minimax.py │ game_bridge.py │
│ measurement.py │ evolutionary.py │ strategy_mapper.py │
│ grover.py │ mechanism.py │ │
│ qaoa.py │ quantum_games.py │ │
│ vqe.py │ repeated.py │ │
│ annealing.py │ cooperative.py │ │
│ ansatz.py │ │ │
│ tensor_network.py │ │ │
├──────────────────────┴────────────────────────┴─────────────────────────┤
│ 🧩 APPLICATION SOLVERS │
│ sudoku · graph_coloring · maxcut · nqueens · knapsack · tsp │
│ portfolio │
├──────────────────────┬────────────────────────┬─────────────────────────┤
│ 📊 DATA GENERATORS │ 📈 VISUALIZATION │ ⏱️ METRICS & BENCH │
│ puzzles.py │ quantum_viz.py │ performance.py │
│ graphs.py │ game_viz.py │ benchmark.py │
│ games_gen.py │ solver_viz.py │ │
│ market.py │ │ │
├──────────────────────┴────────────────────────┴─────────────────────────┤
│ ⚙️ INFRASTRUCTURE │
│ backends/ (classical · gpu · hybrid) │
│ utils/ (serialization · decomposition) │
│ _types.py (core dataclasses & enums) │
└─────────────────────────────────────────────────────────────────────────┘
✨ Key Features
🚀 Installation
# Clone the repository
git clone https://github.com/Ronit26Mehta/quant-gameth.git
cd quant-gameth
# Install in editable mode
pip install -e .
# (Optional) GPU acceleration
pip install cupy-cuda12x
Requirements
| Package | Minimum Version |
|---|---|
| Python | ≥ 3.9 |
| NumPy | ≥ 1.21 |
| SciPy | ≥ 1.7 |
| Matplotlib | ≥ 3.5 |
| NetworkX | ≥ 2.6 |
📖 Quick Start
1. Quantum Circuit — Bell State
from quant_gameth.quantum.circuit import QuantumCircuit, Simulator
from quant_gameth.quantum.measurement import sample_counts
qc = QuantumCircuit(2)
qc.h(0).cx(0, 1) # Hadamard + CNOT → Bell state |Φ+⟩
sv = Simulator().run(qc)
counts = sample_counts(sv, n_shots=1024)
print(counts) # {'00': ~512, '11': ~512}
2. Nash Equilibrium — Prisoner's Dilemma
from quant_gameth.games.normal_form import NormalFormGame
game = NormalFormGame.prisoners_dilemma()
equilibria = game.find_nash()
for eq in equilibria:
print(f"Strategies: {eq.strategies}")
print(f"Payoffs: {eq.payoffs}")
3. MaxCut with QAOA
import numpy as np
from quant_gameth.solvers.maxcut import solve_maxcut
adj = np.array([[0,1,1],[1,0,1],[1,1,0]], dtype=float)
result = solve_maxcut(adj, method="qaoa", qaoa_depth=3)
print(f"Cut value: {result.metadata['cut_value']}")
print(f"Partition: {result.solution}")
4. Portfolio Optimization
from quant_gameth.generators.market import generate_portfolio_data
from quant_gameth.solvers.portfolio import solve_portfolio
mu, sigma = generate_portfolio_data(n_assets=10, seed=42)
result = solve_portfolio(mu, sigma, risk_aversion=1.0, method="markowitz")
print(f"Optimal weights: {result.solution.round(4)}")
print(f"Sharpe ratio: {result.metadata['sharpe_ratio']:.4f}")
5. Sudoku Solver
from quant_gameth.generators.puzzles import generate_sudoku
from quant_gameth.solvers.sudoku import solve_sudoku
board = generate_sudoku(difficulty="hard", seed=42)
result = solve_sudoku(board, method="backtracking")
print(result.solution.reshape(9, 9))
🎮 Demo Scripts
Run any demo directly:
python -m quant_gameth.examples.demo_quantum
python -m quant_gameth.examples.demo_games
python -m quant_gameth.examples.demo_sudoku
python -m quant_gameth.examples.demo_maxcut
python -m quant_gameth.examples.demo_portfolio
python -m quant_gameth.examples.demo_trading
python -m quant_gameth.examples.demo_tournament
| Script | What It Demonstrates |
|---|---|
demo_quantum |
States, Bell state, Grover's search, QAOA, VQE |
demo_games |
Nash equilibria, backward induction, evolutionary dynamics, Shapley values |
demo_sudoku |
Puzzle generation (easy/medium/hard) + solving |
demo_maxcut |
Brute-force vs QAOA vs SA with approximation ratios |
demo_portfolio |
Markowitz, discrete selection, efficient frontier |
demo_trading |
First-price, Vickrey, VCG, English auctions |
demo_tournament |
Iterated PD round-robin + evolutionary dynamics |
📊 Benchmarking
from quant_gameth.metrics.benchmark import BenchmarkSuite, BenchmarkConfig
suite = BenchmarkSuite()
suite.register_builtin("maxcut")
results = suite.run(BenchmarkConfig(
problem_name="maxcut",
sizes=[6, 8, 10, 12],
methods=["qaoa", "annealing", "brute_force"],
n_repeats=5,
))
suite.export_json(results, "benchmark_results.json")
suite.export_csv(results, "benchmark_results.csv")
Expected Performance
| Problem | Size | Classical Baseline | Framework | Speedup |
|---|---|---|---|---|
| MaxCut (dense) | 100 nodes | ~10s | ~5s | 2× |
| Sudoku (hard) | 729 variables | ~60s | ~30s | 2× |
| Portfolio | 50 assets | ~1s | ~0.5s | 2× |
| 2-player game | 10×10 | ~0.1s | ~0.05s | 2× |
🔬 Novel Contributions
| # | Innovation | Description |
|---|---|---|
| 1 | Quantum-Game Bridge | Auto-transpile any normal-form game → QUBO or quantum circuit |
| 2 | EWL Quantum Games | Full EWL protocol with demonstrated quantum advantage over classical Nash |
| 3 | Hybrid Quantum-Evolutionary | Combine replicator dynamics with quantum annealing for equilibrium discovery |
| 4 | Game-Theoretic QAOA | QAOA warm-start from game best-response strategies |
| 5 | Multi-Agent Tournament | Tournament system with evolving quantum strategies across generations |
📁 Project Structure
quant-gameth/
├── pyproject.toml # Build config & dependencies
├── LICENSE # MIT License
├── README.md # This file
├── quant_gameth/
│ ├── __init__.py
│ ├── _types.py # Core dataclasses & enums
│ ├── quantum/ # Quantum simulation engine (11 modules)
│ ├── games/ # Game theory engine (8 modules)
│ ├── encoders/ # Problem encoders (4 modules)
│ ├── solvers/ # Application solvers (7 modules)
│ ├── generators/ # Data generators (4 modules)
│ ├── viz/ # Visualization (3 modules)
│ ├── metrics/ # Performance & benchmarking (2 modules)
│ ├── backends/ # Execution backends (4 modules)
│ ├── utils/ # Utilities (2 modules)
│ └── examples/ # Runnable demos (7 scripts)
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License — see the LICENSE file for details.
Made with ❤️ for quantum computing and game theory research
⭐ Star this repo if you find it useful!
Metadata
Release files for quant-gameth 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| quant_gameth-0.1.0.tar.gz | 93.1 kB | Without provenance | Details for quant_gameth-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| quant_gameth-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for quant_gameth-0.1.0-py3-none-any.whl |
Total release size: 211.7 kB
Release files / quant_gameth-0.1.0.tar.gz
| Download URL | quant_gameth-0.1.0.tar.gz |
|---|---|
| Size | 93.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e79f0aebd592d440837ab1e8222188551d056abce4259adac734cb2305625dc
|
|
BLAKE2b-256 checksum How to use checksums |
5eece0a34936cce8537690cd87e2453468e7a57174f95a39084a31201400c183
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Release files / quant_gameth-0.1.0-py3-none-any.whl
| Download URL | quant_gameth-0.1.0-py3-none-any.whl |
|---|---|
| Size | 118.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4fd459a2c877d638045d6bbf1f533b1fb01a9994dd1d790b8bd089173272e49
|
|
BLAKE2b-256 checksum How to use checksums |
a850198b417889ca8eea2f62640ce0add70e9748e8410d087cdec430094a2f15
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.3
|
Security for quant-gameth 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.