pyqir opaque pointers + docs & refs updates

.github/workflows/main.yml

@@ -42,7 +42,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
       - uses: actions/checkout@v6
@@ -58,44 +58,33 @@ jobs:
           path: dist
       - name: Install package wheel with extras
         run: |
+          pip install --upgrade pip
           pip install setuptools
-          bin/install_wheel_extras.sh dist --extra qasm3 --extra cirq --extra test --extra squin
-      - name: Run tests with coverage
+          pip install -r requirements-test.txt
+          bin/install_wheel_extras.sh dist --extra qasm3 --extra cirq --extra squin
+      - name: Run tests with pyqir 0.11.x (typed pointers)
         run: |
-          pytest --cov=qbraid_qir tests/ --cov-report=html --cov-report=xml --cov-report=term
+          pip install "pyqir>=0.10.0,<0.12"
+          pytest tests/ --cov=qbraid_qir --cov-report=term --cov-report= --cov-config=pyproject.toml -q
+          pip install coverage
+          mkdir -p cov_runs
+          python -m coverage combine --data-file=cov_runs/.coverage.run1 .coverage
+      - name: Run tests with pyqir 0.12+ (opaque pointers)
+        run: |
+          pip install "pyqir>=0.12.0,<0.13.0"
+          pytest tests/ --cov=qbraid_qir --cov-report=term --cov-report= --cov-config=pyproject.toml -q
+          python -m coverage combine --data-file=cov_runs/.coverage.run2 .coverage
+      - name: Combine coverage and generate report
+        run: |
+          python -m coverage combine cov_runs/.coverage.run1 cov_runs/.coverage.run2
+          python -m coverage report
+          mkdir -p build/coverage
+          python -m coverage xml -o build/coverage/coverage.xml
       - name: Upload coverage to Codecov
         if: matrix.python-version == '3.11'
         uses: codecov/codecov-action@v5.5.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           fail_ci_if_error: false
           files: ./build/coverage/coverage.xml
-          verbose: true
-
-  test-cudaq-to-squin:
-    if: github.event.pull_request.draft == false
-    needs: build
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ['3.11']
-
-    steps:
-      - uses: actions/checkout@v5
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v6
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
-      - name: Download built package
-        uses: actions/download-artifact@v5
-        with:
-          name: built-package
-          path: dist
-      - name: Install package wheel with squin and test extras
-        run: |
-          pip install setuptools
-          bin/install_wheel_extras.sh dist --extra squin --extra test
-      - name: Run CUDAQ to Squin tests
-        run: |
-          pytest tests/squin_qir/test_cudaq_to_squin.py -v
+          verbose: true

CHANGELOG.md

@@ -14,64 +14,34 @@ Types of changes:
 
 ## [Unreleased]
 
-### ➕  New Features 
-- Added a QIR to `squin` conversion method which allows users to execute QIR programs on `squin` enabled backends. This feature also opens up the Squin representation to many formats such as QASM, and Cirq using the built in qbraid-qir converters. Eg. - ([#252](https://github.com/qBraid/qbraid-qir/pull/252))
-
-```python
-# Converting a PyQIR module to squin
-from qbraid_qir.squin import load
-from pyqir import BasicQisBuilder, SimpleModule
-
-mod = SimpleModule("ghz", num_qubits=3, num_results=3)
-qis = BasicQisBuilder(mod.builder)
-
-qis.h(mod.qubits[0])
-qis.cx(mod.qubits[0], mod.qubits[1])
-qis.cx(mod.qubits[1], mod.qubits[2])
-
-squin_kernel = load(mod._module)
-squin_kernel.print()
-```
-
-Output:
-```stdout
-func.func @main() -> !py.NoneType {
-  ^0(%main_self):
-  │ %0 = func.invoke new() : !py.Qubit maybe_pure=False
-  │ %1 = func.invoke new() : !py.Qubit maybe_pure=False
-  │ %2 = func.invoke h(%0) : !py.NoneType maybe_pure=False
-  │ %3 = func.invoke x(%0) : !py.NoneType maybe_pure=False
-  │ %4 = func.invoke x(%1) : !py.NoneType maybe_pure=False
-  │ %5 = py.constant.constant 1.5707963267948966 : !py.float
-  │ %6 = func.invoke rx(%5, %0) : !py.NoneType maybe_pure=False
-  │ %7 = func.const.none() : !py.NoneType
-  │      func.return %7
-} // func.func main
-
-```
+### ➕  New Features
 
+- **PyQIR 0.12+ support**: Add compatibility for pyqir 0.12+ (opaque pointers / QIR 2.0) alongside existing 0.10.x support. New `_pyqir_compat` module provides `pointer_id`, `qubit_pointer_type`, and `pyqir_uses_opaque_pointers()` for version-agnostic code. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
 
 ### 🌟  Improvements
-- Split `qbraid_qir.profile` into `qbraid_qir.module` and `qbraid_qir.visitor` ([#237](https://github.com/qBraid/qbraid-qir/pull/237))
 
-- Improved circuit pre-processing for Cirq converter using Cirq's built-in `optimize_for_target_gateset` ([#248](https://github.com/qBraid/qbraid-qir/pull/248)) 
-
-- Fix types in the `cirq` converter ([#255](https://github.com/qBraid/qbraid-qir/pull/255)) 
+- **Backward-compatible PyQIR usage**: Cirq, QASM3, and Squin visitors use the compat layer so the codebase works with both pyqir <0.12 (typed pointers) and ≥0.12 (opaque pointers). ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
+- **Version-aware tests**: Test helpers and fixtures choose typed vs opaque pointer expectations based on the installed pyqir version; added version-specific LL fixtures (e.g. `*_typed.ll`, `*_opaque.ll`) for Cirq and QASM3 tests. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
+- **CI: test both PyQIR versions**: GitHub Actions test job runs the full suite with pyqir 0.10.x and 0.12+, then combines coverage and uploads to Codecov. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
+- **Tox: dual PyQIR envs**: New `unit-tests-pyqir10` and `unit-tests-pyqir12` tox environments so `tox` runs unit tests against both pyqir version ranges.
+- **Optional test deps**: Skip cudaq-to-Squin tests when cudaq is not installed; skip autoqasm converter tests when autoqasm is not installed. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
 
 ### 📜  Documentation
-- Factor out docs deps into its own requirements file ([#237](https://github.com/qBraid/qbraid-qir/pull/237))
+
+- **CHANGELOG**: Clarified "Past releases" section with a short description and link to the Releases page. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
 
 ### 🐛  Bug Fixes
 
-### ⬇️  Dependency Updates 
-- Update `pyqasm` requirement from >=0.4.0,<0.5.0 to >=0.4.0,<0.6.0 ([#236](https://github.com/qBraid/qbraid-qir/pull/236))
-- Update docutils requirement from <0.22 to <0.23 ([#238](https://github.com/qBraid/qbraid-qir/pull/238))
-- Bump actions/upload-pages-artifact from 3 to 4 ([#241](https://github.com/qBraid/qbraid-qir/pull/241))
-- Update pyqasm requirement from <0.6.0,>=0.4.0 to >=0.4.0,<1.1.0 ([#245](https://github.com/qBraid/qbraid-qir/pull/245))
-- Update qbraid requirement from <0.10.0,>=0.9.0 to >=0.9.0,<0.11.0 ([#247](https://github.com/qBraid/qbraid-qir/pull/247))
-- Bump actions/download-artifact from 5 to 6 ([#249](https://github.com/qBraid/qbraid-qir/pull/249))
-- Bump actions/upload-artifact from 4 to 5 ([#250](https://github.com/qBraid/qbraid-qir/pull/250))
-- Bump actions/checkout from v5 to v6 ([#254](https://github.com/qBraid/qbraid-qir/pull/254))
+- _(none this release)_
+
+### ⬇️  Dependency Updates
 
+- **pyqir**: Relax requirement from `>=0.10.0,<0.11.0` to `>=0.10.0,<0.13.0` so both 0.10.x and 0.12.x are supported. ([#265](https://github.com/qBraid/qbraid-qir/pull/265))
 
 ### 👋  Deprecations
+
+- _(none)_
+
+## Past releases
+
+Release notes for earlier versions are published on the [Releases](https://github.com/qBraid/qbraid-qir/releases) page.

CITATION.cff

@@ -19,6 +19,7 @@ keywords:
 - llvm
 - cirq
 - openasm
+- squin
 license: Apache-2.0
 version: 0.5.0
 date-released: '2025-12-15'

README.md

@@ -29,13 +29,13 @@
 
 qBraid-SDK extension providing support for QIR conversions.
 
-[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com?gitHubUrl=https://github.com/qBraid/qbraid-qir.git)
+[<img src="https://qbraid-static.s3.amazonaws.com/logos/Launch_on_qBraid_white.png" width="150">](https://account.qbraid.com/explore/projects/qbraid-qir-n792k0)
 
 ## Motivation
 
 <img align="right" width="100" alt="qir" src="https://qbraid-static.s3.amazonaws.com/logos/qir.png">
 
-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/sdk/user-guide/overview#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).
+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/v2/sdk/user-guide/overview#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).
 
 ## Installation
 
@@ -61,6 +61,12 @@ For Cirq to QIR conversions, install the `cirq` extra:
 pip install 'qbraid-qir[cirq]'
 ```
 
+For QIR to SQUIN conversions, install the `squin` extra:
+
+```shell
+pip install 'qbraid-qir[squin]'
+```
+
 ### Install from source
 
 You can also install from source by cloning this repository and running a pip install command
@@ -75,7 +81,7 @@ pip install .
 To include optional dependencies when installing from source, use the same "extras_require" format, e.g.
 
 ```shell
-pip install '.[qasm3,cirq]'
+pip install '.[qasm3,cirq,squin]'
 ```
 
 ## Check version
@@ -90,7 +96,7 @@ qbraid_qir.__version__
 
 ## Resources
 
-- [User Guide](https://docs.qbraid.com/qir/user-guide)
+- [User Guide](https://docs.qbraid.com/v2/qir/user-guide)
 - [API Reference](https://sdk.qbraid.com/qbraid-qir/api/qbraid_qir.html)
 - [Example Notebooks](https://github.com/qBraid/qbraid-lab-demo/tree/main/qbraid_qir)
 - [Docker Containers](docker)
@@ -140,9 +146,26 @@ module = cirq_to_qir(circuit, name="my-circuit")
 ir = str(module)
 ```
 
+### SQUIN conversions
+
+```python
+from pyqir import BasicQisBuilder, SimpleModule
+from qbraid_qir.squin import load
+
+module = SimpleModule("ghz_n", num_qubits=2, num_results=2)
+qis = BasicQisBuilder(module.builder)
+
+qis.h(module.qubits[0])
+qis.cx(module.qubits[0], module.qubits[1])
+
+squin_module = load(module.ir())
+
+squin_module.print()
+```
+
 ## Architecture diagram
 
-qBraid-SDK transpiler hub-and-spokes [architecture](https://docs.qbraid.com/qir/user-guide/overview#architecture-diagram) with qbraid-qir integration (left) mapped to language specific conversion step in QIR abstraction [layers](https://www.qir-alliance.org/qir-book/concepts/why-do-we-need.html) (right).
+qBraid-SDK transpiler hub-and-spokes [architecture](https://docs.qbraid.com/v2/qir/user-guide/overview#architecture-diagram) with qbraid-qir integration (left) mapped to language specific conversion step in QIR abstraction [layers](https://www.qir-alliance.org/qir-book/concepts/why-do-we-need.html) (right).
 
 <img width="full" alt="architecture" src="https://github.com/qBraid/qbraid-qir/assets/46977852/36644614-2715-4f08-8a8c-8a2e61aebf38">
 
@@ -169,10 +192,10 @@ citation details, please refer to [CITATION.cff](CITATION.cff).
 @software{Gupta_qBraid-QIR_Python_package_2025,
   author = {Gupta, Harshit and Hill, Ryan James},
   license = {Apache-2.0},
-  month = jun,
+  month = dec,
   title = {{qBraid-QIR: Python package for QIR conversions, integrations, and utilities.}},
   url = {https://github.com/qBraid/qbraid-qir},
-  version = {0.4.0},
+  version = {0.5.0},
   year = {2025}
 }
 ```

bin/bump_version.py

@@ -16,6 +16,7 @@
 Script to bump the major, minor, or patch version in _version.py
 
 """
+
 import pathlib
 import sys
 

docs/api/qbraid_qir.squin.rst

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

docs/conf.py

@@ -15,7 +15,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "qBraid"
-copyright = "2025, qBraid Development Team"
+copyright = "2026, qBraid Development Team"
 author = "qBraid Development Team"
 
 # The full version, including alpha/beta/rc tags
@@ -41,7 +41,7 @@
 # set_type_checking_flag = True
 autodoc_member_order = "bysource"
 autoclass_content = "both"
-autodoc_mock_imports = ["cirq", "openqasm3", "pyqasm", "numpy", "numpy.typing"]
+autodoc_mock_imports = ["cirq", "openqasm3", "pyqasm", "numpy", "numpy.typing", "kirin", "bloqade"]
 napoleon_numpy_docstring = False
 todo_include_todos = True
 mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"

docs/index.rst

@@ -91,7 +91,7 @@ To enable specific conversions such as OpenQASM 3 to QIR or Cirq to QIR, you can
 Resources
 ----------
 
-- `User Guide <https://docs.qbraid.com/qir/user-guide>`_
+- `User Guide <https://docs.qbraid.com/v2/qir/user-guide>`_
 - `Example Notebooks <https://github.com/qBraid/qbraid-lab-demo/tree/main/qbraid_qir>`_
 - `API Reference <https://qbraid.github.io/qbraid-qir/api/qbraid_qir.html>`_
 - `Source Code <https://github.com/qBraid/qbraid-qir>`_
@@ -117,6 +117,7 @@ Resources
    api/qbraid_qir
    api/qbraid_qir.cirq
    api/qbraid_qir.qasm3
+   api/qbraid_qir.squin
 
 .. toctree::
    :caption: CORE API Reference
@@ -130,3 +131,9 @@ Resources
    :hidden:
 
    pyqasm <https://qbraid.github.io/pyqasm/api/pyqasm.html>
+
+.. toctree::
+   :caption: ALGOS API Reference
+   :hidden:
+
+   qbraid_algorithms <https://qbraid.github.io/qbraid-algorithms/api/qbraid_algorithms.html>

pyproject.toml

@@ -9,7 +9,7 @@ description = "qBraid-SDK extension providing support for QIR conversions."
 readme = "README.md"
 authors = [{name = "qBraid Development Team"}, {email = "contact@qbraid.com"}]
 license = "Apache-2.0"
-keywords = ["qbraid", "quantum", "qir", "llvm", "cirq", "openqasm"]
+keywords = ["qbraid", "quantum", "qir", "llvm", "cirq", "openqasm", "squin"]
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
@@ -21,17 +21,18 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: 3 :: Only",
     "Typing :: Typed",
     "Topic :: Scientific/Engineering",
     "Topic :: Scientific/Engineering :: Physics"
 ]
-dependencies = ["pyqir>=0.10.0,<0.11.0"]
+dependencies = ["pyqir>=0.10.0,<0.13.0"]
 requires-python = ">=3.10"
 
 [project.urls]
 Homepage = "https://github.com/qBraid/qbraid-qir"
-Documentation = "https://docs.qbraid.com/qir"
+Documentation = "https://docs.qbraid.com/v2/qir"
 "Bug Tracker" = "https://github.com/qBraid/qbraid-qir/issues"
 Discord = "https://discord.gg/TPBU2sa8Et"
 "Launch on Lab" = "https://account.qbraid.com/?gitHubUrl=https://github.com/qBraid/qbraid-qir.git"
@@ -40,7 +41,6 @@ Discord = "https://discord.gg/TPBU2sa8Et"
 cirq = ["cirq-core>=1.3.0,<1.6.0"]
 qasm3 = ["pyqasm>=0.4.0,<1.1.0", "numpy"]
 squin = ["kirin-toolchain>=0.17.33", "bloqade-circuit>=0.9.1"]
-test = ["qbraid>=0.9.0,<0.11.0", "pytest", "pytest-cov", "autoqasm>=0.1.0", "cudaq"]
 
 [tool.setuptools]
 packages = ["qbraid_qir", "qbraid_qir.cirq", "qbraid_qir.qasm3", "qbraid_qir.squin"]

qbraid_qir/__init__.py

@@ -36,6 +36,7 @@
    QirConversionError
 
 """
+
 import importlib
 from typing import TYPE_CHECKING