{"id":21375261,"url":"https://github.com/qbraid/pyqasm","last_synced_at":"2025-07-13T09:32:41.910Z","repository":{"id":257829457,"uuid":"867738914","full_name":"qBraid/pyqasm","owner":"qBraid","description":"Python toolkit providing OpenQASM 3 semantic analyzer and utilities for program analysis and compilation.","archived":false,"fork":false,"pushed_at":"2025-07-03T07:32:28.000Z","size":728,"stargazers_count":16,"open_issues_count":44,"forks_count":18,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-03T08:36:06.458Z","etag":null,"topics":["openqasm","quantum-computing"],"latest_commit_sha":null,"homepage":"https://docs.qbraid.com/pyqasm","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/qBraid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-10-04T16:15:04.000Z","updated_at":"2025-07-03T07:32:34.000Z","dependencies_parsed_at":"2025-05-01T09:19:41.511Z","dependency_job_id":"b006b796-11d6-443d-a250-9d608a4fb257","html_url":"https://github.com/qBraid/pyqasm","commit_stats":null,"previous_names":["qbraid/pyqasm"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/qBraid/pyqasm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qBraid%2Fpyqasm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qBraid%2Fpyqasm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qBraid%2Fpyqasm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qBraid%2Fpyqasm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/qBraid","download_url":"https://codeload.github.com/qBraid/pyqasm/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/qBraid%2Fpyqasm/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265120260,"owners_count":23714490,"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":["openqasm","quantum-computing"],"created_at":"2024-11-22T09:09:31.952Z","updated_at":"2025-07-13T09:32:41.904Z","avatar_url":"https://github.com/qBraid.png","language":"Python","readme":"# pyqasm\n\n\u003cimg align=\"right\" width=\"100\" src=\"https://qbraid-static.s3.amazonaws.com/pyqasm.svg\"/\u003e\n\n[![CI](https://github.com/qBraid/pyqasm/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/qBraid/pyqasm/actions/workflows/main.yml)\n[![codecov](https://codecov.io/gh/qBraid/pyqasm/graph/badge.svg?token=92YURMR8T8)](https://codecov.io/gh/qBraid/pyqasm)\n[![GitHub Pages](https://img.shields.io/github/actions/workflow/status/qBraid/pyqasm/gh-pages.yml?label=docs)](https://sdk.qbraid.com/pyqasm/)\n[![PyPI version](https://img.shields.io/pypi/v/pyqasm.svg?color=blue)](https://pypi.org/project/pyqasm/)\n[![PyPI Downloads](https://static.pepy.tech/badge/pyqasm)](https://pepy.tech/projects/pyqasm)\n[![Python verions](https://img.shields.io/pypi/pyversions/pyqasm.svg?color=blue)](https://pypi.org/project/pyqasm/)\n[![License](https://img.shields.io/github/license/qBraid/pyqasm.svg?color=purple)](https://www.apache.org/licenses/LICENSE-2.0)\n\nPython toolkit providing an OpenQASM 3 semantic analyzer and utilities for program analysis and compilation.\n\n[![Env Badge](https://img.shields.io/endpoint?url=https://api.qbraid.com/api/environments/valid?envSlug=pyqasm_l9qauu\u0026label=Launch+on+qBraid\u0026labelColor=lightgrey\u0026logo=rocket\u0026logoSize=auto\u0026style=for-the-badge)](http://account.qbraid.com?gitHubUrl=https://github.com/qBraid/pyqasm.git\u0026envId=pyqasm_l9qauu)\n\n## Motivation\n[OpenQASM](https://openqasm.com/) is a powerful language for expressing hybrid quantum-classical programs, but it lacks a comprehensive tool supporting the _full capabilities of the language_. PyQASM aims to fill this gap by building upon the [`openqasm3.parser`](https://github.com/openqasm/openqasm/blob/ast-py/v1.0.1/source/openqasm/openqasm3/parser.py), and providing support for semantic analysis and utilities for program compilation.\n\n## Installation\n\nPyQASM requires Python 3.10 or greater, and can be installed with pip as follows:\n\n```bash\npip install pyqasm\n```\n\n### Optional Dependencies\nPyQASM offers optional extras such as - \n1. `cli` : command-line interface (CLI) functionality\n2. `visualization`: for program visualization \n3. `pulse` : pulse/calibration features (in progress)\n\nTo install these features along with the core package, you can use the following command:\n```bash\npip install 'pyqasm[cli,pulse,visualization]'\n```\n\nYou can also install them individually. For example, to install the CLI features only, you can run:\n```bash\npip install 'pyqasm[cli]'      \n```\n\n\n### Install from source \n\nYou can also install from source by cloning this repository and running a pip install command\nin the root directory of the repository:\n\n```bash\ngit clone https://github.com/qBraid/pyqasm.git\ncd pyqasm\npip install .\n```\n\n## Check version\n\nYou can view the version of pyqasm you have installed within a Python shell as follows:\n\n```python\n\u003e\u003e\u003e import pyqasm\n\u003e\u003e\u003e pyqasm.__version__\n```\n\n## Key Features: Unroll \u0026 Validate OpenQASM 3 Programs\n\nPyQASM offers robust support for the **extensive grammar of OpenQASM 3**, including custom gates, subroutines, loops, conditionals, classical control, and more. Its core utilities allow you to **validate** programs for semantic correctness and **unroll** (flatten) all high-level constructs into a linear sequence of basic quantum operations, ready for execution or further compilation.\n\n### Highlights\n\n- **[Comprehensive Grammar Support](src/README.md)**: PyQASM supports the full breadth of OpenQASM 3 operations, and backward compatibility with OpenQASM 2, including:\n  - Classical and quantum registers\n  - Loops (`for`, `while`)\n  - Conditionals (`if`, `else`)\n  - Parameterized and custom gates\n  - Subroutine inlining\n  - Switch statements\n  - Classical expressions and assignments\n  - Variables and arrays\n  - Type casting and conversions\n  - Built-in and user-defined constants\n  - Quantum-classical interaction (`measurement`, `reset`, etc.)\n  - Inclusion of standard libraries (`stdgates.inc`, etc.)\n\n- **[Unrolling](https://docs.qbraid.com/pyqasm/user-guide/examples#inlining-%26-unrolling):**  \n  Expands all custom gates, loops, subroutines, branches, etc. into a flat, hardware-ready sequence of instructions.\n\n- **[Validation](https://docs.qbraid.com/pyqasm/user-guide/overview#the-qasmmodule-object):**  \n  Performs semantic analysis to ensure programs are correct and conform to the OpenQASM 3 specification.\n\n---\n\n### Example: Unroll and Validate a Complex QASM Program\n\nBelow is an example demonstrating PyQASM's efficacy on a non-trivial OpenQASM 3 program. This program uses custom gates, loops, and classical control, and is fully unrolled and validated by PyQASM:\n\n```python\nfrom pyqasm import loads, dumps\n\nqasm = \"\"\"\nOPENQASM 3;\ninclude \"stdgates.inc\";\n\ngate h2 a, b { h a; h b; }\ndef parity_flip(qubit[4] q) {\n    for int i in [0:3] {\n        if (i % 2 == 0) {\n            x q[i];\n        }\n    }\n}\n\nqubit[4] q;\nbit[4] c;\n\nh2 q[0], q[1];\nparity_flip(q);\n\nfor int i in [0:3] {\n    measure q[i] -\u003e c[i];\n}\n\"\"\"\n\nmodule = loads(qasm)      # Parse and build the program\nmodule.validate()         # Check for semantic errors\nmodule.unroll()           # Flatten all gates, loops, and subroutines\n\nprint(dumps(module))      # Output the fully unrolled QASM\n```\n\n**Output (fully unrolled QASM):**\n```qasm\nOPENQASM 3.0;\ninclude \"stdgates.inc\";\nqubit[4] q;\nbit[4] c;\nh q[0];\nh q[1];\nx q[0];\nx q[2];\nc[0] = measure q[0];\nc[1] = measure q[1];\nc[2] = measure q[2];\nc[3] = measure q[3];\n```\n\nPyQASM ensures your OpenQASM programs are **semantically correct** and **hardware-ready**, supporting the language's most advanced features with ease.\n## Resources\n\n- [API Reference](https://qbraid.github.io/pyqasm/api/pyqasm.html): Developer documentation.\n- [Usage Examples](examples): Scripts and Markdown examples demonstrating core functionality.\n- [Supported Operations](pyqasm/README.md#supported-operations): OpenQASM language features supported, in progress, and planned for future support.\n\n## Contributing\n\n[![GitHub](https://img.shields.io/badge/issue_tracking-github-black?logo=github)](https://github.com/qBraid/pyqasm/issues)\n[![QCSE](https://img.shields.io/badge/QCSE-pyqasm-orange?logo=stackexchange)](https://quantumcomputing.stackexchange.com/questions/tagged/pyqasm)\n[![Discord](https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord\u0026logoColor=white)](https://discord.gg/TPBU2sa8Et)\n\n- Interested in contributing code, or making a PR? See\n  [CONTRIBUTING.md](CONTRIBUTING.md)\n- For feature requests and bug reports:\n  [Submit an issue](https://github.com/qBraid/pyqasm/issues)\n- For discussions, and specific questions about pyqasm, or\n  other topics, [join our discord community](https://discord.gg/TPBU2sa8Et)\n- For questions that are more suited for a forum, post to\n  [QCSE](https://quantumcomputing.stackexchange.com/)\n  with the [`pyqasm`](https://quantumcomputing.stackexchange.com/questions/tagged/pyqasm) tag.\n- By participating, you are expected to uphold our [code of conduct](CODE_OF_CONDUCT).\n\n## License\n\n[Apache-2.0 License](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbraid%2Fpyqasm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fqbraid%2Fpyqasm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fqbraid%2Fpyqasm/lists"}