Refactoring of the Qrisp Backend Class #331

PietropaoloFrisoni · 2025-11-30T13:51:03Z

Context: The current backend implementation in Qrisp works as an extremely abstract "one-fits-all" tool. Essentially, the only existing feature is to send quantum circuits and receive results.

Furthermore, it is embedded into a network interface that was part of a requirement of the SeQuenC project during the early stages of Qrisp. This network interface eventually never used and should now be deprecated.

Description of the Change:

We introduce a custom QrispDeprecationWarning in a new module.
We use the new QrispDeprecationWarning to deprecate the current BackendClient, BackendServer, and VirtualBackend classes (as well as a few other functionalities that were already marked as deprecated).
We introduce a new Backend class in a new module (the latter is described in the associated docstring).
We modify all the existing backends so that they inherit from Backend rather than the deprecated backends. These are DefaultBackend, BatchedBackend, and QiskitBackend. A few backends are excluded from this: QiskitRuntimeBackend (since I do not have an IBM token to test it) and all the docker backends.
We introduce a new qiskit-ibm-runtime dependency to test a specific backend for QiskitBackend (this test was commented out), and we replace qiskit-iqm with iqm-client[qiskit] (as the former was causing the following error: RuntimeError: The qiskit-iqm package is obsolete (...))
Finally, the changes implemented in this PR are also part of the associated PR in the plasma_sabre repository on GitLab (I cannot link it here as it is part of IQM Finland).

Benefits: Much better structure and deprecated Qunicorn servers.

Possible Drawbacks: We cannot exclude at 100% edge-case incompatibilities with the backends we could not test because of missing tokens and api accesses (especially considering that several tests were missing and/or commented out).

Related GitHub Issues: None

positr0nium · 2025-11-30T14:00:57Z

It is important to mention here that this is specifically not intended to fit "only" IQM Backends but we are dedicated to make this as vendor agnostic as possible. Any input or features request from within or outside of the Qrisp development community is welcome.

…w one

…kage version)

Aerylia

Summary of changes proposed/discussed during the meeting today

src/qrisp/interface/backend.py

Aerylia · 2025-12-11T09:55:26Z

src/qrisp/interface/backend.py

+    # ----------------------------------------------------------------------
+
+    @abstractmethod
+    def run(self, *args, **kwargs) -> Any:


This needs to be more precise so that users can call the run method with similar signature on different Backend child classes. e.g. circuit

I agree. So far I simply specified one more positional argument for the qrisp quantum circuit to execute, but we can revise this if needed (it is also related to the batched backend discussion)

Aerylia · 2025-12-11T09:57:20Z

src/qrisp/interface/backend.py

+    @classmethod
+    def _default_options(cls) -> Mapping:
+        """
+        Default runtime options for the backend.
+
+        Child classes may override this method to provide custom default options,
+        or the defaults may be overridden entirely by passing an ``options``
+        mapping to the constructor.
+        """
+        return {"shots": 1024}
+
+    @property
+    def options(self):
+        """Current runtime options."""
+        return self._options
+
+    def update_options(self, **kwargs) -> None:
+        """Update existing runtime options, rejecting unknown keys."""
+
+        for key, val in kwargs.items():
+            if key not in self._options:
+                raise AttributeError(
+                    f"'{key}' is not a valid backend option for {self.__class__.__name__}. "
+                    f"Valid options: {list(self._options.keys())}"
+                )
+            self._options[key] = val
+


This options construct causes ambiguities with the kwargs in Backend.run. It is probably better to not use them in favour of specifying the run options and their defaults in the overloaded run(self, ..., shots=1024) method.

Thanks for putting in these comments! This point might have slipped me during the discussion. I don't think allowing kwargs in .run is the preferable architecture because several Qrisp implementations call the .run without the user getting the chance to interfere. This is for instance the case for many algorithms like QAOA or VQE. In other words the .run call is part of the algorithm implementation and can not be modified by the user. If the user wants to try out a different set of options, they can not modify with this architecture. Having the options as a backend attribute therefore seems the more attractive approach.

Ah, yeah, if that is how the architecture works, then options would be best, but the kwargs should then not be used for user level options

But that would also mean that we would want a strictly fixed function architecture for run

Thanks for the comments. I would keep these runtime options in place for the moment.

In case of overlap with run-time options provided to run (as in your example run(self, ..., shots=1024)), we probably just need to clarify what is the priority. In this case, it seems to me that the options provided to the run function directly (if present) should have the higher priority.

Aerylia · 2025-12-11T09:59:03Z

src/qrisp/interface/backend.py

+            self._options[key] = val
+
+    # ----------------------------------------------------------------------
+    # Optional hardware/backend-specific metadata


These properties should at least be typed and they can only return None if that is meaningful. i.e. what does it mean for a backend to have backend.num_qubits is None ? And how would the transpiler deal with that?

(see answer below regarding hardware metadata)

Aerylia · 2025-12-11T10:01:21Z

src/qrisp/interface/backend.py

+        return None
+
+    @property
+    def error_rates(self):


These are calibration dependent, we probably want the backend to somehow track which calibrated state of the hardware it is refering to.

(see answer below regarding hardware metadata)

Aerylia · 2025-12-11T10:11:07Z

src/qrisp/interface/batched_backend.py



-class BatchedBackend(VirtualBackend):
+class BatchedBackend(Backend):


We probably want to merge this with the regular backend with a run_batched that by default sequentially calls the run method and can be overloaded by a child instance.

Right now, this BatchedBackend class inherits from Backend, but takes care of:

Enqueuing the backend calls from multiple threads

Synchronizing multiple threads

Dispatching the batch to the backend

Therefore, it acts primarily as a scheduler / execution coordinator, not as a real backend in the strict sense (i.e. an object that defines execution semantics for a single circuit).

I don't think this should inherit from Backend (this was the quickest solution to make tests passing since it was inheriting from VirtualBackend before, which now is deprecated), but I am also not convinced about putting everything into a unique Backend class.

If we do that, then we need to take care of execution semantics, batching strategy, scheduling and sync. in the same class, which might be a little too messy.

I think this is something we should revisit once the design of the Backend class is fully finalized.

Agreed! We should also gather feedback on how necessary the batching feature is (both from benchmarks and stakeholder interaction). According to Joni (SWE at IQM) the overhead from executing non-batched got significantly reduced.

Aerylia · 2025-12-11T10:11:29Z

src/qrisp/interface/backend.py

+        return None
+
+    @property
+    def connectivity(self):


Can this connectivity graph be disconnected?

One single connected component, up to vendor to decide which one. e.g. largest of best qubits

(see answer below regarding hardware metadata)

Aerylia · 2025-12-11T10:23:43Z

src/qrisp/interface/backend.py

+        return None
+
+    @property
+    def gate_set(self):


How to deal with overlapping gate sets in the connectivity. e.g. some pairs with CZ, some pairs with iSWAP, some pairs with both.

(see answer below regarding hardware metadata)

Aerylia · 2025-12-11T10:28:49Z

src/qrisp/interface/backend.py

+
+    @property
+    def gate_set(self):
+        """Set of gates supported by the backend."""


What are the assumptions of the universality of the gate set or the qubits? Are qubits assumed to have a measurement implemented? - Document these assumptions

(see answer below regarding hardware metadata)

Aerylia · 2025-12-11T10:33:23Z

src/qrisp/interface/backend.py

+    # ----------------------------------------------------------------------
+
+    @abstractmethod
+    def run(self, *args, **kwargs) -> Any:


If transpilation is done as part of the run, we will need run(..., transpile_method=Somefunc/object) and we will also want a backend.transpile() that is used in the run() so that users can inspect the transpile result before running the circuit on the hardware.

Thanks for bringing this up. Conceptually, I would like to keep transpilation and execution as distinct phases. That is, keep them separable and inspectable. At the same time, I agree that for usability reasons run() may invoke transpilation as a convenience. If that is the case, the run method can be overridden by specifying this keyword argument.

A possible design is to expose a backend.transpile() in this class.

For example, in the PlasmaSabre package we indeed have a transpile_to_iqm function, and I don't see why we cannot implement it in the IQM backend as concrete implementation of the transpile method. But I do not have a lot of experience with transpilation processes for different backends.

What do you think @positr0nium ?

PietropaoloFrisoni · 2025-12-15T14:09:05Z

I reply here regarding the observations about the hardware metadata (gate_set, connectivity, etc.).

Thanks for the very good observations! I agree that raw properties such as num_qubits, gate_set, etc. are insufficient to fully capture real hardware characteristics.

I think the intent of the base Backend class should be to define only the 'execution contract', while keeping hardware description optional and flexible. It seems to me that hardware-specific information is most of the time vendor-dependent, and different vendors already expose this information through their own typed capability objects, all of which may be absent or irrelevant for simulators. The (abstract) base Backend therefore needs to accommodate all these scenarios without enforcing a single universal structure.

In practice, I would like vendor backends to reuse data structures already provided by the vendor whenever possible. For example, in the case of IQM, we have an IQMBackend inheriting from Backend (currently in the PlasmaSabre package on GitLab), which seems the appropriate place to introduce hardware-specific typing and semantics suitable for IQM. In that context, we can keep using the existing IQM data structures for calibration sets, connectivity, etc., while avoiding typing those properties too narrowly in the base class.

In this model, I think None for hardware metadata should be interpreted as “capability not exposed”. The transpiler can then either require specific capabilities (and raise if they are missing) or ignore them, depending on the mode. For simulators, these can simply be None.
Connectivity selection, overlapping gate availability, calibration identity, and similar concerns can therefore be handled by backend-specific implementations or higher-level policies, keeping the core Backend interface fully hardware-agnostic.

I agree that, in this context, the Backend class might seem too generic, but at the moment I'm not sure how to combine this extreme flexibility with a more rigid structure. Obviously, all of this will need to be explained in the documentation :)

PietropaoloFrisoni added 2 commits November 30, 2025 14:50

E.C.

83ab0d8

[ci skip]

865bc01

PietropaoloFrisoni added 19 commits December 1, 2025 11:21

Pylint + isort + black in iqm_backend [ci-skip]

a07d5d6

Minimal doc change in BatchedBackend class

860adf4

BatchedBackend no longer inherits from VirtualBackend

3798911

Trying to move some backends with this new structure

2b80397

Converting QiskitBackend(s) wth the new Backend class

26a2605

Tests for overriding options

2e39251

Refactoring IQM tests

2804aba

Refactoring BatchedBackend test

a33a29a

Trying to cange default Backend in qrisp so that inherits from the ne…

6276969

…w one

Commenting out problematic deps in tests for now

ccb8c38

Adding new dependency for qiskit test(s)

0a6841d

Illuminazione, o solo illusione?

5aaa511

Merge branch 'main' into NewBackendClass

335298d

Moving pip install so that qiskit-iqm downgrades qiskit version

73cfc49

Disabling iqm mocking test (no longer working after update to the pac…

cf6b916

…kage version)

New QrispDeprecation message + Deprecation of old backend infrastructure

0e8741d

Updates to IQM tests

4133a79

Necessary restriction on qiskit-iqm version

59f97fc

Replacing installation of iqm-qiskit with new package

9d08c95

Aerylia reviewed Dec 11, 2025

View reviewed changes

PietropaoloFrisoni added 5 commits December 15, 2025 16:34

Bunch of modifications after first discussion

d59e974

NumPy version restriction

6f36296

Merge branch 'main' into NewBackendClass

4193a0c

Trying to fix Numba import error

304534f

Trying to fix Numba import error

960c172



		class BatchedBackend(VirtualBackend):
		class BatchedBackend(Backend):

Refactoring of the Qrisp Backend Class #331

Are you sure you want to change the base?

Refactoring of the Qrisp Backend Class #331

Uh oh!

Conversation

PietropaoloFrisoni commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

positr0nium commented Nov 30, 2025

Uh oh!

Aerylia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PietropaoloFrisoni commented Dec 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

PietropaoloFrisoni commented Nov 30, 2025 •

edited

Loading