Refactoring of the Qrisp Backend structure by PietropaoloFrisoni · Pull Request #331 · eclipse-qrisp/Qrisp

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

src/qrisp/interface/backend.py

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 ?

The backend might also solve this issue (that is, inspect the final circuits that would be submitted for execution before actually submitting them, which can be useful for debugging purposes) with another method such as create_run_request (as IQMBackend currently does). I would not add this method to the base class though

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 :)

Aerylia

Comments from todays meeting

.github/workflows/qrisp_test.yml

Aerylia · 2025-12-18T09:39:25Z

src/qrisp/default_backend.py

+    def run(self, circuit, **kwargs):
+        shots = kwargs.get("shots", self.options.get("shots", None))
+        token = kwargs.get("token", self.options.get("token", ""))
+        return default_run(circuit, shots, token)


Suggested change

def run(self, circuit, **kwargs):

shots = kwargs.get("shots", self.options.get("shots", None))

token = kwargs.get("token", self.options.get("token", ""))

return default_run(circuit, shots, token)

def run(self, circuit, *, shots) -> Job:

token = self._default_options[token] # This should probably get the options from the specific instance

return default_run(circuit, shots, token)

def run_await_results(self, circuit, *, shots, timeout=1000) -> dict[str, int]:

return run(self, circuit, shots=shots).results(timeout=timeout)

Job here should be an abstract class that you can query for results so that it can be run asynchronously

bastibock · 2025-12-18T11:04:42Z

First of all: thank you everyone for your efforts so far in refactoring the backend class.
I followed your discussions here and also think that this is absolutely necessary!

However, as indicated in your comments, there are some open points, that could and should be discussed together, to shape the backend class, and also the compilation pipeline (where does what step of compilation/transpilation take place), in an optimal way.

Maybe we could start a discussion together about this topic in the beginning of next year.

PietropaoloFrisoni · 2025-12-18T11:20:30Z

Hi @bastibock, nice to meet you!
Sure, the plan was to keep you guys in the loop and discuss with you very soon : )

Right now, we are getting very useful feedback from IQM's devs and Product Team, who have a lot of experience with real physical quantum backends and therefore can provide good suggestions for such a class.

Happy to talk to you next year!

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

Testing new changes for the full test suite

34e337b

PietropaoloFrisoni added 2 commits December 17, 2025 14:33

Modify signature in run calling

ce7b4b5

Improvements and clarifications to docstrings of the class

5b337ef

PietropaoloFrisoni changed the title ~~Refactoring of the Qrisp Backend Class~~ Refactoring of the Qrisp Backend structure Dec 17, 2025

Aerylia reviewed Dec 18, 2025

View reviewed changes

PietropaoloFrisoni added 2 commits December 22, 2025 16:09

Final signature for run and documentation updates plus explanations

113bb91

Docstring clarification

b48b31f



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

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!

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!

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!

Aerylia left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bastibock commented Dec 18, 2025

Uh oh!

PietropaoloFrisoni commented Dec 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PietropaoloFrisoni commented Nov 30, 2025 •

edited

Loading