{"id":13751196,"url":"https://github.com/Pitt-JonesLab/mirror-gates","last_synced_at":"2025-05-09T18:31:06.273Z","repository":{"id":186788744,"uuid":"630172381","full_name":"Pitt-JonesLab/mirror-gates","owner":"Pitt-JonesLab","description":"mirror-decomposition integrated routing for algorithm gate efficiency","archived":false,"fork":false,"pushed_at":"2023-11-26T22:49:49.000Z","size":68358,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-03T09:02:05.673Z","etag":null,"topics":["qiskit","quantum-computing","quantum-gates","transpilation"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Pitt-JonesLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-04-19T20:26:32.000Z","updated_at":"2024-04-21T12:55:47.000Z","dependencies_parsed_at":"2023-11-26T23:33:30.749Z","dependency_job_id":null,"html_url":"https://github.com/Pitt-JonesLab/mirror-gates","commit_stats":null,"previous_names":["pitt-joneslab/mirror-gates"],"tags_count":4,"template":false,"template_full_name":"evmckinney9/python-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pitt-JonesLab%2Fmirror-gates","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pitt-JonesLab%2Fmirror-gates/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pitt-JonesLab%2Fmirror-gates/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Pitt-JonesLab%2Fmirror-gates/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Pitt-JonesLab","download_url":"https://codeload.github.com/Pitt-JonesLab/mirror-gates/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224876989,"owners_count":17384699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["qiskit","quantum-computing","quantum-gates","transpilation"],"created_at":"2024-08-03T09:00:38.877Z","updated_at":"2024-11-16T04:30:39.142Z","avatar_url":"https://github.com/Pitt-JonesLab.png","language":"Jupyter Notebook","funding_links":[],"categories":["Community"],"sub_categories":[],"readme":"# MIRAGE\r\n\r\n[Quantum Circuit Decomposition and Routing Collaborative Design using Mirror Gates](https://arxiv.org/abs/2308.03874)\r\n\r\n[![ecosystem](https://img.shields.io/badge/Qiskit-Ecosystem-blueviolet)](https://github.com/qiskit-community/ecosystem)\r\n![Tests](https://github.com/Pitt-JonesLab/mirror-gates/actions/workflows/tests.yml/badge.svg?branch=main)\r\n![Format Check](https://github.com/Pitt-JonesLab/mirror-gates/actions/workflows/format-check.yml/badge.svg?branch=main)\r\n[![DOI](https://zenodo.org/badge/630172381.svg)](https://zenodo.org/doi/10.5281/zenodo.10208066)\r\n\u003ca href=\"https://colab.research.google.com/github/Pitt-JonesLab/mirror-gates/blob/main/mirage_demo.ipynb\" target=\"_parent\"\u003e\u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/\u003e\u003c/a\u003e\r\n\r\n## 📌 Project Overview\r\n\r\n- **Objective**: Optimize quantum transpilation by unifying the layout and routing stages with gate decomposition.\r\n- **Strategy**: Employ the mirror gate of $\\texttt{U}$, represented as $\\texttt{U} \\cdot \\texttt{SWAP}$, to achieve more cost-efficient routing without altering decomposition costs. In certain cases, it can even reduce decomposition expenses.\r\n\r\n## 🌟 Key Features\r\n\r\n- **Mirage Algorithm**: Defined in `src/mirror_gates/mirage.py`\r\n\r\n![image](https://github.com/Pitt-JonesLab/mirror-gates/assets/47376937/08408089-561a-4799-9904-a2637d829edd)\r\n\r\n## 📊 Results \u0026 Comparisons\r\n\r\n- **Experiments**: Detailed in `src/notebooks/results`\r\n- **Findings**: Our methodology considerably reduces circuit depth and swap count when compared with conventional techniques across multiple topologies.\r\n\r\n![image](https://github.com/Pitt-JonesLab/mirror-gates/assets/47376937/81653cab-24c1-4170-ac5a-438c94d2bab3)\r\n\r\n## 🚀 Getting Started\r\n\r\nTo use as a standalone [transpiler plugin](https://qiskit.org/documentation/apidoc/transpiler_plugins.html), install using\r\n\r\n```\r\npip install -e git+https://github.com/Pitt-JonesLab/mirror-gates#egg=mirror-gates[core]\r\n```\r\n\r\nThen get started by exploring the main demo located at `src/mirror_gates/notebooks/bench.ipynb`.\r\n\r\n### 💻🐒 Usage\r\n\r\n```python\r\nfrom qiskit.transpiler import CouplingMap\r\ncoupling_map = CouplingMap.from_grid(6, 6)\r\n```\r\n\r\n#### 1. Use as a Qiskit-Plugin\r\n\r\nIntegrate MIRAGE into your existing transpilation pipeline:\r\n\r\n```python\r\nfrom qiskit import transpile\r\nmirage_qc = transpile(\r\n              qc, # input circuit\r\n              optimization_level = 3, # default: Qiskit's highest level\r\n              coupling_map=coupling_map,\r\n              basis_gates= [\"u\", \"xx_plus_yy\", \"id\"],\r\n              routing_method=\"mirage\",\r\n              layout_method=\"sabre_layout_v2\",\r\n)\r\n```\r\n\r\n#### 2. Use Mirage as a complete pass manager.\r\n\r\nHandles all pre-, post-processing stages described in our paper:\r\n\r\n```python\r\nfrom mirror_gates.pass_managers import Mirage\r\nmirage = Mirage(\r\n            coupling_map, # coupling map\r\n            name=\"Mirage-$\\sqrt{\\texttt{iSWAP}}$\", # transpile_benchy and figure labels)\r\n            parallel=True, # run trials in parallel or serial\r\n            cx_basis=False, # turning on sets CNOT as the basis gate,\r\n            # (can take arbitrary basis but parameters are not configured that way yet)\r\n            cost_function=\"depth\", # switch to \"basic\" for counting SWAPs\r\n            fixed_aggression=None, # force aggression level on all iterations\r\n            layout_trials=None, # how many independent layout trials to run (20)\r\n            fb_iters=None, # how many forward-backward iterations to run (4)\r\n            swap_trials=None, # how many independent routing trials to run (20)\r\n            no_vf2=False, # keep False to use VF2 for finding complete layouts\r\n            logger=None, # from logging moduel\r\n)\r\nmirage_qc = mirage.run(circuit=qc)\r\n```\r\n\r\n[!WARNING]\r\n[!WARNING]\r\nIn the current version of Qiskit, there's no direct support for \\( \\sqrt{iSWAP} \\) as a basis gate. As a workaround, I've been using `XX+YY`, which provides a partial solution but isn't fully optimized.\r\n\r\nHowever, there's an ongoing [pull request](https://github.com/Qiskit/qiskit-terra/pull/9375) in Qiskit that introduces a new gate, `SiSwapGate`, which represents \\( \\sqrt{iSWAP} \\). This PR also brings in optimized decomposition methods for the gate. I've previously [implemented a similar logic](https://github.com/Pitt-JonesLab/slam_decomposition/blob/main/src/slam/utils/transpiler_pass/weyl_decompose.py), but the PR suggests there might have been some inaccuracies in the paper I referenced.\r\n\r\nTo benefit from the advancements in the PR, I'm temporarily using a [fork of the PR](https://github.com/evmckinney9/qiskit-evmckinney9/tree/sqisw-gate) in this project. By leveraging the fork, when you use the `SiSwapGate`, you'll notice a more efficient decomposition compared to the `XX+YY` workaround.\r\n\r\nPlease note that this is a provisional solution. I'll transition back to the main Qiskit repository once the PR is merged and the `SiSwapGate` with its decomposition methods becomes officially available.\r\n\r\n### 📋 Prerequisites\r\n\r\n- **Monodromy Dependency**: This needs lrs. To install:\r\n\r\n  - `sudo apt install lrslib`\r\n\r\n- **Package Dependencies**: By default, two other packages are dependencies:\r\n\r\n  - [transpile_benchy](https://github.com/evmckinney9/transpile_benchy): Manages circuit benchmarks, data analytics, and plotting.\r\n  - [monodromy (fork)](https://github.com/evmckinney9/monodromy): modified for Qiskit AnalysisPass integration.\r\n\r\n- ⚠️ **Setup**: Running `make init` sets up the required environment and tools. It also clones required repositories.\r\n  - **Optional**: If you want to leverage the additional features from transpile_benchy, especially its submodules for circuit benchmarking, run `make dev-init`. This will clone and set up transpile_benchy with its complete functionalities.\r\n\r\n### Dive Deeper into the Code 💻🐒\r\n\r\n- **Please report any issues**. (Currently the most unstable part is related to the parallel processing. 😺)\r\n- The main logic of the MIRAGE pass is in `src/mirror_gates/mirage.py` which includes `ParallelMirage`, and the class `Mirage`, a subclass of `qiskit.transpiler.passes.SabreSwap` to handle serial passes.\r\n- The main pass manager is defined in `src/mirror_gates/pass_managers.py`.\r\n- Circuit benchmarks are defined as `.txt` files in `src/mirror_gates/circuits/`. These are loaded into a `transpile_benchy.Library` object.\r\n- For more details, see code documentation or contact me.\r\n\r\nAdditional utility commands available in the Makefile:\r\n\r\n- **make format**: Formats the codebase.\r\n- **make clean**: Cleans up temporary and unnecessary files.\r\n- **make test**: Runs tests to ensure code functionality.\r\n- For more information about the repository structure, visit my [python-template](https://github.com/evmckinney9/python-template).\r\n\r\n## 📚 Reference\r\n\r\n```bibtex\r\n@article{McKinney_MIRAGE_Quantum_Circuit_2023,\r\n    author = {McKinney, Evan and Hatridge, Michael and Jones, Alex K},\r\n    doi = {10.48550/arXiv.2308.03874},\r\n    journal = {arXiv preprint arXiv:2308.03874},\r\n    title = {{MIRAGE: Quantum Circuit Decomposition and Routing Collaborative Design using Mirror Gates}},\r\n    year = {2023}\r\n}\r\n```\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPitt-JonesLab%2Fmirror-gates","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPitt-JonesLab%2Fmirror-gates","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPitt-JonesLab%2Fmirror-gates/lists"}