IonQ Job

IonQ’s Job implementation.

Note

IonQ job status names are slightly different than those of the standard JobStatus enum values.

As such, the IonQJob.status() method on the IonQJob class attempts to perform a mapping between these status values for compatibility with BaseJob.

class qiskit_ionq.ionq_job.IonQJob(backend: ionq_backend.IonQBackend, job_id: str | None = None, client: ionq_client.IonQClient | None = None, circuit: QuantumCircuit | None = None, passed_args: dict | None = None)

Representation of a Job that will run on an IonQ backend.

It is not recommended to create Job instances directly; use IonQBackend.run() and IonQBackend.retrieve_job() instead.

circuit

A possibly None Qiskit quantum circuit.

Type:

QuantumCircuit

_result

The actual Qiskit Result of this job when done.

Type:

Result

Initializes the asynchronous job.

Parameters:

• backend – the backend used to run the job.

• job_id – a unique id in the context of the backend used to run the job.

• kwargs – Any key value metadata to associate with this job.

backend() → Backend

Return the backend where this job was executed.

cancel() → None

Cancel this job.

cancelled() → bool

Return whether the job has been cancelled.

compiled_circuit(lang: str = 'native') → str

Fetch the server-compiled circuit for this job.

Useful for jobs submitted with dry_run=True (compilation as a service) but also works for any completed job to inspect what was actually run on hardware after IonQ’s compiler resynthesizes the input.

Parameters:

lang (str) – Output language. "native" (default) returns the IonQ-native gate JSON; "qasm3" returns OpenQASM 3 source. Other values may be accepted depending on organization entitlement; the API rejects unsupported or non-entitled values with a 4xx response surfaced here as IonQAPIError.

Raises:

• IonQJobStateError – If the job has not reached a final state yet.

• IonQJobFailureError – If the job failed before compilation completed.

• IonQAPIError – If the API rejects the lang value.

Returns:

The compiled circuit as a string (IonQ-native JSON or OpenQASM 3).

Return type:

str

done() → bool

Return whether the job has successfully run.

property dry_run: bool

Whether this job was submitted with dry_run=True.

Dry-run jobs are compiled by the IonQ Cloud compiler-as-a-service but not executed - they produce no measurement results. Use compiled_circuit() to retrieve the compiled circuit instead of result().

get_counts(circuit: QuantumCircuit | None = None) → dict

Return the counts for the job.

Attention

Result counts for jobs processed by IonQSimulatorBackend are returned from the API as probabilities, and are converted to counts via simple statistical sampling that occurs on the client side.

To obtain the true probabilities, use the get_probabilties() method instead.

Parameters:

circuit (str or QuantumCircuit or int or None) – Optional. The index of the experiment.

Returns:

A dictionary of counts.

Return type:

dict

get_memory(circuit=None)

Return per-shot memory bitstrings (MSB-left), one entry per shot.

circuit follows the same semantics as get_counts(). Raises IonQBackendError if the job was submitted with memory=False.

get_probabilities(circuit=None)

Return the probabilities (for simulators).

This is effectively a pass-through to

get_probabilities

Parameters:

circuit (str or QuantumCircuit or int or None) – Optional.

Returns:

A tuple counts, probabilities.

Return type:

tuple(dict[str, float], dict[str, float])

in_final_state() → bool

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

job_id() → str

Return a unique id identifying the job.

result(sharpen: bool | None = None, timeout: float | None = None, wait: float = 5, callback: Callable | None = None, extra_query_params: dict | None = None)

Retrieve job result data, blocking until the job is complete.

Note

_result is populated by status(), when the job status has reached a “final” state.

This method calls the wait_for_final_state method to poll for a completed job.

Raises:

• IonQJobTimeoutError – If after the default wait period in wait_for_final_state elapses and the job has not reached a “final” state.

• IonQJobError – If the job has reached a final state but the job itself was never converted to a Result.

• IonQJobStateError – If the job was cancelled before this method fetches it.

Returns:

A Qiskit Result representation of this job.

Return type:

Result

running() → bool

Return whether the job is actively running.

status(detailed: bool = False) → JobStatus | dict

Retrieve the status of a job.

Parameters:

detailed (bool) – If True, returns a detailed status of children.

Returns:

An enum value from Qiskit’s

JobStatus if detailed is False. A dictionary containing the detailed status of the children if detailed is True.

Return type:

JobStatus or dict

Raises:

• IonQJobError – If the IonQ job status was unknown or otherwise unmappable to a qiskit job status.

• IonQJobFailureError – If the job fails

• IonQJobStateError – If the job was cancelled

submit() → None

Submit a job to the IonQ API.

Raises:

IonQJobError – If this instance’s qobj was None.

wait_for_final_state(timeout: float | None = None, wait: float = 5, callback: Callable | None = None) → None

Poll the job status until it progresses to a final state such as DONE or ERROR.

Parameters:

• timeout – Seconds to wait for the job. If None, wait indefinitely.

• wait – Seconds between queries.

• callback –

  Callback function invoked after each query. 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 JobV1 instance

  Note: different subclass might provide different arguments to the callback function.

Raises:

JobTimeoutError – If the job does not reach a final state before the specified timeout.