IBMCircuitJob#

class IBMCircuitJob(backend, api_client, job_id, creation_date=None, status=None, runtime_client=None, kind=None, name=None, time_per_step=None, result=None, error=None, session_id=None, tags=None, run_mode=None, client_info=None, **kwargs)[source]#

Representation of a job that executes on an IBM Quantum backend.

The job may be executed on a simulator or a real device. A new IBMCircuitJob instance is returned when you call IBMBackend.run() to submit a job to a particular backend.

If the job is successfully submitted, you can inspect the job’s status by calling status(). Job status can be one of the JobStatus members. For example:

from qiskit.providers.jobstatus import JobStatus

job = backend.run(...)

try:
    job_status = job.status()  # Query the backend server for job status.
    if job_status is JobStatus.RUNNING:
        print("The job is still running")
except IBMJobApiError as ex:
    print("Something wrong happened!: {}".format(ex))

Note

An error may occur when querying the remote server to get job information. The most common errors are temporary network failures and server errors, in which case an IBMJobApiError is raised. These errors usually clear quickly, so retrying the operation is likely to succeed.

Some of the methods in this class are blocking, which means control may not be returned immediately. result() is an example of a blocking method:

job = backend.run(...)

try:
    job_result = job.result()  # It will block until the job finishes.
    print("The job finished with result {}".format(job_result))
except JobError as ex:
    print("Something wrong happened!: {}".format(ex))

Job information retrieved from the server is attached to the IBMCircuitJob instance as attributes. Given that Qiskit and the server can be updated independently, some of these attributes might be deprecated or experimental. Supported attributes can be retrieved via methods. For example, you can use creation_date() to retrieve the job creation date, which is a supported attribute.

IBMCircuitJob constructor.

Parameters:

backend (IBMBackend) – The backend instance used to run this job.
api_client (AccountClient) – Object for connecting to the server.
job_id (str) – Job ID.
creation_date (Optional[str]) – Job creation date.
status (Optional[str]) – Job status returned by the server.
runtime_client (Optional[RuntimeClient]) – Object for connecting to the runtime server
kind (Optional[str]) – Job type.
name (Optional[str]) – Job name.
time_per_step (Optional[dict]) – Time spent for each processing step.
result (Optional[dict]) – Job result.
error (Optional[dict]) – Job error.
tags (Optional[List[str]]) – Job tags.
run_mode (Optional[str]) – Scheduling mode the job runs in.
client_info (Optional[Dict[str, str]]) – Client information from the API.
kwargs (Any) – Additional job attributes.

Attributes

`IBMCircuitJob.client_version`	Return version of the client used for this job.
`IBMCircuitJob.usage_estimation`	Return usage estimation information for this job.
`IBMCircuitJob.version`

Methods

`IBMCircuitJob.backend`()	Return the backend where this job was executed.
`IBMCircuitJob.backend_options`()	Return the backend configuration options used for this job.
`IBMCircuitJob.cancel`()	Attempt to cancel the job.
`IBMCircuitJob.cancelled`()	Return whether the job has been cancelled.
`IBMCircuitJob.circuits`()	Return the circuits or pulse schedules for this job.
`IBMCircuitJob.creation_date`()	Return job creation date, in local time.
`IBMCircuitJob.done`()	Return whether the job has successfully run.
`IBMCircuitJob.error_message`()	Provide details about the reason of failure.
`IBMCircuitJob.header`()	Return the user header specified for this job.
`IBMCircuitJob.in_final_state`()	Return whether the job is in a final job state such as `DONE` or `ERROR`.
`IBMCircuitJob.job_id`()	Return the job ID assigned by the server.
`IBMCircuitJob.name`()	Return the name assigned to this job.
`IBMCircuitJob.properties`()	Return the backend properties for this job.
`IBMCircuitJob.queue_info`()	Return queue information for this job.
`IBMCircuitJob.queue_position`([refresh])	Return the position of the job in the server queue.
`IBMCircuitJob.refresh`()	Obtain the latest job information from the server.
`IBMCircuitJob.result`([timeout, refresh])	Return the result of the job.
`IBMCircuitJob.running`()	Return whether the job is actively running.
`IBMCircuitJob.scheduling_mode`()	Return the scheduling mode the job is in.
`IBMCircuitJob.status`()	Query the server for the latest job status.
`IBMCircuitJob.submit`()	Unsupported method.
`IBMCircuitJob.tags`()	Return the tags assigned to this job.
`IBMCircuitJob.time_per_step`()	Return the date and time information on each step of the job processing.
`IBMCircuitJob.update_name`(name)	Update the name associated with this job.
`IBMCircuitJob.update_tags`(new_tags)	Update the tags associated with this job.
`IBMCircuitJob.wait_for_final_state`([timeout])	Use the websocket server to wait for the final the state of a job. The server