4 ucc

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug report
+about: Report a reproducible problem with q8s.runtime.
+---
+
+## Description
+
+Describe the bug clearly and briefly.
+
+## Steps to reproduce
+
+Include a minimal code example and the commands or steps needed to reproduce the problem.
+
+```python
+# Minimal reproducible example
+```
+
+## Expected behavior
+
+What did you expect to happen?
+
+## Actual behavior
+
+What happened instead? Include relevant error messages or tracebacks.
+
+```text
+Paste error messages or tracebacks here.
+```
+
+## Environment
+
+- Operating system:
+- Python version:
+- q8s.runtime version (or commit if installed from source):
+- Relevant integrations and their versions (such as Qiskit, Qrisp, UCC, or MLflow):
+
+## Additional context
+
+Optional: include related issues, workarounds, or other details that help explain the problem.

.github/ISSUE_TEMPLATE/feature_or_idea.md

@@ -0,0 +1,24 @@
+---
+name: Feature or idea
+about: Discuss a new feature or improvement before starting implementation.
+---
+
+## Problem or use case
+
+What problem would this address? Describe who would benefit and how.
+
+## Proposed solution
+
+Describe the feature or improvement you have in mind. An example of the desired behavior or API is helpful. If you do not have a solution yet, describe the outcome you want.
+
+## Alternatives considered
+
+Describe any alternatives or existing workarounds you have considered.
+
+## Additional context
+
+Optional: include examples, related issues, or relevant integrations.
+
+## Interest in contributing
+
+Optional: let us know whether you would like to help implement the idea after discussion.

.github/workflows/publish.yaml

@@ -18,9 +18,9 @@ jobs:
           - "3.13"
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -49,9 +49,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.x"
       - name: Install pypa/build
@@ -63,7 +63,7 @@ jobs:
       - name: Build a binary wheel and a source tarball
         run: python3 -m build
       - name: Store the distribution packages
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: python-package-distributions
           path: dist/

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing
+
+## Report bugs
+
+Report bugs using this repository's GitHub Issues. Search existing issues first to avoid duplicates, then open an issue using the **Bug report** template.
+
+Include a minimal reproducible example, the behavior you expected, what actually happened, and any relevant error messages or tracebacks. Provide your operating system, Python version, `q8s.runtime` version, and versions of any relevant integrations.
+
+## Propose features and new ideas
+
+Discuss new features in a GitHub issue before starting implementation. Search existing issues first, then open an issue using the **Feature or idea** template. Describe the problem or use case, your proposed solution, and any alternatives you have considered so maintainers and contributors can discuss the scope and approach.
+
+## Development setup
+
+Run the following commands from the root of your local `q8s-runtime` checkout. You will need Git and Python 3.10 or newer; optional integrations may require a newer Python version.
+
+## Create a virtual environment
+
+On macOS or Linux:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+On Windows with PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Activate this environment whenever you open a new terminal to work on the project.
+
+## Install in editable mode
+
+Install the package and development tools into the active environment:
+
+```bash
+python -m pip install --upgrade pip
+python -m pip install -e ".[development]"
+```
+
+Editable mode makes changes under `src/` available without reinstalling the package. The `development` extra includes `pre-commit`, `pytest`, and `pytest-cov`.
+
+For integration development and the test suite, install the additional dependencies:
+
+```bash
+python -m pip install -e ".[development,test,qiskit,qrisp,ucc,matplotlib]"
+```
+
+The extras are defined in [pyproject.toml](pyproject.toml). You can select only the integrations needed for your work when running a subset of the tests.
+
+## Configure pre-commit
+
+Install the repository's Git hooks:
+
+```bash
+pre-commit install
+```
+
+Check all existing files once after setup:
+
+```bash
+pre-commit run --all-files
+```
+
+The first run downloads and prepares the hook environments, so it requires network access and can take longer. Hooks are configured in [.pre-commit-config.yaml](.pre-commit-config.yaml) and include formatting, import sorting, linting, file checks, and Python license headers.
+
+The hooks run automatically on staged files when you commit. If a hook modifies files, review and stage those changes, then retry the commit. Run `pre-commit run --all-files` before submitting changes.
+
+## Run tests
+
+With the test and integration dependencies installed:
+
+```bash
+python -m pytest
+```
+
+To run a specific test file:
+
+```bash
+python -m pytest tests/test_qiskit_utils.py
+```
+
+When you finish working, leave the virtual environment with `deactivate`.

README.md

@@ -2,7 +2,7 @@
 
 `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.
+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), [UCC](https://ucc.readthedocs.io/en/latest/) 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
 
@@ -17,12 +17,13 @@ Support for individual quantum development kits can be installed using the corre
 ```bash
 pip install "q8s.runtime[qiskit]"
 pip install "q8s.runtime[qrisp]"
+pip install "q8s.runtime[ucc]"
 ```
 
 Multiple integrations can be installed together:
 
 ```bash
-pip install "q8s.runtime[qiskit,qrisp]"
+pip install "q8s.runtime[qiskit,qrisp,ucc]"
 ```
 
 ## Integrations
@@ -112,6 +113,32 @@ with mlflow.start_run():
     optimized_qc = pm.run(qc)
 ```
 
+### UCC
+
+The UCC integration tracks the underlying Qiskit transpilation stages used by UCC through MLflow.
+
+Enable autologging before importing UCC's `compile` function, then compile within an active MLflow run:
+
+```python
+import mlflow
+
+from q8s.runtime.mlflow.ucc import autolog
+
+autolog()
+
+from qiskit import QuantumCircuit
+from ucc import compile
+
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+
+mlflow.set_experiment("ucc-compilation")
+
+with mlflow.start_run():
+    result = compile(qc)
+```
+
 ## Capabilities
 
 ### Provenance
@@ -120,15 +147,17 @@ with mlflow.start_run():
 
 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        |   -    |   -   |
+| QProv category       | Description                                                       | Qiskit | Qrisp | UCC |
+| -------------------- | ----------------------------------------------------------------- | :----: | :---: | :-: |
+| **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.
 
+UCC collects circuit and pass metadata through the Qiskit instrumentation described above. The detailed tables below describe the direct Qiskit and Qrisp integrations.
+
 ### Quantum Circuit
 
 Quantum Circuit provenance describes the structure and characteristics of the quantum circuit being executed.
@@ -149,26 +178,26 @@ Circuit width represents the number of qubits used by the circuit, circuit depth
 
 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     |   ✓    |   ✓   |
+| QProv  | Provenance attribute | Qiskit/UCC | 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                       |   ✓    |   ✓   |
+| Compiler provenance | Description                                       | Qiskit/UCC | 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**.
 

pyproject.toml

@@ -32,6 +32,7 @@ development = ["pre-commit", "pytest", "pytest-cov"]
 
 qiskit = ["qiskit", "qiskit-aer"]
 qrisp = ["qrisp"]
+ucc = ["ucc"]
 
 test = ["mqt.bench", "qiskit<2.2", "mlflow", "iqm-client[qiskit]"]
 [build-system]

src/q8s/runtime/mlflow/qiskit/__init__.py

@@ -16,5 +16,6 @@
 """MLflow autologging integration for Qiskit."""
 
 from q8s.runtime.mlflow.qiskit.autologging import autolog
+from q8s.runtime.mlflow.qiskit.utils import create_autolog
 
-__all__ = ["autolog"]
+__all__ = ["autolog", "create_autolog"]