docker container + project housekeep (#178)

* house keeping + docker updates

* update run run container echo

* add examples submodule

* updates workflows and manifest

* point to correct package entry in setuptools

* try hyphen convention

* update manifest and pyproject

* fixed typing & headers format

* keep version fixed

* update changelog

.github/workflows/docs.yml

@@ -3,18 +3,20 @@ name: Docs
 on:
   pull_request:
     branches: ['main']
+    types: [opened, reopened, ready_for_review, synchronize]
   workflow_dispatch:
 
 jobs:
   build:
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
 
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.10'
+        python-version: '3.11'
         cache: pip
     - name: Install dependencies
       run: |

.github/workflows/format.yml

@@ -3,10 +3,12 @@ name: Format
 on:
   pull_request:
       branches: ['main']
+      types: [opened, reopened, ready_for_review, synchronize]
   workflow_dispatch:
 
 jobs:
   check:
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/main.yml

@@ -3,12 +3,14 @@ name: CI
 on:
   pull_request:
     branches: ['main']
+    types: [opened, reopened, ready_for_review, synchronize]
   push:
     branches: ['main']
   workflow_dispatch:
 
 jobs:
   build:
+    if: github.event.pull_request.draft == false
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -35,6 +37,7 @@ jobs:
           path: dist/*.whl
 
   test:
+    if: github.event.pull_request.draft == false
     needs: build
     runs-on: ubuntu-latest
     strategy:
@@ -56,7 +59,7 @@ jobs:
       - name: Install package wheel with extras
         run: |
           pip install setuptools
-          tools/install_wheel_extras.sh dist --extra qasm3 --extra cirq --extra test
+          bin/install_wheel_extras.sh dist --extra qasm3 --extra cirq --extra test
       - name: Run tests with coverage
         run: |
           pytest --cov=qbraid_qir tests/ --cov-report=html --cov-report=xml --cov-report=term

.github/workflows/pre-release.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Install dependencies
         run: |
@@ -25,10 +25,10 @@ jobs:
       - name: Build binary wheel + source tarball
         id: build-dev
         run: |
-            export QBRAID_PRE_RELEASE_VERSION=$(tools/stamp_dev_version.sh)
+            export QBRAID_PRE_RELEASE_VERSION=$(bin/stamp_dev_version.sh)
             [[ "$QBRAID_PRE_RELEASE_VERSION" =~ .*dev.* ]] && echo "Deploying dev version '$QBRAID_PRE_RELEASE_VERSION'" || (echo "not dev version"; exit 0)
             out_dir="${PWD}/dist"
-            tools/create_dev_build.sh $QBRAID_PRE_RELEASE_VERSION "${out_dir}"
+            bin/create_dev_build.sh $QBRAID_PRE_RELEASE_VERSION "${out_dir}"
             echo "dir=$out_dir" >> $GITHUB_OUTPUT
 
       - name: Publish package to PyPI

.github/workflows/publish.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.11'
 
       - name: Build binary wheel + source tarball
         run: |

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "examples"]
+	path = examples
+	url = https://github.com/qBraid/qbraid-lab-demo.git

.readthedocs.yaml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.10"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

CHANGELOG.md

@@ -16,12 +16,18 @@ Types of changes:
 
 ### ➕  New Features 
 
-### 🌟  Improvements 
+### 🌟  Improvements
+- Update QIR-Runner docker container to `ubuntu:24.04` as base image ([#173](https://github.com/qBraid/qbraid-qir/pull/173))
+- Changed examples notebook to sub-module linked to [qbraid-lab-demo](https://github.com/qBraid/qbraid-lab-demo) repo. ([#178](https://github.com/qBraid/qbraid-qir/pull/178))
+- Improved typing in `qbraid_qir.qasm3.linalg` ([#178](https://github.com/qBraid/qbraid-qir/pull/178))
+- Updated project metadata and README in anticipation of release v0.3 ([#178](https://github.com/qBraid/qbraid-qir/pull/178))
 
-### 📜  Documentation 
+### 📜  Documentation
+- Updated sphinx docs pages with PyQASM API reference links ([#174](https://github.com/qBraid/qbraid-qir/pull/174))
 
 ### 🐛  Bug Fixes
 
 ### ⬇️  Dependency Updates 
+- Added `pyqasm` as project dependency ([#173](https://github.com/qBraid/qbraid-qir/pull/173))
 
 ### 👋  Deprecations

MANIFEST.in

@@ -1,5 +1,5 @@
-include *.txt *.md 
-recursive-include docs *.rst *.py *.png *.ico *.txt
+include README.md
+recursive-include docs *.rst *.py *.png *.ico
 recursive-include qbraid_qir *.py
 include qbraid_qir/py.typed
 prune docs/build/

README.md

@@ -16,11 +16,8 @@
   <a href="https://pypi.org/project/qbraid-qir/">
     <img src="https://img.shields.io/pypi/pyversions/qbraid-qir.svg?color=blue" alt="PyPI version"/>
   </a>
-<!--   <a href="https://pepy.tech/project/qbraid-qir">
-    <img src="https://static.pepy.tech/badge/qbraid-qir" alt="Downloads"/>
-  </a> -->
   <a href='https://www.gnu.org/licenses/gpl-3.0.html'>
-    <img src='https://img.shields.io/github/license/qBraid/qbraid.svg' alt='License'/>
+    <img src='https://img.shields.io/github/license/qBraid/qbraid-qir.svg' alt='License'/>
   </a>
   <a href='https://discord.gg/TPBU2sa8Et'>
     <img src="https://img.shields.io/badge/Discord-%235865F2.svg?logo=discord&logoColor=white" alt="Discord"/>
@@ -39,7 +36,7 @@ This project aims to make [QIR](https://www.qir-alliance.org/) representations a
 
 ## Installation
 
-qBraid-QIR requires Python 3.9 or greater, and can be installed with pip as follows:
+qBraid-QIR requires Python 3.10 or greater, and can be installed with pip as follows:
 
 ```shell
 pip install qbraid-qir
@@ -83,9 +80,9 @@ pip install '.[qasm3,cirq]'
 You can view the version of qbraid-qir you have installed within a Python shell as follows:
 
 ```python
-In [1]: import qbraid_qir
+import qbraid_qir
 
-In [2]: qbraid_qir.__version__
+qbraid_qir.__version__
 ```
 
 ## Resources
@@ -100,7 +97,7 @@ In [2]: qbraid_qir.__version__
 ### OpenQASM 3 conversions
 
 ```python
-from qbraid_qir.qasm3 import qasm3_to_qir
+from qbraid_qir import qasm3_to_qir
 
 program = """
 OPENQASM 3;
@@ -125,7 +122,7 @@ ir = str(module)
 
 ```python
 import cirq
-from qbraid_qir.cirq import cirq_to_qir
+from qbraid_qir import cirq_to_qir
 
 q0, q1 = cirq.LineQubit.range(2)
 

tools/create_dev_build.sh → bin/create_dev_build.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (C) 2023 qBraid
+# Copyright (C) 2024 qBraid
 #
 # This file is part of the qBraid-SDK
 #

tools/stamp_dev_version.sh → bin/stamp_dev_version.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Copyright (C) 2023 qBraid
+# Copyright (C) 2024 qBraid
 #
 # This file is part of the qBraid-SDK
 #

test-containers/qir_runner/Dockerfile → docker/linux-amd64/Dockerfile

@@ -1,17 +1,22 @@
 # Copyright (C) 2024 qBraid Development Team.
 # Distributed under terms of the GNU General Public License v3.
-FROM jupyter/base-notebook:python-3.11
+
+FROM ubuntu:24.04
 
 LABEL maintainer="qBraid Development Team <[email protected]>"
-LABEL description="Flexible environment with Jupyter, Rust, LLVM, and qir-runner"
+LABEL licenses="GNU General Public License v3.0"
+LABEL title="qBraid-QIR x QIR bytecode runner"
+LABEL description="Flexible environment with qBraid-QIR and the QIR-Runner (built from source)."
 LABEL version="1.0"
 
-USER root
+ENV USER=qbraid
+
+ENV HOME=/home/$USER
 
 RUN apt-get update --yes && \
     apt-get install --yes --no-install-recommends \
     # Basic utilities
-    vim git curl jq pkg-config lsb-release wget software-properties-common gnupg \
+    sudo vim git curl jq pkg-config lsb-release wget software-properties-common gnupg \
     # SSL related dependencies
     openssl libssl-dev \
     # Build dependencies
@@ -23,11 +28,17 @@ RUN apt-get update --yes && \
     # LLVM dependencies
     clang-format clang-tidy clang-tools clang clangd libc++-dev libc++1 libc++abi-dev \
     libc++abi1 libclang-dev libclang1 liblldb-dev libllvm-ocaml-dev libomp-dev \
-    libomp5 lld lldb llvm-dev llvm-runtime llvm python3-clang && \
+    libomp5 lld lldb llvm-dev llvm-runtime llvm python3-clang \
+    libpolly-18-dev libzstd-dev \
+    # Python interpreter and package managers 
+    cargo python3 python3-pip python3-venv && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
 
-USER $NB_UID
+RUN useradd -ms /bin/bash $USER && \
+    echo "$USER ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers
+
+USER $USER
 
 # Install Rustup: https://www.rust-lang.org/tools/install
 RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
@@ -39,11 +50,9 @@ USER root
 RUN bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
 
 RUN git clone https://github.com/qir-alliance/qir-runner.git /opt/qir-runner && \
-    chown -R $NB_UID:$NB_GID /opt/qir-runner && \
-    mkdir -p $(pip cache dir) && \
-    fix-permissions $(pip cache dir)
+    chown -R $USER:$USER /opt/qir-runner
 
-USER $NB_UID
+USER $USER
 
 WORKDIR /opt/qir-runner
 
@@ -52,9 +61,11 @@ RUN cargo install llvmenv && \
 
 ENV PATH="/opt/qir-runner/target/release:${PATH}"
 
-RUN pip install qbraid qbraid-qir[cirq,qasm3] qbraid-core[runner] && \
-    rm -rf $(pip cache dir)/*
+WORKDIR /work
 
-USER root
+RUN python3 -m venv venv && \
+    venv/bin/python3 -m pip install --upgrade pip && \
+    venv/bin/python3 -m pip install qbraid qbraid-qir[cirq,qasm3] qbraid-core[runner] && \
+    rm -rf $(venv/bin/python3 -m pip cache dir)
 
-WORKDIR $HOME
+COPY --chown=USER:USER ./examples examples

docker/linux-amd64/README.md

@@ -0,0 +1,54 @@
+# QIR Runner Docker Container
+
+This Docker image provides an environment for testing and executing Quantum Intermediate Representation (QIR)
+bytecode programs with the [qir-runner](https://github.com/qir-alliance/qir-runner/tree/main) package.
+
+## Build & run image
+
+To build the QIR runner image, run the following command:
+
+```bash
+./build.sh
+```
+
+To start the container, use the following command:
+
+```bash
+./run.sh <container_name>
+```
+
+To access an interactive shell inside the running container:
+
+```bash
+./exec.sh <container_name>
+```
+
+## Verify setup with bell circuit example
+
+Once inside the running container, activate the Python virtual environment that contains `qbraid-qir` by running:
+
+```bash
+source /work/venv/bin/activate
+```
+
+Next, run one of the example scripts to verify the setup:
+
+```bash
+python3 /work/examples/cirq_bell.py
+```
+
+This should output something similar to:
+
+```bash
+Cirq Circuit: 
+0: ───H───@───M───
+          │   │
+1: ───────X───M───
+
+Running on: QirRunner(seed=None, exec_path=/opt/qir-runner/target/release/qir-runner, version=0.7.4)
+
+Result: {...,'measurementCounts': {'00': 5, '11': 5}, 'runnerVersion': '0.7.4', 'runnerSeed': None}
+```
+
+
+

docker/linux-amd64/build.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+# Copyright (C) 2024 qBraid Development Team.
+# Distributed under terms of the GNU General Public License v3.
+
+docker build --platform linux/amd64 -t qbraid/qir-runner .

docker/linux-amd64/examples/cirq_bell.py

@@ -0,0 +1,34 @@
+# Copyright (C) 2024 qBraid
+#
+# This file is part of qbraid-qir
+#
+# Qbraid-qir 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 qbraid-qir, as per Section 15 of the GPL v3.
+
+"""
+Example of running a Cirq circuit on the QIR bytecode runner.
+
+"""
+
+import cirq
+from qbraid.runtime import QirRunner
+
+from qbraid_qir.cirq import cirq_to_qir
+
+q0, q1 = cirq.LineQubit.range(2)
+circuit = cirq.Circuit(cirq.H(q0), cirq.CNOT(q0, q1), cirq.measure(q0, q1))
+
+print(f"Cirq Circuit: \n{circuit}")
+
+module = cirq_to_qir(circuit, name="bell")
+
+sim = QirRunner()
+
+print(f"\nRunning on: {repr(sim)}")
+
+result = sim.run(module.bitcode, shots=10)
+
+print(f"\nResult: {result}")