3 qrisp circuit manipulation

.flake8

@@ -0,0 +1,2 @@
+[flake8]
+max-line-length = 100

.github/workflows/publish.yaml

@@ -13,7 +13,6 @@ jobs:
     strategy:
       matrix:
         python-version:
-          - "3.10"
           - "3.11"
           - "3.12"
           - "3.13"
@@ -24,17 +23,17 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-    #   - name: Install dependencies
-    #     run: >-
-    #       python3 -m
-    #       pip install
-    #       .[development]
-    #   - name: Run tests with coverage
-    #     run: >-
-    #       python3 -m
-    #       pytest
-    #       --cov=q8s
-    #       --cov-report=xml
+      - name: Install dependencies
+        run: >-
+          python3 -m
+          pip install
+          .[development,qiskit,qrisp]
+      - name: Run tests with coverage
+        run: >-
+          python3 -m
+          pytest
+          --cov=q8s.runtime
+          --cov-report=xml
     #   - name: Upload coverage to Codecov
     #     uses: codecov/codecov-action@v5
     #     if: matrix.python-version == '3.10'
@@ -158,4 +157,4 @@ jobs:
         with:
           repository-url: https://test.pypi.org/legacy/
           skip-existing: true
-          verbose: true
+          verbose: true

.gitignore

@@ -6,4 +6,4 @@ mlartifacts/
 mlflow.db
 
 .envrc
-out.txt
+out.txt

.pre-commit-config.yaml

@@ -0,0 +1,103 @@
+# Copyright 2026 Qubernetes Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+exclude: '^docs/conf.py'
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: check-added-large-files
+  - id: check-ast
+  # - id: check-json
+  - id: check-merge-conflict
+  - id: check-xml
+  - id: check-yaml
+  - id: debug-statements
+  - id: end-of-file-fixer
+  - id: requirements-txt-fixer
+  - id: mixed-line-ending
+    args: ['--fix=auto']  # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows
+
+## If you want to automatically "modernize" your Python code:
+# - repo: https://github.com/asottile/pyupgrade
+#   rev: v3.17.0
+#   hooks:
+#   - id: pyupgrade
+#     args: ['--py38-plus']
+
+## If you want to avoid flake8 errors due to unused vars or imports:
+# - repo: https://github.com/PyCQA/autoflake
+#   rev: v2.3.1
+#   hooks:
+#   - id: autoflake
+#     args: [
+#       --in-place,
+#       --remove-all-unused-imports,
+#       --remove-unused-variables,
+#     ]
+
+- repo: https://github.com/PyCQA/docformatter
+  rev: v1.7.7
+  hooks:
+  - id: docformatter
+    args:
+      - --in-place
+      - --wrap-summaries=88
+      - --wrap-descriptions=88
+
+- repo: https://github.com/PyCQA/isort
+  rev: 7.0.0
+  hooks:
+  - id: isort
+    args: ["--profile", "black", "--filter-files"]
+
+- repo: https://github.com/psf/black
+  rev: 25.11.0
+  hooks:
+  - id: black
+    language_version: python3
+
+# If like to embrace black styles even in the docs:
+- repo: https://github.com/asottile/blacken-docs
+  rev: 1.18.0
+  hooks:
+  - id: blacken-docs
+    additional_dependencies: [black]
+
+- repo: https://github.com/PyCQA/flake8
+  rev: 7.3.0
+  hooks:
+  - id: flake8
+  ## You can add flake8 plugins via `additional_dependencies`:
+  #  additional_dependencies: [flake8-bugbear]
+
+## Check for misspells in documentation files:
+# - repo: https://github.com/codespell-project/codespell
+#   rev: v2.3.0
+#   hooks:
+#   - id: codespell
+
+- repo: https://github.com/google/addlicense
+  rev: v1.2.0
+  hooks:
+    - id: addlicense
+      args: ["-c", "Qubernetes Project", "-s", "*.py"]
+        # - -c
+        # - Qubernetes Project
+        # - -l
+        # - apache
+        # - "*.py"
+      files: ^(src|tests)/.*\.py$

README.md

@@ -1,18 +1,39 @@
 # q8s.runtime
 
-A runtime library for q8s workloads.
+`q8s.runtime` provides common runtime, provenance, and experiment-tracking capabilities for quantum software.
+
+The library provides a QDK-independent representation of quantum programs and their execution metadata, together with integrations for quantum development kits such as [Qiskit](https://www.ibm.com/quantum/qiskit) and [Qrisp](https://www.qrisp.eu/index.html). This makes it possible to collect and analyse execution and compilation information consistently across different quantum software stacks.
 
 ## Installation
 
-You can install the q8s.runtime library using pip:
+Install the core package using:
 
 ```bash
 pip install q8s.runtime
 ```
 
-## Features
+Support for individual quantum development kits can be installed using the corresponding optional dependencies:
+
+```bash
+pip install "q8s.runtime[qiskit]"
+pip install "q8s.runtime[qrisp]"
+```
+
+Multiple integrations can be installed together:
+
+```bash
+pip install "q8s.runtime[qiskit,qrisp]"
+```
+
+## Integrations
+
+### Qiskit
+
+The Qiskit integration provides adapters for Qiskit objects and automatic experiment tracking through MLflow.
 
-### Qiskit autologging to MLflow
+#### MLflow autologging
+
+Qiskit transpilation and execution can be automatically captured by enabling autologging:
 
 ```python
 import mlflow
@@ -48,3 +69,121 @@ with mlflow.start_run():
 
     result.get_counts()
 ```
+
+The integration can capture information about the transpilation process, including individual transpiler passes and their associated metadata.
+
+### Qrisp
+
+The Qrisp integration converts Qrisp programs into the common `q8s.runtime` representation, allowing provenance and experiment information produced by Qrisp workflows to be handled using the same model as Qiskit workflows.
+
+```python
+import mlflow
+
+from q8s.runtime.mlflow.qrisp import autolog
+
+autolog()
+
+from qrisp import (
+    PassManager,
+    QuantumCircuit,
+    combine_single_qubit_gates,
+    commute_swaps,
+    fuse_adjacents,
+)
+
+from q8s.runtime.mlflow.qrisp.autologging import get_context
+from q8s.runtime.qprov.graphs import plot_transpilation_timeline
+
+mlflow.set_experiment("qrisp-transpilation")
+
+with mlflow.start_run():
+
+    qc = QuantumCircuit(2)
+    qc.cx(0, 1)
+    qc.cx(0, 1)  # Self-inverse — will be cancelled
+    qc.h(0)
+    qc.h(0)  # Another self-inverse pair
+
+    pm = PassManager()
+    pm += fuse_adjacents
+    pm += commute_swaps
+    pm += combine_single_qubit_gates
+
+    optimized_qc = pm.run(qc)
+```
+
+## Capabilities
+
+### Provenance
+
+`q8s.runtime` uses the **QProv provenance model** to describe the information associated with the lifecycle of a quantum program.
+
+QProv organizes provenance information into four main categories:
+
+| QProv category       | Description                                                       | Qiskit | Qrisp |
+| -------------------- | ----------------------------------------------------------------- | :----: | :---: |
+| **Quantum Circuit**  | Structure and characteristics of the quantum circuit              |   ◐    |   ◐   |
+| **Quantum Computer** | Characteristics of the quantum computer or execution backend      |   -    |   -   |
+| **Compilation**      | Transformation of a quantum circuit for a target quantum computer |   ◐    |   ◐   |
+| **Execution**        | Information associated with executing the compiled circuit        |   -    |   -   |
+
+The availability of individual provenance attributes depends on the QDK, backend, provider, and application.
+
+### Quantum Circuit
+
+Quantum Circuit provenance describes the structure and characteristics of the quantum circuit being executed.
+
+| QProv  | Provenance attribute | Qiskit | Qrisp |
+| ------ | -------------------- | :----: | :---: |
+| **Q1** | Gates                |   ✓    |   ✓   |
+| **Q2** | Measurements         |   ✓    |   ✓   |
+| **Q3** | Execution order      |   -    |   -   |
+| **Q4** | Circuit width        |   ✓    |   ✓   |
+| **Q5** | Circuit depth        |   ✓    |   ✓   |
+| **Q6** | Circuit size         |   ✓    |   ✓   |
+| **Q7** | Encoding             |   -    |   -   |
+
+Circuit width represents the number of qubits used by the circuit, circuit depth describes the number of sequential operations required by the circuit, and circuit size describes its number of operations.
+
+### Compilation
+
+Compilation provenance describes how an abstract quantum circuit is transformed into a circuit that can be executed by a particular quantum computer.
+
+| QProv  | Provenance attribute | Qiskit | Qrisp |
+| ------ | -------------------- | :----: | :---: |
+| **C1** | Qubit assignments    |   ✓    |   ✓   |
+| **C2** | Gate mappings        |   ✓    |   ✓   |
+| **C3** | Optimisation goal    |   ✓    |   -   |
+| **C4** | Random seed          |   ✓    |   -   |
+| **C5** | Compilation time     |   ✓    |   ✓   |
+
+In addition to the QProv compilation attributes, `q8s.runtime` toolkit collects **fine-grained compiler provenance**.
+
+For each transpiler pass, the following information can be recorded:
+
+| Compiler provenance | Description                                       | Qiskit | Qrisp |
+| ------------------- | ------------------------------------------------- | :----: | :---: |
+| **Pass index**      | Position of the pass in the transpilation process |   ✓    |   ✓   |
+| **Pass name**       | Transpiler pass name                              |   ✓    |   ✓   |
+| **Stage**           | Stage of the staged pass manager                  |   ✓    |   -   |
+| **Duration**        | Execution time of the pass                        |   ✓    |   ✓   |
+| **Circuit depth**   | Circuit depth after the pass                      |   ✓    |   ✓   |
+| **Circuit size**    | Circuit size after the pass                       |   ✓    |   ✓   |
+
+This extends QProv's compilation provenance with information about the internal compilation process and enables reconstruction and visualization of a **transpilation timeline**.
+
+**Legend:** ✓ supported · ◐ dependent on QDK/backend/application · — not currently collected
+
+## References
+
+The provenance model implemented by `q8s.runtime` is based on:
+
+> Weder, B., Breitenbücher, U., Leymann, F., and Wild, K.
+> _Integrating quantum computing into workflow modeling and execution._
+> IET Quantum Communication.
+
+See the QProv publication for the complete provenance model and definitions.
+
+## License
+
+`q8s.runtime` is licensed under the Apache License 2.0.

pyproject.toml

@@ -3,6 +3,7 @@ name = "q8s.runtime"
 version = "0.1.0"
 authors = [{ name = "Vlad Stirbu", email = "vstirbu@gmail.com" }]
 description = "A runtime library for q8s workloads"
+readme = "README.md"
 requires-python = ">=3.10"
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -15,7 +16,6 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -28,10 +28,19 @@ dependencies = ["mlflow-skinny", "dataclasses-json"]
 [project.optional-dependencies]
 matplotlib = ["matplotlib"]
 
+development = ["pre-commit", "pytest", "pytest-cov"]
+
+qiskit = ["qiskit", "qiskit-aer"]
+qrisp = ["qrisp"]
+
 test = ["mqt.bench", "qiskit<2.2", "mlflow", "iqm-client[qiskit]"]
 [build-system]
 requires = ["setuptools >= 61.0"]
 build-backend = "setuptools.build_meta"
 
 [tool.setuptools.packages.find]
 where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

src/q8s/runtime/__init__.py

@@ -1,3 +1,19 @@
+# Copyright 2026 Qubernetes Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# SPDX-License-Identifier: Apache-2.0
+
 from importlib.metadata import version
 
 __version__ = version("q8s.runtime")