BatchedBackend#

class BatchedBackend(backend: Backend, name: str | None = None)[source]#

A class that buffers circuit submissions and executes them on an explicit dispatch() call.

Obtain an instance via batched():

batched_backend = my_backend.batched()

How it works

Each call to run() registers the circuit in an internal queue and returns a MeasurementResult immediately. The result is lazy: its data is not available until dispatch() is called. Accessing the result before dispatch raises RuntimeError.

After dispatch(), every pending MeasurementResult is populated with raw bitstring counts by forwarding each circuit to the wrapped backend’s run_async(). Higher-level decoding (performed by QuantumVariable.get_measurement) is deferred until the user actually reads the decoded result.

Note

BatchedBackend is not thread-safe. run() and dispatch() must be called from the same thread. Concurrent calls from multiple threads can silently drop queued circuits.

Parameters:

backendBackend: The backend whose run_async() is called with all queued circuits when dispatch() is invoked.
namestr or None: Optional name for this backend.

Examples

In this example, we collect two measurements, then dispatch:

from qrisp import QuantumFloat
from qrisp.default_backend import QrispSimulatorBackend

backend = QrispSimulatorBackend()
batched_backend = backend.batched()

a = QuantumFloat(4); a[:] = 1
b = QuantumFloat(3); b[:] = 2
c = a + b

d = QuantumFloat(4); d[:] = 2
e = QuantumFloat(3); e[:] = 3
f = d + e

res_c = c.get_measurement(backend=batched_backend)  # lazy (returns immediately)
res_f = f.get_measurement(backend=batched_backend)  # lazy (returns immediately)

batched_backend.dispatch()  # runs both circuits, then populates results

print(res_c)  # {3: 1.0}
print(res_f)  # {5: 1.0}

The same pattern is available via batched_measurement():

from qrisp import batched_measurement
results = batched_measurement([c, f], backend=batched_backend)
print(results)  # [{3: 1.0}, {5: 1.0}]

Properties#

`BatchedBackend.options`	Current runtime options (read-only).
`BatchedBackend.pending_count`	Number of circuits currently queued, waiting for `dispatch()`.

Methods#

`BatchedBackend.run`()	Register one or more circuits in the queue and return lazy result(s).
`BatchedBackend.dispatch`([timeout])	Execute all pending circuits and populate their results.
`BatchedBackend.update_options`(**kwargs)	Update existing runtime options.
`BatchedBackend.clear`()	Discard all queued circuits without dispatching.