Backend

class Backend(name: str | None = None, options: Mapping | None = None, **kwargs)

Abstract base class for Qrisp-compatible backends.

This class provides a minimal, hardware-agnostic interface that all backends (simulators or quantum hardware clients) must follow.

The only mandatory method for child classes is run_async(), which submits one or more circuits for execution and returns a Job handle immediately. The caller then decides when to wait for the result by calling Job.result.

A synchronous run() method is also provided. It calls run_async() internally, blocks until the job completes, and returns the results as MeasurementResult objects. This is the standard execution path for most users, and is what get_measurement() uses internally. Use run_async() directly only when you need the Job handle itself (e.g. to poll status, cancel, or wait concurrently).

Design contract

The Backend class defines the minimal execution interface required by Qrisp. It does not assume universality of the gate set, specific connectivity constraints, or the presence of calibration data. Any such assumptions must be made explicit by concrete backend implementations or higher-level compilation policies.

This class intentionally avoids prescribing compilation, scheduling, or execution policies, which are delegated to concrete backends or external components.

For example, simulators are expected to implement run_async() but may return None for all hardware metadata properties.

Execution model

run_async() accepts a single circuit or a sequence of circuits and always returns a Job instance immediately. This follows the Future pattern: execution happens independently of the caller, and the caller decides when to block by calling Job.result.

run() is the standard synchronous execution path. It blocks until execution completes and returns the measurement results (one per submitted circuit).

Runtime options

Runtime options describe how the backend executes circuits (e.g. the number of shots). These can be provided:

• by overriding _default_options() at class level, or

• by passing a custom options mapping to __init__().

The number of shots may also be overridden per-execution by passing the shots argument to run_async() or run(). It is treated as a conventional execution parameter for gate-based, shot-based backends, and may be ignored by backends for which it is not meaningful.

Options are updated through update_options(), but only keys that were present at initialisation may be modified.

Hardware metadata

The backend may optionally expose hardware metadata such as:

• backend health or diagnostics,

• backend queue status,

• number of qubits,

• connectivity information,

• supported native gates,

• gate errors or calibration data.

These properties are intentionally left loosely typed at the base-class level. Their purpose is to signal the presence of a capability, not to enforce a universal hardware schema.

The absence of a value for a given property (None) explicitly means “capability not exposed by this backend”. This is common for simulators, abstract backends, or backends that choose not to provide hardware details.

Concrete backend implementations (e.g. vendor-specific backends) are expected to override these properties and may return structured, vendor-defined objects with richer semantics. Transpilers or compilation passes may then either:

• require specific capabilities and raise if they are missing, or

• ignore hardware metadata entirely and operate in a backend-agnostic mode.

Backend-specific capabilities that are not covered by the base interface should be exposed as concrete typed properties on the subclass.

Parameters:

namestr or None

Optional user-defined name for the backend. Defaults to the class name.

optionsMapping or None

Runtime execution options for the backend. If omitted, _default_options() is used.

**kwargs

Additional backend-specific parameters. These are not defined at the base-class level but may be accepted by concrete backend implementations (e.g. for authentication, provider selection, or other configuration).

Methods

Backend.__init__([name, options])	Initialise the backend.
Backend.run_async(circuits[, shots])	Submit one or more circuits for execution and return a Job.
Backend.run()	Submit one or more circuits, block until completion, and return results.
Backend.retrieve_job(job_id)	Reconnect to a previously submitted job by its identifier.
Backend.batched()	Return a BatchedBackend that wraps this backend.

Runtime options

Backend.options	Current runtime options for the backend.
Backend.update_options(**kwargs)	Update existing runtime options for the backend.
Backend._default_options()	Default runtime options for the backend.

Hardware status information

Backend.health	Current health status or diagnostics of the backend.
Backend.info	General information about the backend.
Backend.queue	Current queue status or job backlog of the backend.

Hardware metadata

Backend.num_qubits	Total number of physical qubits the backend exposes.
Backend.max_circuits	Maximum number of circuits this backend can execute in a single job.
Backend.connectivity	Currently executable qubit connectivity for the backend.
Backend.gate_set	Native gate set supported by the backend.
Backend.error_rates	Error rates or calibration-related information for the backend.