qrunch.quantum.backends.backend_callbacks

Module defining the BackendCallback protocol and concrete implementations.

Classes

`BackendCallback`	Protocol for a callback that can be called at various stages of backend execution.
`CompositeBackendCallback`	A backend callback that delegates to a list of callbacks, calling each in order.
`LogTopStatesBackendCallback`	A backend callback that logs the most frequently measured states after each job completes.
`SaveCircuitsOnFailureBackendCallback`	A backend callback that saves input circuits to a file when a job fails.
`StoreEverythingBackendCallback`	A backend callback that stores all inputs and jobs for later inspection.

class BackendCallback

Bases: Protocol

Protocol for a callback that can be called at various stages of backend execution.

__init__(*args, **kwargs)

record_backend_jobs(jobs: Sequence[BackendJob]) → None

Record the job object representing the execution of a circuit on the backend.

This allows the callback to capture details about the job submission, such as timing, resource usage, or any metadata associated with the job.

Parameters:: jobs (Sequence[BackendJob]) – The job objects returned by the backend upon submission of circuits for execution.
Return type:: None

record_circuits(circuits: Sequence[Circuit], compiled_circuits: Sequence[UniversalGateCircuit], transpiled_circuits: Sequence[Any]) → None

Record the input circuit sent to the backend.

The circuit is given after layout synthesis and compilation, but before any backend-specific optimizations or transformations. This allows the callback to capture as close to the exact circuit that is sent to the backend for execution.

Parameters:

circuits (Sequence[Circuit]) – The circuit(s) sent to the backend for execution.
compiled_circuits (Sequence[UniversalGateCircuit]) – The compiled version of the circuits.
transpiled_circuits (Sequence[Any]) – The transpiled version of the circuits. The class used for this is backend-specific.

Return type:

None

record_measurement_results(measurements: Sequence[QuantumMeasurement]) → None

Record the measurement result obtained from executing a circuit on the backend.

The measurement recorded here is strait from the backend and, therefore, before any layout unmapping. The mapped result can be optained from the backend job, which is recorded in the record_backend_job callback.

Parameters:: measurements (Sequence[QuantumMeasurement]) – The measurement results obtained from the backend execution.
Return type:: None

class CompositeBackendCallback

Bases: BackendCallback

A backend callback that delegates to a list of callbacks, calling each in order.

__init__(callbacks: Sequence[BackendCallback]) → None

Initialize the composite callback.

Parameters:: callbacks (Sequence[BackendCallback]) – The callbacks to delegate to.
Return type:: None

record_backend_jobs(jobs: Sequence[BackendJob]) → None

Delegate to all callbacks.

Parameters:: jobs (Sequence[BackendJob]) – The jobs to pass to each callback.
Return type:: None

record_circuits(circuits: Sequence[Circuit], compiled_circuits: Sequence[UniversalGateCircuit], transpiled_circuits: Sequence[Any]) → None

Delegate to all callbacks.

Parameters:

circuits (Sequence[Circuit]) – The circuit(s) to pass to each callback.
compiled_circuits (Sequence[UniversalGateCircuit]) – The compiled version of the circuits.
transpiled_circuits (Sequence[Any]) – The transpiled version of the circuits. The class used for this is backend-specific.

Return type:

None

record_measurement_results(measurements: Sequence[QuantumMeasurement]) → None

Delegate to all callbacks.

Parameters:: measurements (Sequence[QuantumMeasurement]) – The measurements to pass to each callback.
Return type:: None

class LogTopStatesBackendCallback

Bases: BackendCallback

A backend callback that logs the most frequently measured states after each job completes.

__init__(number_of_states_to_log: int = 5) → None

Initialize the callback.

Parameters:: number_of_states_to_log (int) – Number of top states to log. Defaults to 5.
Return type:: None

record_backend_jobs(jobs: Sequence[BackendJob]) → None

Record the job object representing the execution of a circuit on the backend.

This allows the callback to capture details about the job submission, such as timing, resource usage, or any metadata associated with the job.

Parameters:: jobs (Sequence[BackendJob]) – The job objects returned by the backend upon submission of circuits for execution.
Return type:: None

record_circuits(circuits: Sequence[Circuit], compiled_circuits: Sequence[UniversalGateCircuit], transpiled_circuits: Sequence[Any]) → None

Record the input circuit sent to the backend.

The circuit is given after layout synthesis and compilation, but before any backend-specific optimizations or transformations. This allows the callback to capture as close to the exact circuit that is sent to the backend for execution.

Parameters:

circuits (Sequence[Circuit]) – The circuit(s) sent to the backend for execution.
compiled_circuits (Sequence[UniversalGateCircuit]) – The compiled version of the circuits.
transpiled_circuits (Sequence[Any]) – The transpiled version of the circuits. The class used for this is backend-specific.

Return type:

None

record_measurement_results(measurements: Sequence[QuantumMeasurement]) → None

Log the top measured states for each measurement.

Parameters:: measurements (Sequence[QuantumMeasurement]) – The measurements to log top states from.
Return type:: None

class SaveCircuitsOnFailureBackendCallback

Bases: BackendCallback

A backend callback that saves input circuits to a file when a job fails.

__init__(output_path: Path) → None

Initialize the callback.

Parameters:: output_path (Path) – Path to the file where QASM representations of the circuits will be written on failure.
Return type:: None

record_backend_jobs(jobs: Sequence[BackendJob]) → None

Wait for each job to complete and save circuits to file if the job failed.

Parameters:: jobs (Sequence[BackendJob]) – The jobs to check for failure.
Return type:: None

record_circuits(circuits: Sequence[Circuit], compiled_circuits: Sequence[UniversalGateCircuit], transpiled_circuits: Sequence[Any]) → None

Store the input circuits for later use.

Parameters:

circuits (Sequence[Circuit]) – The circuit(s) to store.
compiled_circuits (Sequence[UniversalGateCircuit]) – The compiled version of the circuits.
transpiled_circuits (Sequence[Any]) – The transpiled version of the circuits. The class used for this is backend-specific.

Return type:

None

record_measurement_results(measurements: Sequence[QuantumMeasurement]) → None

Record the measurement result obtained from executing a circuit on the backend.

The measurement recorded here is strait from the backend and, therefore, before any layout unmapping. The mapped result can be optained from the backend job, which is recorded in the record_backend_job callback.

Parameters:: measurements (Sequence[QuantumMeasurement]) – The measurement results obtained from the backend execution.
Return type:: None

class StoreEverythingBackendCallback

Bases: BackendCallback

A backend callback that stores all inputs and jobs for later inspection.

__init__() → None

Initialize the callback with empty storage.

Return type:: None

record_backend_jobs(jobs: Sequence[BackendJob]) → None

Store the backend jobs.

Parameters:: jobs (Sequence[BackendJob]) – The jobs to store.
Return type:: None

record_circuits(circuits: Sequence[Circuit], compiled_circuits: Sequence[UniversalGateCircuit], transpiled_circuits: Sequence[Any]) → None

Store the input circuits.

Parameters:

circuits (Sequence[Circuit]) – The circuit(s) sent to the backend for execution.
compiled_circuits (Sequence[UniversalGateCircuit]) – The compiled version of the circuits.
transpiled_circuits (Sequence[Any]) – The transpiled version of the circuits. The class used for this is backend-specific.

Return type:

None

record_measurement_results(measurements: Sequence[QuantumMeasurement]) → None

Store the measurement results.

Parameters:: measurements (Sequence[QuantumMeasurement]) – The measurements to store.
Return type:: None