RuntimeJob
class RuntimeJob(backend, api_client, client_params, job_id, program_id, service, creation_date=None, user_callback=None, result_decoder=None, image='', session_id=None, tags=None, version=None)
Representation of a runtime primitive execution.
A new RuntimeJob instance is returned when you call QiskitRuntimeService.run to execute a runtime primitive, or QiskitRuntimeService.job to retrieve a previously executed job.
If the primitive 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 primitive 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. - 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]) – AResultDecodersubclass 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
ERROR
Type: str | RuntimeJobStatus
Default value: 'job incurred error'
JOB_FINAL_STATES
Type: Tuple[Any, ...]
Default value: (JobStatus.DONE, JobStatus.CANCELLED, JobStatus.ERROR)
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.
instance
For ibm_quantum channel jobs, return the instance where the job was run. For ibm_cloud, None is returned.
Return type
Optional[str]
primitive_id
Primitive name. :rtype: str :returns: Primitive this job is for.
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.
tags
Job tags.
Return type
List
Returns
Tags assigned to the job that can be used for filtering.
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)
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()
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
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()
Returns the reason if the job failed.
Return type
Optional[str]
Returns
Error message string or None.
errored
in_final_state
in_final_state()
Return whether the job is in a final job state such as DONE or ERROR.
Return type
bool
interim_results
interim_results(decoder=None)
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()
Return job logs.
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()
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)
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()
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.
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)
Return the position of the job in the server queue.
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)
Return the results of the job.
Parameters
- timeout (
Optional[float]) – Number of seconds to wait for job. - decoder (
Optional[Type[ResultDecoder]]) – AResultDecodersubclass 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
stream_results
stream_results(callback, decoder=None)
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:
- Job ID
- Job result.
-
decoder (
Optional[Type[ResultDecoder]]) – AResultDecodersubclass 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()
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)
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)
Poll for the job status from the API until the status is in a final state.
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