Executing Quantum Jobs

When you execute a quantum program, whether on a local simulator or a remote physical processor, the execution is managed as a 'Job'. A quantum job is an asynchronous task that packages your quantum circuits, sends them to an execution backend, monitors their progress through queues, and retrieves the resulting data. Understanding the lifecycle of a job is essential for writing robust, production-ready quantum applications.

Because physical quantum computers are highly specialized, shared resources located in cloud data centers, you cannot execute code on them instantaneously. Instead, your circuit is placed in a queue alongside jobs from other developers around the world. Qiskit manages this queueing and execution process asynchronously, allowing your classical Python script to continue running, monitor the job's status, or even disconnect and retrieve the results hours later.

In this topic, you will master the mechanics of quantum jobs in Qiskit 1.x. You will learn how to submit jobs using Primitives, monitor their status (queued, running, completed, or failed), handle execution errors, and retrieve results. This knowledge is critical for managing long-running computations and building hybrid classical-quantum workflows.

Think of submitting a quantum job like submitting a 3D print job to a shared community workshop. You don't stand next to the 3D printer waiting for it to heat up, print, and cool down. Instead, you upload your design file (the transpiled quantum circuit) to the printer's server. The server gives you a receipt with a unique tracking ID (the Job ID) and places your design in a queue.

You can check the printer's website to see your job's status: 'In Queue (Position 5)', 'Printing', or 'Completed'. While it is printing, you can go have lunch or work on other designs. Once the website says 'Completed', you go to the workshop and pick up your physical plastic model (the measurement results).

In Qiskit, the Job object is your digital receipt. It holds the unique Job ID and provides methods to check the status of your circuit on the remote quantum processor. If the queue is long, you can close your laptop, go to sleep, and use the Job ID to retrieve your results the next morning from a completely different script.

In Qiskit 1.x, when you call the run() method on a Primitive (like Sampler or Estimator), it returns a Job object (specifically, an instance of a class implementing the JobV1 interface, such as PrimitiveJob or RuntimeJob). This submission is non-blocking; the job is sent to the backend in the background, and your Python script immediately moves to the next line of code.

A quantum job progresses through a series of standard states, represented by the JobStatus enum: 1. INITIALIZING: The job is being prepared and packaged. 2. QUEUED: The job is waiting in the backend's queue. You can query its queue position. 3. RUNNING: The circuit is actively being executed on the physical hardware or simulator. 4. DONE: Execution completed successfully, and results are ready for retrieval. 5. ERROR: Execution failed (e.g., due to transpilation errors, timeout, or hardware faults). 6. CANCELLED: The job was manually cancelled by the user before execution.

Here is a complete, runnable Qiskit 1.x program that demonstrates how to manage this asynchronous lifecycle programmatically:

import time
from qiskit import QuantumCircuit
from qiskit.primitives import StatevectorSampler

# Build a simple circuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()

# Instantiate the sampler
sampler = StatevectorSampler()

# Submit the job asynchronously (this call returns immediately)
print("Submitting job...")
job = sampler.run([qc], shots=2000)

# Retrieve the unique Job ID
job_id = job.job_id()
print(f"Job submitted successfully! Job ID: {job_id}")

# Monitor the job status without blocking
while not job.in_final_state():
    status = job.status()
    print(f"Current Job Status: {status}")
    time.sleep(0.5) # Wait half a second before checking again

# Check final status
final_status = job.status()
print(f"Final Job Status: {final_status}")

if final_status.name == 'DONE':
    # Retrieve results
    result = job.result()
    counts = result[0].data.meas.get_counts()
    print("Results retrieved successfully!")
    print("Counts:", counts)
else: 
    print("Job failed or was cancelled.")

In this code, job.in_final_state() returns True if the job is in a terminal state (DONE, ERROR, or CANCELLED). This allows us to write a non-blocking monitoring loop. For cloud-based jobs, Qiskit provides a helper utility, job_monitor(job), which prints a live-updating status line in your terminal.