Add initial implementation

.github/workflows/format.yml

@@ -0,0 +1,24 @@
+name: Format
+
+on:
+  pull_request:
+      branches: ['main']
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install dependencies
+        run: |
+          python3 -m pip install --upgrade pip
+          python3 -m pip install tox>=4.2.0
+      - name: Check isort, black, mypy, headers
+        run: |
+          tox -e format-check

.gitignore

@@ -25,6 +25,8 @@ share/python-wheels/
 .installed.cfg
 *.egg
 MANIFEST
+pyqasm/_version.py
+
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

CHANGELOG.md

@@ -30,4 +30,5 @@ Types of changes:
 
 ### Added
 - Setup basic project/repo template ([#1](https://github.com/qBraid/pyqasm/pull/1))
-- Configured PyPI workflows ([#2](https://github.com/qBraid/pyqasm/pull/2))
+- Configured PyPI workflows ([#2](https://github.com/qBraid/pyqasm/pull/2))
+- Add initial implementation ([#3](https://github.com/qBraid/pyqasm/pull/3))

CONTRIBUTING.md

@@ -1 +1,115 @@
-# Contributing
+# Contributing
+
+Welcome! We're delighted that you're interested in contributing. Your help is essential for keeping the project great.
+
+## Getting Started
+
+Before you start working on a new feature or a fix, here's how you can contribute:
+
+1. **Fork the repository**: Visit the GitHub page of our project and use the "Fork" button to create a copy of the project in your own GitHub account.
+2. **Create a Development Branch**: After forking, clone the repository to your local machine and create a new branch for your development. Use a descriptive name for your branch, such as `feature-<feature-name>` or `bugfix-<bug-description>`.
+3. **Commit Your Changes**: Make your changes in your development branch and commit them. Be sure to write clear, concise commit messages.
+4. **Push to Your Fork**: Push your changes to your forked repository on GitHub.
+5. **Create a Pull Request**: Go to the original project repository and click on "Pull Requests", then click the "New Pull Request" button
+
+### Development install
+
+```shell
+git clone https://github.com/qBraid/pyqasm.git
+cd pyqasm
+pip install -e .
+```
+
+## Pull requests
+
+Before submitting a pull request (PR), ensure your contributions comply with the [Developer's Certificate of Origin](https://developercertificate.org/), confirming your right to submit the work under this project's license. Contributors are encouraged to [sign commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits), however, it is not required.
+
+For code changes, please ensure that:
+1. All new code includes corresponding unit tests and satisfies code coverage.
+2. Docstrings are thorough and accurate for both new and updated features.
+3. All integration tests, including docs and linters, are passing.
+4. New functions and classes are annotated with Python type hints to support `py.typed`.
+
+Once PR has been validated by the maintainers, please ensure to update the [`CHANGELOG.md`](https://github.com/qBraid/pyqasm/blob/main/CHANGELOG.md) with a description of the PR and its link. You can refer to the [past release changelogs](https://github.com/qBraid/pyqasm/releases/tag/v0.0.0) as an example. Please make sure to correctly classify your work under one of the available contribution types.
+
+### Run tests
+
+Workflow: [`main.yml`](.github/workflows/main.yml)
+
+- [ ] All unit tests are passing
+- [ ] New/modified code has corresponding unit tests and satisfies ``codecov`` checks.
+
+Install pytest:
+
+```shell
+pip install pytest pytest-cov
+```
+
+Run unit tests:
+
+```shell
+pytest tests
+```
+
+Generate a coverage report and verify that project and diff ``codecov`` are both upheld:
+
+```bash
+pytest --cov=pyqasm --cov-report=term tests/
+```
+
+### Build docs
+
+Workflow: [`docs.yml`](.github/workflows/docs.yml)
+
+- [ ] Docs builds are passing.
+- [ ] New/modified code has appropriate docstrings.
+- [ ] Tree stubs are updated, if applicable.
+- [ ] README and/or example notebooks are updated, if applicable.
+
+Static docs pages (e.g. User Guide) are written using reStructuredText (reST), which is the default plaintext markup language used by [Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html). It's pretty straightforward once you get the hang of it. If you're unfamiliar, [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#restructuredtext-primer) is a good place to start.
+
+Use [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
+to specify attributes, arguments, exceptions, returns, and other related info. The docstrings are compiled into HTML using Sphinx, so to add relative links, in-line markup, bulleted lists, code-blocks, or do other types of formatting inside of docstrings, use the `reST` syntax mentioned (linked) above.
+
+Install sphinx and other docs requirements:
+
+```shell
+pip install -e '.[docs]'
+```
+
+Then, build docs with:
+
+```shell
+cd docs
+make html
+```
+
+View docs in local browser window:
+
+```shell
+open build/html/index.html
+```
+
+### Code style
+
+Workflow: [`format.yml`](.github/workflows/format.yml)
+
+- [ ] Formatting/linters checks pass
+- [ ] All files have appropriate licensing header
+
+For code style, our project uses a combination of [isort](https://github.com/PyCQA/isort), [pylint](https://github.com/pylint-dev/pylint),
+and [black](https://github.com/psf/black). Specific configurations for these tools should be added to [`pyproject.toml`](pyproject.toml).
+
+Install linters:
+
+```shell
+pip install 'black[jupyter]' isort pylint
+```
+
+Run the following and make changes as needed to satisfy format checks:
+
+```shell
+black pyqasm tests examples
+isort pyqasm tests
+pylint pyqasm tests
+```

pyproject.toml

@@ -32,14 +32,14 @@ classifiers = [
     'Operating System :: Unix',
     'Operating System :: MacOS',
 ]
-dependencies = ["pyqir>=0.10.0,<0.11.0", "numpy"]
+dependencies = ["numpy", "openqasm3[parser]==1.0.0"]
 
 [project.urls]
 source = "https://github.com/qBraid/pyqasm"
 tracker = "https://github.com/qBraid/pyqasm/issues"
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-cov", "autoqasm>=0.1.0"]
+test = ["pytest", "pytest-cov"]
 lint = ["black", "isort", "pylint", "mypy", "qbraid-cli>=0.8.5"]
 docs = ["sphinx>=7.3.7,<8.1.0", "sphinx-autodoc-typehints>=1.24,<2.5", "sphinx-rtd-theme~=2.0.0", "docutils<0.22", "sphinx-copybutton"]
 
@@ -60,7 +60,7 @@ line_length = 100
 
 [tool.pylint.'MESSAGES CONTROL']
 max-line-length = 100
-disable = "C0414,C0415,R0914,W0511"
+disable = "C0414, C0415, R0914, C0103, C0115, C0116, I1101, R0903, R0917, W0212, W0511"
 
 [tool.pylint.MASTER]
 ignore-paths = [

pyqasm/README.md

@@ -0,0 +1,32 @@
+# OpenQASM 3 to QIR
+
+## Supported conversions status table
+
+| openqasm3.ast Object Type      | Supported   | Comment                |
+| -------------------------------| ----------- | ---------------------- |
+| QuantumMeasurementStatement    | ✅          | Complete               |
+| QuantumReset                   | ✅          | Complete               |
+| QuantumBarrier                 | ✅          | Complete               |
+| QuantumGateDefinition          | ✅          | Complete               |
+| QuantumGate                    | ✅          | Complete               |
+| QuantumGateModifier            | ✅          | Complete (pow, inv)    |
+| QubitDeclaration               | ✅          | Completed              |
+| Clbit Declarations             | ✅          | Completed              |
+| BinaryExpression               | ✅          | Completed              | 
+| UnaryExpression                | ✅          | Completed              |
+| ClassicalDeclaration           | ✅          | Completed              |
+| ConstantDeclaration            | ✅          | Completed              |
+| ClassicalAssignment            | ✅          | Completed              |
+| AliasStatement                 | ✅          | Completed              |
+| SwitchStatement                | ✅          | Completed              |
+| BranchingStatement             | 🔜          | In progress            |
+| SubroutineDefinition           | 🔜          | In progress            |
+| Looping statements(eg. for)    | 🔜          | In progress            |
+| RangeDefinition                | 🔜          | In progress            |
+| IODeclaration                  | 📋          | Planned                |
+| Pragma                         | ❓          | Unsure                 |
+| Annotations                    | ❓          | Unsure                 |
+| Pulse-level ops (e.g. delay)   | ❌          | Not supported by QIR   |
+| Calibration ops                | ❌          | Not supported by QIR   |
+| Duration literals              | ❌          | Not supported by QIR   |
+| ComplexType                    | ❌          | Not supported by QIR   |

pyqasm/__init__.py

@@ -1,12 +1,12 @@
 # Copyright (C) 2024 qBraid
 #
-# This file is part of the qBraid-SDK
+# This file is part of pyqasm
 #
-# The qBraid-SDK is free software released under the GNU General Public License v3
+# Pyqasm is free software released under the GNU General Public License v3
 # or later. You can redistribute and/or modify it under the terms of the GPL v3.
 # See the LICENSE file in the project root or <https://www.gnu.org/licenses/gpl-3.0.html>.
 #
-# THERE IS NO WARRANTY for the qBraid-SDK, as per Section 15 of the GPL v3.
+# THERE IS NO WARRANTY for pyqasm, as per Section 15 of the GPL v3.
 
 """
 Top level module containing the main PyQASM functionality.
@@ -20,6 +20,7 @@
    :toctree: ../stubs/
 
    validate
+   unroll
 
 Exceptions
 -----------
@@ -41,11 +42,13 @@
     __version__ = "dev"
 
 from .exceptions import PyQasmError, ValidationError
+from .unroller import unroll
 from .validate import validate
 
 __all__ = [
     "PyQasmError",
     "ValidationError",
     "validate",
+    "unroll",
     "__version__",
 ]