CircuitRunner

class CircuitRunner(shots, track_depth=False)

Bases: ABC

A generic interface for anything that can “run” quantum circuits.

Attributes Summary

depth_history	Circuit depth per batch when track_depth is True.
is_async	Whether the backend executes circuits asynchronously.
shots	Get the number of measurement shots for circuit execution.
supports_expval	Whether the backend supports expectation value measurements.

Methods Summary

average_depth()	Average circuit depth across all tracked submissions.
clear_depth_history()	Clear the depth history.
set_seed(seed)	Seed the backend's random number generator, if supported.
std_depth()	Standard deviation of circuit depth across all tracked submissions.
submit_circuits(circuits, *[, ...])	Submit quantum circuits for execution.

Attributes Documentation

depth_history

Circuit depth per batch when track_depth is True.

Each element is a list of depths (one per circuit) for that submission. Empty when track_depth is False or before any circuits have been run.

is_async

Whether the backend executes circuits asynchronously.

Returns:

True if the backend returns a job ID and requires polling

for results (e.g., QoroService). False if the backend returns results immediately (e.g., QiskitSimulator).

Return type:

bool

shots

Get the number of measurement shots for circuit execution.

Returns:

Number of shots configured for this runner.

Return type:

int

supports_expval

Whether the backend supports expectation value measurements.

Methods Documentation

average_depth()

Average circuit depth across all tracked submissions.

Returns 0.0 when depth history is empty.

Return type:

float

clear_depth_history()

Clear the depth history. Use when reusing the backend for a new run.

Return type:

None

set_seed(seed)

Seed the backend’s random number generator, if supported.

The default implementation is a no-op. Backends that can seed their simulation RNG should override this method.

Parameters:

seed (int) – Seed value for the backend’s RNG.

Return type:

None

std_depth()

Standard deviation of circuit depth across all tracked submissions.

Returns 0.0 when depth history is empty or has a single value.

Return type:

float

abstractmethod submit_circuits(circuits, *, cancellation_event=None, **kwargs)

Submit quantum circuits for execution.

This abstract method must be implemented by subclasses to define how circuits are executed on their respective backends (simulator, hardware, etc.).

Parameters:

• circuits (Mapping[str, str]) – Dictionary mapping circuit labels to their OpenQASM string representations.

• cancellation_event (Event | None) – When set, the backend aborts the batch and raises ExecutionCancelledError. Sync backends honour it between items; async backends thread it into their poll loop.

• **kwargs – Additional backend-specific parameters for circuit execution.

Returns:

For synchronous backends, contains results directly.

For asynchronous backends, contains a job_id that can be used to fetch results later.

Return type:

ExecutionResult