Developing the openqasm3 to QIR visitor

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,3 +1,3 @@
-*issue tag(s), if exist*:
+<!-- Please link or tag any issues that is PR closes -->
 
 ## Changes

.github/workflows/docs.yml

@@ -20,7 +20,6 @@ jobs:
       run: |
         python3 -m pip install --upgrade pip
         python3 -m pip install -r docs/requirements.txt
-        python3 -m pip install -r requirements.txt
         python3 -m pip install -e .
     - name: Build docs
       run: |

CITATION.cff

@@ -15,6 +15,9 @@ authors:
   - given-names: Priyansh
     family-names: Parakh
     affiliation: University of Toronto
+  - given-names: Harshit
+    family-names: Gupta
+    affiliation: VISA Inc.
   - given-names: Ryan James
     family-names: Hill
     affiliation: qBraid Co.

README.md

@@ -34,16 +34,32 @@ qBraid-SDK extension providing support for QIR conversions.
 
 This project aims to make [QIR](https://www.qir-alliance.org/) representations accessible via the qBraid-SDK [transpiler](#architecture-diagram), and by doing so, open the door to language-specific conversions from any and all high-level quantum languages [supported](https://docs.qbraid.com/en/latest/sdk/overview.html#supported-frontends) by `qbraid`. See QIR Alliance: [why do we need it?](https://www.qir-alliance.org/qir-book/concepts/why-do-we-need.html).
 
-## Getting started
-
-### Installation
+## Installation
 
 qBraid-QIR requires Python 3.8 or greater, and can be installed with pip as follows:
 
 ```shell
 pip install qbraid-qir
 ```
 
+### Optional dependencies
+
+qBraid-QIR offers integrations that require extra (optional) dependencies, which can be installed as follows:
+
+For Cirq to QIR conversions, install the `cirq` extra:
+
+```shell
+pip install 'qbraid-qir[cirq]'
+```
+
+For OpenQASM 3 to QIR conversions, install the `qasm3` extra:
+
+```shell
+pip install 'qbraid-qir[qasm3]'
+```
+
+### Install from source
+
 You can also install from source by cloning this repository and running a pip install command
 in the root directory of the repository:
 
@@ -53,7 +69,13 @@ cd qbraid-qir
 pip install .
 ```
 
-### Check version
+To include optional dependencies when installing from source, use the same "extras_require" format, e.g.
+
+```shell
+pip install '.[cirq,qasm3]'
+```
+
+## Check version
 
 You can view the version of qbraid-qir you have installed within a Python shell as follows:
 
@@ -63,18 +85,20 @@ In [1]: import qbraid_qir
 In [2]: qbraid_qir.__version__
 ```
 
-### Resources
+## Resources
 
 - [User Guide](https://docs.qbraid.com/projects/qir/)
 - [API Reference](https://docs.qbraid.com/projects/qir/en/latest/api/qbraid_qir.html)
 - [Example Notebooks](examples)
 - [Test Containers](test-containers)
 
-### Usage Example
+## Usage examples
+
+### Cirq conversions
 
 ```python
 import cirq
-from qbraid_qir import cirq_to_qir
+from qbraid_qir.cirq import cirq_to_qir
 
 q0, q1 = cirq.LineQubit.range(2)
 
@@ -89,6 +113,30 @@ module = cirq_to_qir(circuit, name="my-circuit")
 ir = str(module)
 ```
 
+### OpenQASM 3 conversions
+
+```python
+from qbraid_qir.qasm3 import qasm3_to_qir
+
+program = """
+OPENQASM 3;
+include "stdgates.inc";
+
+qubit[2] q;
+bit[2] c;
+
+h q[0];
+cx q[0], q[1];
+
+measure q[0] -> c[0];
+measure q[1] -> c[1];
+"""
+
+module = qasm3_to_qir(program, name="my-program")
+
+ir = str(module)
+```
+
 ### Add QIR node to qBraid conversion graph
 
 ```python
@@ -131,12 +179,12 @@ citation details, please refer to [CITATION.cff](CITATION.cff).
 
 ```tex
 @software{Kushnir_qBraid-QIR_Python_package_2024,
-author = {Kushnir, Samuel and Jain, Rohan and Parakh, Priyansh and Hill, Ryan James},
+author = {Kushnir, Samuel and Gupta, Harshit and Jain, Rohan and Parakh, Priyansh and Hill, Ryan James},
 license = {GPL-3.0},
-month = jan,
-title = {{qBraid-QIR: Python package for generating QIR programs from Cirq.}},
+month = mar,
+title = {{qBraid-QIR: Python package for QIR conversions, integrations, and utilities.}},
 url = {https://github.com/qBraid/qbraid-qir},
-version = {0.1.0},
+version = {0.2.0},
 year = {2024}
 }
 ```

docs/api/qbraid_qir.qasm3.rst

@@ -0,0 +1,9 @@
+:orphan:
+
+qbraid_qir.qasm3
+=================
+
+.. automodule:: qbraid_qir.qasm3
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -46,12 +46,10 @@
 # set_type_checking_flag = True
 autodoc_member_order = "bysource"
 autoclass_content = "both"
-autodoc_mock_imports = ["cirq"]
+autodoc_mock_imports = ["cirq", "openqasm3"]
 napoleon_numpy_docstring = False
 todo_include_todos = True
-mathjax_path = (
-    "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
-)
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
 # The master toctree document.
 master_doc = "index"

docs/index.rst

@@ -165,6 +165,8 @@ This project was conceived in cooperation with the Quantum Open Source Foundatio
    :hidden:
 
    userguide/cirq_qir
+   userguide/qasm3_qir
+   userguide/qasm3_supported
 
 .. toctree::
    :maxdepth: 1
@@ -173,6 +175,7 @@ This project was conceived in cooperation with the Quantum Open Source Foundatio
 
    api/qbraid_qir
    api/qbraid_qir.cirq
+   api/qbraid_qir.qasm3
 
 
 Indices and Tables

docs/userguide/qasm3_qir.rst

@@ -0,0 +1,75 @@
+.. _sdk_qir_qasm3:
+
+QASM conversions
+==================
+
+Example Usage
+--------------
+
+Convert an ``OpenQASM 3`` program to ``QIR`` code:
+
+.. code-block:: python
+
+   from qbraid_qir import dumps
+   from qbraid_qir.qasm3 import qasm3_to_qir
+
+   # create a test program
+   program = """
+   OPENQASM 3;
+   include "stdgates.inc";
+   qubit[2] q;
+   h q[0];
+   cx q[0], q[1];
+   measure q[0] -> c[0];
+   measure q[1] -> c[1];
+   """
+
+   # convert to QIR
+   module = qasm3_to_qir(program, name="bell")
+
+   # saves to .ll and .bc files in working directory
+   dumps(module)
+
+   print(module)
+
+.. code-block:: none
+
+   ; ModuleID = 'bell'
+   source_filename = "bell"
+
+   %Qubit = type opaque
+   %Result = type opaque
+
+   define void @main() #0 {
+   entry:
+     call void @__quantum__qis__h__body(%Qubit* inttoptr (i64 0 to %Qubit*))  # Corrected %Qubit* null to inttoptr (i64 0 to %Qubit*)
+     call void @__quantum__qis__cnot__body(%Qubit* inttoptr (i64 0 to %Qubit*), %Qubit* inttoptr (i64 1 to %Qubit*))  # Corrected %Qubit* null and added correct inttoptr conversion
+     call void @__quantum__qis__mz__body(%Qubit* inttoptr (i64 0 to %Qubit*), %Result* inttoptr (i64 0 to %Result*))  # Corrected %Qubit* and %Result* null to correct inttoptr conversion
+     call void @__quantum__qis__mz__body(%Qubit* inttoptr (i64 1 to %Qubit*), %Result* inttoptr (i64 1 to %Result*))  # Added correct inttoptr conversion
+     ret void
+   }
+
+   declare void @__quantum__qis__h__body(%Qubit*)
+   declare void @__quantum__qis__cnot__body(%Qubit*, %Qubit*)
+   declare void @__quantum__qis__mz__body(%Qubit*, %Result* writeonly) #1
+
+   attributes #0 = { "entry_point" "output_labeling_schema" "qir_profiles"="custom" "required_num_qubits"="2" "required_num_results"="2" }
+   attributes #1 = { "irreversible" }
+
+   !llvm.module.flags = !{!0, !1, !2, !3}
+   !0 = !{i32 1, !"qir_major_version", i32 1}
+   !1 = !{i32 7, !"qir_minor_version", i32 0}
+   !2 = !{i32 1, !"dynamic_qubit_management", i1 false}
+   !3 = !{i32 1, !"dynamic_result_management", i1 false}
+
+
+Execute the QIR program using the `qir-runner <https://github.com/qir-alliance/qir-runner>`_ command line tool:
+
+.. code-block:: bash
+
+   $ qir-runner -f bell.bc
+
+
+.. seealso::
+
+   https://github.com/qBraid/qbraid-qir/tree/main/test-containers