q8s.runtime

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, UCC and Qrisp. This makes it possible to collect and analyse execution and compilation information consistently across different quantum software stacks.

Installation

Install the core package using:

pip install q8s.runtime

Support for individual quantum development kits can be installed using the corresponding optional dependencies:

pip install "q8s.runtime[qiskit]"
pip install "q8s.runtime[qrisp]"
pip install "q8s.runtime[ucc]"

Multiple integrations can be installed together:

pip install "q8s.runtime[qiskit,qrisp,ucc]"

Integrations

Qiskit

The Qiskit integration provides adapters for Qiskit objects and automatic experiment tracking through MLflow.

MLflow autologging

Qiskit transpilation and execution can be automatically captured by enabling autologging:

import mlflow
from mqt.bench import BenchmarkLevel, get_benchmark
from q8s.runtime.mlflow.qiskit import autolog

autolog()

from iqm.qiskit_iqm.fake_backends.fake_aphrodite import IQMFakeAphrodite
from qiskit.transpiler import generate_preset_pass_manager

mlflow.set_experiment("qiskit-transpilation")


with mlflow.start_run():
    qc = get_benchmark(
        benchmark="qft",
        level=BenchmarkLevel.ALG,
        circuit_size=30,
    )

    backend = IQMFakeAphrodite()

    manager = generate_preset_pass_manager(
        optimization_level=3, backend=backend, seed_transpiler=42
    )

    tqc = manager.run(qc)

    job = backend.run(tqc, shots=1024, memory=True)

    result = job.result()

    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.

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)

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:

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

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	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.

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/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/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.

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.