Skip to main contentIBM Quantum Documentation

IBMCompositeJob

IBMCompositeJob(backend, api_client, job_id=None, creation_date=None, jobs=None, circuits_list=None, run_config=None, name=None, tags=None, client_version=None)

Representation of a set of jobs that execute on an IBM Quantum backend.

An IBMCompositeJob instance is returned when you call IBMBackend.run() to submit a list of circuits whose length exceeds the maximum allowed by the backend or by the max_circuits_per_job parameter.

This IBMCompositeJob instance manages all the sub-jobs for you and can be used like a traditional job instance. For example, you can continue to use methods like status() and result() to get the job status and result, respectively.

You can also retrieve a previously executed IBMCompositeJob using the job() and jobs() methods, like you would with traditional jobs.

IBMCompositeJob also allows you to re-run failed jobs, using the rerun_failed() method. This method will re-submit all failed or cancelled sub-jobs. Any circuits that failed to be submitted (e.g. due to server error) will only be re-submitted if the circuits are known. That is, if this IBMCompositeJob was returned by qiskit_ibm_provider.IBMBackend.run() and not retrieved from the server.

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, and control will return only after all sub-jobs finish.

IBMCompositeJob uses job tags to identify sub-jobs. It is therefore important to preserve these tags. All tags used internally by IBMCompositeJob start with ibm_composite_job_.

IBMCompositeJob constructor.

Parameters

  • backend (IBMBackend) – The backend instance used to run this job.
  • api_client (AccountClient) – Object for connecting to the server.
  • job_id (Optional[str]) – Job ID.
  • creation_date (Optional[datetime]) – Job creation date.
  • jobs (Optional[List[IBMCircuitJob]]) – A list of sub-jobs.
  • circuits_list (Optional[List[List[QuantumCircuit]]]) – Circuits for this job.
  • run_config (Optional[Dict]) – Runtime configuration for this job.
  • name (Optional[str]) – Job name.
  • tags (Optional[List[str]]) – Job tags.
  • client_version (Optional[Dict]) – Client used for the job.

Raises

IBMJobInvalidStateError – If one or more subjobs is missing.

Attributes

client_version

Dict[str, str]

Return version of the client used for this job.

Return type

Dict[str, str]

Returns

Client version in dictionary format, where the key is the name

of the client and the value is the version. An empty dictionary is returned if the information is not yet known.

version

= 1

Methods

backend

IBMCompositeJob.backend()

Return the backend where this job was executed.

Return type

Backend

backend_options

IBMCompositeJob.backend_options()

Return the backend configuration options used for this job.

Options that are not applicable to the job execution are not returned. Some but not all of the options with default values are returned. You can use qiskit_ibm_provider.IBMBackend.options to see all backend options.

Return type

Dict[str, Any]

Returns

Backend options used for this job.

block_for_submit

IBMCompositeJob.block_for_submit()

Block until all sub-jobs are submitted.

Return type

None

cancel

IBMCompositeJob.cancel()

Attempt to cancel the job.

Note

Depending on the state the job is in, it might be impossible to cancel the job.

Return type

bool

Returns

True if the job is cancelled, else False.

Raises

IBMJobApiError – If an unexpected error occurred when communicating with the server.

cancelled

IBMCompositeJob.cancelled()

Return whether the job has been cancelled.

Return type

bool

circuits

IBMCompositeJob.circuits()

Return the circuits for this job.

Return type

List[QuantumCircuit]

Returns

The circuits for this job.

creation_date

IBMCompositeJob.creation_date()

Return 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 job submission hasn’t finished or failed.

done

IBMCompositeJob.done()

Return whether the job has successfully run.

Return type

bool

error_message

IBMCompositeJob.error_message()

Provide details about the reason of failure.

Note

This method blocks until the job finishes.

Return type

Optional[str]

Returns

An error report if the job failed or None otherwise.

from_jobs

classmethod IBMCompositeJob.from_jobs(job_id, jobs, api_client)

Return an instance of this class.

The input job ID is used to query for sub-job information from the server.

Parameters

  • job_id (str) – Job ID.
  • jobs (List[IBMCircuitJob]) – A list of circuit jobs that belong to this composite job.
  • api_client (AccountClient) – Client to use to communicate with the server.

Return type

IBMCompositeJob

Returns

An instance of this class.

header

IBMCompositeJob.header()

Return the user header specified for this job.

Return type

Dict

Returns

User header specified for this job. An empty dictionary is returned if the header cannot be retrieved.

in_final_state

IBMCompositeJob.in_final_state()

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

Return type

bool

job_id

IBMCompositeJob.job_id()

Return a unique id identifying the job.

Return type

str

name

IBMCompositeJob.name()

Return the name assigned to this job.

Return type

Optional[str]

Returns

Job name or None if no name was assigned to this job.

properties

IBMCompositeJob.properties(refresh=False)

Return the backend properties for this job.

Args:

refresh: If True, re-query the server for the backend properties.

Otherwise, return a cached version.

Note

This method blocks until all sub-jobs are submitted.

Return type

Union[List[BackendProperties], BackendProperties, None]

Returns

The backend properties used for this job, or None if properties are not available. A list of backend properties is returned if the sub-jobs used different properties.

Raises

IBMJobApiError – If an unexpected error occurred when communicating with the server.

queue_info

IBMCompositeJob.queue_info()

Return queue information for this job.

This method returns the queue information of the sub-job that is last in queue.

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

IBMCompositeJob.queue_position(refresh=False)

Return the position of the job in the server queue.

This method returns the queue position of the sub-job that is last in 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.

refresh

IBMCompositeJob.refresh()

Obtain the latest job information from the server.

This method may add additional attributes to this job instance, if new information becomes available.

Raises

IBMJobApiError – If an unexpected error occurred when communicating with the server.

Return type

None

report

IBMCompositeJob.report(detailed=True)

Return a report on current sub-job statuses.

Parameters

detailed (bool) – If True, return a detailed report. Otherwise return a summary report.

Return type

str

Returns

A report on sub-job statuses.

rerun_failed

IBMCompositeJob.rerun_failed()

Re-submit all failed sub-jobs.

Note

All sub-jobs that are in “ERROR” or “CANCELLED” states will be re-submitted. Sub-jobs that failed to be submitted will only be re-submitted if the circuits are known. That is, if this IBMCompositeJob was returned by qiskit_ibm_provider.IBMBackend.run() and not retrieved from the server.

Return type

None

result

IBMCompositeJob.result(timeout=None, wait=5, partial=False, refresh=False)

Return the result of the job.

Note

This method blocks until all sub-jobs finish.

Note

Some IBM Quantum job results can only be read once. A second attempt to query the server for the same job will fail, since the job has already been “consumed”.

The first call to this method in an IBMCompositeJob instance will query the server and consume any available job results. Subsequent calls to that instance’s result() will also return the results, since they are cached. However, attempting to retrieve the results again in another instance or session might fail due to the job results having been consumed.

Note

When partial=True, this method will attempt to retrieve partial results of failed jobs. In this case, precaution should be taken when accessing individual experiments, as doing so might cause an exception. The success attribute of the returned Result instance can be used to verify whether it contains partial results.

For example, if one of the circuits in the job failed, trying to get the counts of the unsuccessful circuit would raise an exception since there are no counts to return:

try:
    counts = result.get_counts("failed_circuit")
except QiskitError:
    print("Circuit execution failed!")

If the job failed, you can use error_message() to get more information.

Parameters

  • timeout (Optional[float]) – Number of seconds to wait for job.
  • wait (float) – Time in seconds between queries.
  • partial (bool) – If True, return partial results if possible. Partial results refer to experiments within a sub-job, not individual sub-jobs. That is, this method will still block until all sub-jobs finish even if partial is set to True.
  • refresh (bool) – If True, re-query the server for the result. Otherwise return the cached value.

Return type

Result

Returns

Job result.

Raises

running

IBMCompositeJob.running()

Return whether the job is actively running.

Return type

bool

scheduling_mode

IBMCompositeJob.scheduling_mode()

Return the scheduling mode the job is in.

The scheduling mode indicates how the job is scheduled to run. For example, fairshare indicates the job is scheduled using a fairshare algorithm.

fairshare is returned if any of the sub-jobs has scheduling mode of fairshare.

This information is only available if the job status is RUNNING or DONE.

Return type

Optional[str]

Returns

The scheduling mode the job is in or None if the information is not available.

status

IBMCompositeJob.status()

Query the server for the latest job status.

Note

This method is not designed to be invoked repeatedly in a loop for an extended period of time. Doing so may cause the server to reject your request. Use wait_for_final_state() if you want to wait for the job to finish.

Note

If the job failed, you can use error_message() to get more information.

Note

Since this job contains multiple sub-jobs, the returned status is mapped in the following order:

  • INITIALIZING - if any sub-job is being initialized.
  • VALIDATING - if any sub-job is being validated.
  • QUEUED - if any sub-job is queued.
  • RUNNING - if any sub-job is still running.
  • ERROR - if any sub-job incurred an error.
  • CANCELLED - if any sub-job is cancelled.
  • DONE - if all sub-jobs finished.

Return type

JobStatus

Returns

The status of the job.

Raises

IBMJobApiError – If an unexpected error occurred when communicating with the server.

sub_job

IBMCompositeJob.sub_job(circuit_index)

Retrieve the job used to submit the specified circuit.

Parameters

circuit_index (int) – Index of the circuit whose job is to be returned.

Return type

Optional[IBMCircuitJob]

Returns

The Job submitted for the circuit, or None if the job has not been submitted or the submit failed.

Raises

IBMJobInvalidStateError – If the circuit index is out of range.

sub_jobs

IBMCompositeJob.sub_jobs(block_for_submit=True)

Return all submitted sub-jobs.

Parameters

block_for_submit (bool) – True if this method should block until all sub-jobs are submitted. False if the method should return immediately with submitted sub-jobs, if any.

Return type

List[IBMCircuitJob]

Returns

All submitted sub-jobs.

submit

IBMCompositeJob.submit()

Unsupported method.

Note

This method is not supported, please use run() to submit a job.

Raises

NotImplementedError – Upon invocation.

Return type

None

tags

IBMCompositeJob.tags()

Return the tags assigned to this job.

Return type

List[str]

Returns

Tags assigned to this job.

time_per_step

IBMCompositeJob.time_per_step()

Return the date and time information on each step of the job processing.

The output dictionary contains the date and time information on each step of the job processing, in local time. The keys of the dictionary are the names of the steps, and the values are the date and time data, as a datetime object with local timezone info. For example:

{'CREATING': datetime(2020, 2, 13, 15, 19, 25, 717000, tzinfo=tzlocal(),
 'CREATED': datetime(2020, 2, 13, 15, 19, 26, 467000, tzinfo=tzlocal(),
 'VALIDATING': datetime(2020, 2, 13, 15, 19, 26, 527000, tzinfo=tzlocal()}

Return type

Optional[Dict]

Returns

Date and time information on job processing steps, in local time, or None if the information is not yet available.

update_name

IBMCompositeJob.update_name(name)

Update the name associated with this job.

Note

This method blocks until all sub-jobs are submitted.

Parameters

name (str) – The new name for this job.

Return type

str

Returns

The new name associated with this job.

Raises

update_tags

IBMCompositeJob.update_tags(new_tags)

Update the tags associated with this job.

Note

This method blocks until all sub-jobs are submitted.

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

  • IBMJobApiError – If an unexpected error occurred when communicating with the server or updating the job tags.
  • IBMJobInvalidStateError – If none of the input parameters are specified or if any of the input parameters are invalid.

wait_for_final_state

IBMCompositeJob.wait_for_final_state(timeout=None, wait=None, callback=None)

Wait until the job progresses to a final state such as DONE or ERROR.

Parameters

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

  • wait (Optional[float]) – Seconds to wait between invoking the callback function. If None, the callback function is invoked only if job status or queue position has changed.

  • callback (Optional[Callable]) –

    Callback function invoked after each querying iteration. The following positional arguments are provided to the callback function:

    • job_id: Job ID
    • job_status: Status of the job from the last query.
    • job: This IBMCompositeJob instance.

    In addition, the following keyword arguments are also provided:

    • queue_info: A QueueInfo instance with job queue information, or None if queue information is unknown or not applicable. You can use the to_dict() method to convert the QueueInfo instance to a dictionary, if desired.

Raises

IBMJobTimeoutError – if the job does not reach a final state before the specified timeout.

Return type

None

Was this page helpful?