RuntimeJob

class RuntimeJob(backend, api_client, client_params, job_id, program_id, service, params=None, creation_date=None, user_callback=None, result_decoder=None, image='', session_id=None, tags=None, version=None)

GitHub

Representation of a runtime program execution.

A new RuntimeJob instance is returned when you call QiskitRuntimeService.run to execute a runtime program, or QiskitRuntimeService.job to retrieve a previously executed job.

If the program execution is successful, you can inspect the job’s status by calling status() . Job status can be one of the JobStatus members.

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 = service.run(...)
 
try:
    job_result = job.result()  # It will block until the job finishes.
    print("The job finished with result {}".format(job_result))
except RuntimeJobFailureError as ex:
    print("Job failed!: {}".format(ex))

If the program has any interim results, you can use the callback parameter of the run() method to stream the interim results along with the final result. Alternatively, you can use the stream_results() method to stream the results at a later time, but before the job finishes.

RuntimeJob constructor.

Parameters

backend (Backend) – The backend instance used to run this job.
api_client (RuntimeClient) – Object for connecting to the server.
client_params (ClientParameters) – Parameters used for server connection.
job_id (str) – Job ID.
program_id (str) – ID of the program this job is for.
params (Optional[Dict]) – Job parameters.
creation_date (Optional[str]) – Job creation date, in UTC.
user_callback (Optional[Callable]) – User callback function.
result_decoder (Union[Type[ResultDecoder], Sequence[Type[ResultDecoder]], None]) – A ResultDecoder subclass used to decode job results.
image (Optional[str]) – Runtime image used for this job: image_name:tag.
service (QiskitRuntimeService) – Runtime service.
session_id (Optional[str]) – Job ID of the first job in a runtime session.
tags (Optional[List]) – Tags assigned to the job.
version (Optional[int]) – Primitive version.

Attributes

creation_date

Job creation date in local time.

Return type

Optional [datetime]

Returns

The job creation date as a datetime object, in local time, or None if creation date is not available.

image

Return the runtime image used for the job.

Returns

image_name:tag or “” if the default image is used.

Return type

Runtime image

inputs

Job input parameters.

Return type

Dict

Returns

Input parameters used in this job.

program_id

Program ID.

Return type

str

Returns

ID of the program this job is for.

session_id

Session ID.

Return type

str

Returns

Session ID. None if the backend is a simulator.

usage_estimation

Return the usage estimation infromation for this job.

Return type

Dict [str, Any]

Returns

quantum_seconds which is the estimated system execution time of the job in seconds. Quantum time represents the time that the system is dedicated to processing your job.

version

Default value: 1

Methods

backend

backend(timeout=None)

GitHub

Return the backend where this job was executed. Retrieve data again if backend is None.

Raises

IBMRuntimeError - If a network error occurred.

Return type

Optional [Backend]

cancel

cancel()

GitHub

Cancel the job.

Raises

RuntimeInvalidStateError – If the job is in a state that cannot be cancelled.
IBMRuntimeError – If unable to cancel job.

Return type

None

cancel_result_streaming

cancel_result_streaming()

GitHub

Cancel result streaming.

Return type

None

cancelled

cancelled()

Return whether the job has been cancelled.

Return type

bool

done

done()

Return whether the job has successfully run.

Return type

bool

error_message

error_message()

GitHub

Returns the reason if the job failed.

Return type

Optional [str]

Returns

Error message string or None .

errored

errored()

GitHub

Return whether the job has failed.

Return type

bool

in_final_state

in_final_state()

GitHub

Return whether the job is in a final job state such as DONE or ERROR .

Return type

bool

interim_results

interim_results(decoder=None)

GitHub

Return the interim results of the job.

Parameters

decoder (Optional [Type [ResultDecoder]]) - A ResultDecoder subclass used to decode interim results.

Return type

Any

Returns

Runtime job interim results.

Raises

RuntimeJobFailureError - If the job failed.

job_id

job_id()

Return a unique id identifying the job.

Return type

str

logs

logs()

GitHub

Return job logs.

Note

Job logs are only available after the job finishes.

Return type

str

Returns

Job logs, including standard output and error.

Raises

IBMRuntimeError - If a network error occurred.

metrics

metrics()

GitHub

Return job metrics.

Return type

Dict [str, Any]

Returns

Job metrics, which includes timestamp information.

Raises

IBMRuntimeError - If a network error occurred.

properties

properties(refresh=False)

GitHub

Return the backend properties for this job.

Parameters

refresh (bool) - If True, re-query the server for the backend properties. Otherwise, return a cached version.

Return type

Optional [BackendProperties]

Returns

The backend properties used for this job, at the time the job was run, or None if properties are not available.

queue_info

queue_info()

GitHub

Return queue information for this job.

The queue information may include queue position, estimated start and end time, and dynamic priorities for the hub, group, and project. See QueueInfo for more information.

Note

The queue information is calculated after the job enters the queue. Therefore, some or all of the information may not be immediately available, and this method may return None .

Return type

Optional [QueueInfo]

Returns

A QueueInfo instance that contains queue information for this job, or None if queue information is unknown or not applicable.

queue_position

queue_position(refresh=False)

GitHub

Return the position of the job in the server queue.

Note

The position returned is within the scope of the provider and may differ from the global queue position.

Parameters

refresh (bool) - If True, re-query the server to get the latest value. Otherwise return the cached value.

Return type

Optional [int]

Returns

Position in the queue or None if position is unknown or not applicable.

result

result(timeout=None, decoder=None)

GitHub

Return the results of the job.

Parameters

timeout (Optional[float]) – Number of seconds to wait for job.
decoder (Optional[Type[ResultDecoder]]) – A ResultDecoder subclass used to decode job results.

Return type

Any

Returns

Runtime job result.

Raises

RuntimeJobFailureError – If the job failed.
RuntimeJobMaxTimeoutError – If the job does not complete within given timeout.
RuntimeInvalidStateError – If the job was cancelled, and attempting to retrieve result.

running

running()

Return whether the job is actively running.

Return type

bool

status

status()

GitHub

Return the status of the job.

Return type

JobStatus

Returns

Status of this job.

stream_results

stream_results(callback, decoder=None)

GitHub

Start streaming job results.

Parameters

callback (Callable) –

Callback function to be invoked for any interim results and final result. The callback function will receive 2 positional parameters:
1. Job ID
2. Job result.
$decoder (Optional [Type [ResultDecoder]]) - A ResultDecoder subclass used to decode job results.$

Raises

RuntimeInvalidStateError - If a callback function is already streaming results or if the job already finished.

Return type

None

submit

submit()

GitHub

Unsupported method. .. note:

This method is not supported, please use
:meth:`~qiskit_ibm_runtime.QiskitRuntimeService.run`
to submit a job.

Raises

NotImplementedError - Upon invocation.

Return type

None

update_tags

update_tags(new_tags)

GitHub

Update the tags associated with this job.

Parameters

new_tags (List [str]) - New tags to assign to the job.

Return type

List [str]

Returns

The new tags associated with this job.

Raises

IBMApiError - If an unexpected error occurred when communicating with the server or updating the job tags.

wait_for_final_state

wait_for_final_state(timeout=None)

GitHub

Use the websocket server to wait for the final the state of a job.

The server will remain open if the job is still running and the connection will be terminated once the job completes. Then update and return the status of the job.

Parameters

timeout (Optional [float]) - Seconds to wait for the job. If None, wait indefinitely.

Raises

RuntimeJobTimeoutError - If the job does not complete within given timeout.

Return type

None

Was this page helpful?

Report a bug or request content on GitHub.