{"id":29970513,"url":"https://github.com/touradbaba/thesis-quantum-gnn-learnability","last_synced_at":"2026-04-15T18:01:36.248Z","repository":{"id":304746684,"uuid":"1006106183","full_name":"TouradBaba/thesis-quantum-gnn-learnability","owner":"TouradBaba","description":"This repository hosts code for a thesis on learning full output distributions of quantum circuits using Transformer-based Graph Neural Networks. It includes dataset generation under noiseless and noisy settings, circuit feature engineering, GNN and CNN modeling, transfer learning across qubit sizes, and model evaluation.","archived":false,"fork":false,"pushed_at":"2025-07-24T13:51:51.000Z","size":4198,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-04T07:05:30.542Z","etag":null,"topics":["cnn","deep-learning","distribution-learning","extrapolation","gnn","graph-neural-networks","graph-transformer","machine-learning","multi-output-regression","pytorch","pytorch-geometric","qaoa","qiskit","quantum-circuits","quantum-computing","quantum-machine-learning","quantum-noise","thesis","transfer-learning"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TouradBaba.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-21T14:03:53.000Z","updated_at":"2025-07-26T01:18:09.000Z","dependencies_parsed_at":"2025-07-23T00:07:48.138Z","dependency_job_id":null,"html_url":"https://github.com/TouradBaba/thesis-quantum-gnn-learnability","commit_stats":null,"previous_names":["touradbaba/thesis-quantum-gnn-learnability"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TouradBaba/thesis-quantum-gnn-learnability","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TouradBaba%2Fthesis-quantum-gnn-learnability","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TouradBaba%2Fthesis-quantum-gnn-learnability/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TouradBaba%2Fthesis-quantum-gnn-learnability/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TouradBaba%2Fthesis-quantum-gnn-learnability/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TouradBaba","download_url":"https://codeload.github.com/TouradBaba/thesis-quantum-gnn-learnability/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TouradBaba%2Fthesis-quantum-gnn-learnability/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31853279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cnn","deep-learning","distribution-learning","extrapolation","gnn","graph-neural-networks","graph-transformer","machine-learning","multi-output-regression","pytorch","pytorch-geometric","qaoa","qiskit","quantum-circuits","quantum-computing","quantum-machine-learning","quantum-noise","thesis","transfer-learning"],"created_at":"2025-08-04T05:39:16.475Z","updated_at":"2026-04-15T18:01:36.228Z","avatar_url":"https://github.com/TouradBaba.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evaluating the Learnability of Transformer-Based Graph Neural Networks for the Output Distributions of Quantum Circuits\n\nThis repository provides all code, datasets, trained models, and Jupyter notebooks required reproduce the experiments from a **Bachelor thesis** investigating whether TransformerConv-based Graph Neural Networks (GNNs) can learn to predict the **full output probability distributions** of quantum circuits. The thesis compares GNNs with a CNN baseline on variational and QAOA-style circuits (Class A and B) across 2–5 qubits, under both noiseless and hardware-calibrated noisy conditions, and includes extrapolation tests to 6-qubit circuits.\n\n---\n\n## Setup Instructions\n\n### 1. Install Git LFS\n\nThis repository uses Git Large File Storage (LFS) to store `.pt` files for datasets and models.\n\nInstall Git LFS:\n\n* **Ubuntu/Debian**:\n\n  ```bash\n  sudo apt install git-lfs\n  git lfs install\n  ```\n\n* **macOS**:\n\n  ```bash\n  brew install git-lfs\n  git lfs install\n  ```\n\n* **Windows (Git Bash)**:\n  Download and install Git LFS from [https://git-lfs.github.com/](https://git-lfs.github.com/)\n\n* Then run:\n\n  ```bash\n  git lfs install\n  ```\n\n### 2. Clone the Repository\n\n```bash\ngit clone https://github.com/TouradBaba/thesis-quantum-gnn-learnability.git\ncd thesis-quantum-gnn-learnability\n```\n\nIf Git LFS is installed, all `.pt` files will be fetched automatically.\n\n### 3. Create and Activate Python Environment\n\nPython version used: **3.12.6**\n\n* **macOS/Linux**:\n\n  ```bash\n  python3 -m venv venv\n  source venv/bin/activate\n  ```\n\n* **Windows**:\n\n  ```cmd\n  python -m venv venv\n  venv\\Scripts\\activate\n  ```\n\n### 4. Install Python Dependencies\n\n```bash\npip install -r requirements.txt\n```\n\n\n## Repository Structure\n\n```\n├── datasets/                        # Quantum-circuit graph datasets (.pt)\n│   ├── {2-,3-,4-,5-,6-}qubit/       # Top-level folders by qubit count\n│   │   ├── noiseless/              # Noise-free circuit simulations\n│   │   │   └── class{A,B}/         # Circuit classes A and B\n│   │   │       └── dataset_*.pt\n│   │   └── noisy/                  # Simulations with IBM hardware-calibrated noise\n│   │       ├── class{A,B}/\n│   │       └── dataset_*.pt\n│   │       └── calibration_*.json  # IBM calibration snapshots used to generate noise models\n│\n├── figures/\n│   ├── circuits/                   # Circuit diagrams\n│   ├── gnn/metrics/                # GNN learning curves and metric plots\n│   └── cnn/metrics/                # CNN learning curves and metric plots\n│\n├── models/\n│   ├── gnn_models/                 # Trained GNN checkpoints (2q–5q)\n│   └── cnn_models/                 # Trained CNN checkpoints (2q–5q)\n│\n├── notebooks/                      # End-to-end experiment notebooks\n│   ├── 1_circuits_data_generation.ipynb\n│   ├── 2_data_exploration.ipynb\n│   ├── 3_gnn_modeling.ipynb\n│   ├── 4_cnn_modeling.ipynb\n│   ├── 5_extrapolation_data_gen.ipynb\n│   ├── 6_gnn_extrapolation.ipynb\n│   ├── 7_cnn_extrapolation.ipynb\n│   └── gnn_kl-fid_boxplot_visualization.ipynb\n│\n├── requirements.txt               # Python package dependencies\n├── .gitignore                     # Excludes cache, log, and OS-generated files\n└── .gitattributes                 # Git LFS tracking for .pt files\n\n```\n\n\n## How to Reproduce the Experiments\n\n### A. Dataset Usage\n\nAll datasets used in the experiments (2–6 qubits, noiseless and noisy, Class A and B) are included under `datasets/`.\n\nEach quantum circuit is converted to a **directed acyclic graph (DAG)** where:\n\n* **Nodes** encode gate type, qubit index, gate parameters, position, and Laplacian eigenvectors.\n* **Edges** represent gate execution order (topological flow).\n* **Global features** include circuit-level properties such as depth and entanglement type.\n\nTo regenerate datasets:\n\n* Use `1_circuits_data_generation.ipynb` for 2–5 qubit circuits\n* Use `5_extrapolation_data_gen.ipynb` for 6-qubit circuits\n\n\u003e If generating noisy data, use the existing `calibration_*.json` files located in each `noisy/` folder to ensure consistency with the experiments.\n\n### B. Explore Datasets\n\n```bash\nnotebooks/2_data_exploration.ipynb\n```\n\nPerforms integrity checks and entropy analysis on all datasets (2–6 qubits, Class A/B, noisy and noiseless).\n\n### C. Train GNN Models\n\n```bash\nnotebooks/3_gnn_modeling.ipynb\n```\n\nTrains TransformerConv-based GNNs across 2–5 qubits using transfer learning. Checkpoints are saved in `models/gnn_models/`.\n\n### D. Train CNN Baseline\n\n```bash\nnotebooks/4_cnn_modeling.ipynb\n```\n\nTrains a CNN baseline on the same circuit datasets with matched parameter count. Checkpoints are saved in `models/cnn_models/`.\n\n### E. Extrapolation to 6-Qubit Circuits\n\n1. Generate 6-qubit circuit datasets using:\n\n```bash\nnotebooks/5_extrapolation_data_gen.ipynb\n```\n\n* Same generation process as for 2–5 qubits\n* For noisy data, use the `calibration_*.json` files in `datasets/6qubit/noisy/`\n\n2. Evaluate zero-shot and few-shot extrapolation:\n\n* GNN: `notebooks/6_gnn_extrapolation.ipynb`\n* CNN: `notebooks/7_cnn_extrapolation.ipynb`\n\n\n\n### F. Metric Visualization\n\n```bash\nnotebooks/gnn_kl-fid_boxplot_visualization.ipynb\n```\n\nGenerates boxplots for all test-set evaluation metrics: KL divergence, classical fidelity, MSE, and Wasserstein distance.\nThis notebook should be used instead of `3_gnn_modeling.ipynb` for KL and fidelity boxplots, as the visualizations in that notebook are incorrect due to a bug in the plotting direction. The numerical values printed are accurate, but the metric distribution plots for KL and fidelity should be taken from this notebook.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouradbaba%2Fthesis-quantum-gnn-learnability","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftouradbaba%2Fthesis-quantum-gnn-learnability","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftouradbaba%2Fthesis-quantum-gnn-learnability/lists"}