qiskit.providers.ibmq.IBMQBackend
class IBMQBackend(configuration, provider, credentials, api_client)
Backend class interfacing with an IBM Quantum Experience device.
You can run experiments on a backend using the run()
method. The run()
method takes one or more QuantumCircuit
or Schedule
and returns an IBMQJob
instance that represents the submitted job. Each job has a unique job ID, which can later be used to retrieve the job. An example of this flow:
from qiskit import IBMQ, assemble, transpile
from qiskit.circuit.random import random_circuit
provider = IBMQ.load_account()
backend = provider.backend.ibmq_vigo
qx = random_circuit(n_qubits=5, depth=4)
transpiled = transpile(qx, backend=backend)
job = backend.run(transpiled)
retrieved_job = backend.retrieve_job(job.job_id())
- Unlike
qiskit.execute()
, therun()
method does not transpile the circuits/schedules for you, so be sure to do so before submitting them. - You should not instantiate the
IBMQBackend
class directly. Instead, use the methods provided by anAccountProvider
instance to retrieve and handle backends.
Other methods return information about the backend. For example, the status()
method returns a BackendStatus
instance. The instance contains the operational
and pending_jobs
attributes, which state whether the backend is operational and also the number of jobs in the server queue for the backend, respectively:
status = backend.status()
is_operational = status.operational
jobs_in_queue = status.pending_jobs
It is also possible to see the number of remaining jobs you are able to submit to the backend with the job_limit()
method, which returns a BackendJobLimit
instance:
job_limit = backend.job_limit()
IBMQBackend constructor.
Parameters
- configuration (
Union
[QasmBackendConfiguration
,PulseBackendConfiguration
]) – Backend configuration. - provider (
AccountProvider
) – IBM Quantum Experience account provider - credentials (
Credentials
) – IBM Quantum Experience credentials. - api_client (
AccountClient
) – IBM Quantum Experience client used to communicate with the server.
__init__
__init__(configuration, provider, credentials, api_client)
IBMQBackend constructor.
Parameters
- configuration (
Union
[QasmBackendConfiguration
,PulseBackendConfiguration
]) – Backend configuration. - provider (
AccountProvider
) – IBM Quantum Experience account provider - credentials (
Credentials
) – IBM Quantum Experience credentials. - api_client (
AccountClient
) – IBM Quantum Experience client used to communicate with the server.
Methods
__init__ (configuration, provider, …) | IBMQBackend constructor. |
active_jobs ([limit]) | Return the unfinished jobs submitted to this backend. |
configuration () | Return the backend configuration. |
defaults ([refresh]) | Return the pulse defaults for the backend. |
job_limit () | Return the job limit for the backend. |
jobs ([limit, skip, status, job_name, …]) | Return the jobs submitted to this backend, subject to optional filtering. |
name () | Return the backend name. |
properties ([refresh, datetime]) | Return the backend properties, subject to optional filtering. |
provider () | Return the backend Provider. |
remaining_jobs_count () | Return the number of remaining jobs that could be submitted to the backend. |
reservations ([start_datetime, end_datetime]) | Return backend reservations. |
retrieve_job (job_id) | Return a single job submitted to this backend. |
run (circuits[, job_name, job_share_level, …]) | Run on the backend. |
set_options (**fields) | Set the options fields for the backend |
status () | Return the backend status. |
Attributes
options | Return the options for the backend |
version |
active_jobs
active_jobs(limit=10)
Return the unfinished jobs submitted to this backend.
Return the jobs submitted to this backend, with this provider, that are currently in an unfinished job status state. The unfinished JobStatus
states include: INITIALIZING
, VALIDATING
, QUEUED
, and RUNNING
.
Parameters
limit (int
) – Number of jobs to retrieve.
Return type
List
[IBMQJob
]
Returns
A list of the unfinished jobs for this backend on this provider.
configuration
configuration()
Return the backend configuration.
Backend configuration contains fixed information about the backend, such as its name, number of qubits, basis gates, coupling map, quantum volume, etc.
The schema for backend configuration can be found in Qiskit/ibm-quantum-schemas.
Return type
Union
[QasmBackendConfiguration
, PulseBackendConfiguration
]
Returns
The configuration for the backend.
defaults
defaults(refresh=False)
Return the pulse defaults for the backend.
The schema for default pulse configuration can be found in Qiskit/ibm-quantum-schemas.
Parameters
refresh (bool
) – If True
, re-query the server for the backend pulse defaults. Otherwise, return a cached version.
Return type
Optional
[PulseDefaults
]
Returns
The backend pulse defaults or None
if the backend does not support pulse.
job_limit
job_limit()
Return the job limit for the backend.
The job limit information includes the current number of active jobs you have on the backend and the maximum number of active jobs you can have on it.
Job limit information for a backend is provider specific. For example, if you have access to the same backend via different providers, the job limit information might be different for each provider.
If the method call was successful, you can inspect the job limit for the backend by accessing the maximum_jobs
and active_jobs
attributes of the BackendJobLimit
instance returned. For example:
backend_job_limit = backend.job_limit()
maximum_jobs = backend_job_limit.maximum_jobs
active_jobs = backend_job_limit.active_jobs
If maximum_jobs
is equal to None
, then there is no limit to the maximum number of active jobs you could have on the backend.
Return type
BackendJobLimit
Returns
The job limit for the backend, with this provider.
Raises
IBMQBackendApiProtocolError – If an unexpected value is received from the server.
jobs
jobs(limit=10, skip=0, status=None, job_name=None, start_datetime=None, end_datetime=None, job_tags=None, job_tags_operator='OR', experiment_id=None, descending=True, db_filter=None)
Return the jobs submitted to this backend, subject to optional filtering.
Retrieve jobs submitted to this backend that match the given filters and paginate the results if desired. Note that the server has a limit for the number of jobs returned in a single call. As a result, this function might involve making several calls to the server. See also the skip parameter for more control over pagination.
Parameters
-
limit (
int
) – Number of jobs to retrieve. -
skip (
int
) – Starting index for the job retrieval. -
status (
Union
[JobStatus
,str
,List
[Union
[JobStatus
,str
]],None
]) – Only get jobs with this status or one of the statuses. For example, you can specify status=JobStatus.RUNNING or status=”RUNNING” or status=[“RUNNING”, “ERROR”] -
job_name (
Optional
[str
]) – Filter by job name. The job_name is matched partially and regular expressions can be used. -
start_datetime (
Optional
[datetime
]) – Filter by the given start date, in local time. This is used to find jobs whose creation dates are after (greater than or equal to) this local date/time. -
end_datetime (
Optional
[datetime
]) – Filter by the given end date, in local time. This is used to find jobs whose creation dates are before (less than or equal to) this local date/time. -
job_tags (
Optional
[List
[str
]]) – Filter by tags assigned to jobs. -
job_tags_operator (
Optional
[str
]) –Logical operator to use when filtering by job tags. Valid values are “AND” and “OR”:
- If “AND” is specified, then a job must have all of the tags specified in
job_tags
to be included. - If “OR” is specified, then a job only needs to have any of the tags specified in
job_tags
to be included.
- If “AND” is specified, then a job must have all of the tags specified in
-
experiment_id (
Optional
[str
]) – Filter by job experiment ID. -
descending (
bool
) – IfTrue
, return the jobs in descending order of the job creation date (newest first). IfFalse
, return in ascending order. -
db_filter (
Optional
[Dict
[str
,Any
]]) –A loopback-based filter. This is an interface to a database
where
filter. Some examples of its usage are:Filter last five jobs with errors:
job_list = backend.jobs(limit=5, status=JobStatus.ERROR)
Filter last five jobs with hub name
ibm-q
:filter = {'hubInfo.hub.name': 'ibm-q'} job_list = backend.jobs(limit=5, db_filter=filter)
Return type
List
[IBMQJob
]
Returns
A list of jobs that match the criteria.
Raises
IBMQBackendValueError – If a keyword value is not recognized.
name
name()
Return the backend name.
Returns
the name of the backend.
Return type
str
options
Return the options for the backend
The options of a backend are the dynamic parameters defining how the backend is used. These are used to control the run()
method.
properties
properties(refresh=False, datetime=None)
Return the backend properties, subject to optional filtering.
This data describes qubits properties (such as T1 and T2), gates properties (such as gate length and error), and other general properties of the backend.
The schema for backend properties can be found in Qiskit/ibm-quantum-schemas.
Parameters
- refresh (
bool
) – IfTrue
, re-query the server for the backend properties. Otherwise, return a cached version. - datetime (
Optional
[datetime
]) – By specifying datetime, this function returns an instance of theBackendProperties
whose timestamp is closest to, but older than, the specified datetime.
Return type
Optional
[BackendProperties
]
Returns
The backend properties or None
if the backend properties are not currently available.
Raises
TypeError – If an input argument is not of the correct type.
provider
provider()
Return the backend Provider.
Returns
the Provider responsible for the backend.
Return type
remaining_jobs_count
remaining_jobs_count()
Return the number of remaining jobs that could be submitted to the backend.
The number of remaining jobs for a backend is provider specific. For example, if you have access to the same backend via different providers, the number of remaining jobs might be different for each. See BackendJobLimit
for the job limit information of a backend.
If None
is returned, there are no limits to the maximum number of active jobs you could have on the backend.
Return type
Optional
[int
]
Returns
The remaining number of jobs a user could submit to the backend, with this provider, before the maximum limit on active jobs is reached.
Raises
IBMQBackendApiProtocolError – If an unexpected value is received from the server.
reservations
reservations(start_datetime=None, end_datetime=None)
Return backend reservations.
If start_datetime and/or end_datetime is specified, reservations with time slots that overlap with the specified time window will be returned.
Some of the reservation information is only available if you are the owner of the reservation.
Parameters
- start_datetime (
Optional
[datetime
]) – Filter by the given start date/time, in local timezone. - end_datetime (
Optional
[datetime
]) – Filter by the given end date/time, in local timezone.
Return type
List
[BackendReservation
]
Returns
A list of reservations that match the criteria.
retrieve_job
retrieve_job(job_id)
Return a single job submitted to this backend.
Parameters
job_id (str
) – The ID of the job to retrieve.
Return type
IBMQJob
Returns
The job with the given ID.
Raises
IBMQBackendError – If job retrieval failed.
run
run(circuits, job_name=None, job_share_level=None, job_tags=None, experiment_id=None, validate_qobj=None, header=None, shots=None, memory=None, qubit_lo_freq=None, meas_lo_freq=None, schedule_los=None, meas_level=None, meas_return=None, memory_slots=None, memory_slot_size=None, rep_time=None, rep_delay=None, init_qubits=None, parameter_binds=None, **run_config)
Run on the backend.
If a keyword specified here is also present in the options
attribute/object, the value specified here will be used for this run.
Parameters
-
circuits (
Union
[QasmQobj
,PulseQobj
,QuantumCircuit
,Schedule
,List
[Union
[QuantumCircuit
,Schedule
]]]) – An individual or a list ofQuantumCircuit
orSchedule
objects to run on the backend. AQasmQobj
or aPulseQobj
object is also supported but is deprecated. -
job_name (
Optional
[str
]) – Custom name to be assigned to the job. This job name can subsequently be used as a filter in thejobs()
method. Job names do not need to be unique. -
job_share_level (
Optional
[str
]) –Allows sharing a job at the hub, group, project, or global level. The possible job share levels are:
global
,hub
,group
,project
, andnone
.- global: The job is public to any user.
- hub: The job is shared between the users in the same hub.
- group: The job is shared between the users in the same group.
- project: The job is shared between the users in the same project.
- none: The job is not shared at any level.
If the job share level is not specified, the job is not shared at any level.
-
job_tags (
Optional
[List
[str
]]) – Tags to be assigned to the job. The tags can subsequently be used as a filter in thejobs()
function call. -
experiment_id (
Optional
[str
]) – Used to add a job to an “experiment”, which is a collection of jobs and additional metadata. -
validate_qobj (
Optional
[bool
]) – DEPRECATED. IfTrue
, run JSON schema validation against the submitted payload. Only applicable if a Qobj is passed in. -
following arguments are NOT applicable if a Qobj is passed in. (The) –
-
header (
Optional
[Dict
]) – User input that will be attached to the job and will be copied to the corresponding result header. Headers do not affect the run. This replaces the oldQobj
header. -
shots (
Optional
[int
]) – Number of repetitions of each circuit, for sampling. Default: 1024 ormax_shots
from the backend configuration, whichever is smaller. -
memory (
Optional
[bool
]) – IfTrue
, per-shot measurement bitstrings are returned as well (provided the backend supports it). For OpenPulse jobs, only measurement level 2 supports this option. -
qubit_lo_freq (
Optional
[List
[int
]]) – List of default qubit LO frequencies in Hz. Will be overridden byschedule_los
if set. -
meas_lo_freq (
Optional
[List
[int
]]) – List of default measurement LO frequencies in Hz. Will be overridden byschedule_los
if set. -
schedule_los (
Union
[List
[Union
[Dict
[PulseChannel
,float
],LoConfig
]],Dict
[PulseChannel
,float
],LoConfig
,None
]) – Experiment LO configurations, frequencies are given in Hz. -
meas_level (
Union
[int
,MeasLevel
,None
]) – Set the appropriate level of the measurement output for pulse experiments. -
meas_return (
Union
[str
,MeasReturnType
,None
]) –Level of measurement data for the backend to return.
For
meas_level
0 and 1:single
returns information from every shot.avg
returns average measurement output (averaged over number of shots).
-
memory_slots (
Optional
[int
]) – Number of classical memory slots to use. -
memory_slot_size (
Optional
[int
]) – Size of each memory slot if the output is Level 0. -
rep_time (
Optional
[int
]) – Time per program execution in seconds. Must be from the list provided by the backend (backend.configuration().rep_times
). Defaults to the first entry. -
rep_delay (
Optional
[float
]) – Delay between programs in seconds. Only supported on certain backends (ifbackend.configuration().dynamic_reprate_enabled=True
). If supported,rep_delay
will be used instead ofrep_time
and must be from the range supplied by the backend (backend.configuration().rep_delay_range
). Default is given bybackend.configuration().default_rep_delay
. -
init_qubits (
Optional
[bool
]) – Whether to reset the qubits to the ground state for each shot. Default:True
. -
parameter_binds (
Optional
[List
[Dict
[Parameter
,float
]]]) – List of Parameter bindings over which the set of experiments will be executed. Each list element (bind) should be of the form {Parameter1: value1, Parameter2: value2, …}. All binds will be executed across all experiments; e.g., if parameter_binds is a length-n list, and there are m experiments, a total of m x n experiments will be run (one for each experiment/bind pair). -
**run_config – Extra arguments used to configure the run.
Return type
IBMQJob
Returns
The job to be executed.
Raises
- IBMQBackendApiError – If an unexpected error occurred while submitting the job.
- IBMQBackendApiProtocolError – If an unexpected value received from the server.
- IBMQBackendValueError – If an input parameter value is not valid.
set_options
set_options(**fields)
Set the options fields for the backend
This method is used to update the options of a backend. If you need to change any of the options prior to running just pass in the kwarg with the new value for the options.
Parameters
fields – The fields to update the options
Raises
AttributeError – If the field passed in is not part of the options
status
status()
Return the backend status.
If the returned BackendStatus
instance has operational=True
but status_msg="internal"
, then the backend is accepting jobs but not processing them.
Return type
BackendStatus
Returns
The status of the backend.
Raises
IBMQBackendApiProtocolError – If the status for the backend cannot be formatted properly.