Run a parameter sweep

• Package versions

  The code on this page was developed using the following requirements. We recommend using these versions or newer.

  qiskit-serverless~=0.38.0
  

A parameter sweep works like a Slurm job array. Call run() one time for each set of inputs, and the jobs run at the same time, each on its own node. Use the same pattern for any batch of independent inputs, such as one job for each molecule or each backend. Jobs cannot send data to each other, so split the work into independent inputs.

The examples on this page use the workflow from Run a managed workflow, which reads one angle, theta:

import math

from qiskit_serverless import get_arguments, save_result

arguments = get_arguments()
theta = arguments["theta"]
if not 0 <= theta <= math.pi:
    raise ValueError(f"theta must be between 0 and pi, got {theta}")

print(f"Computing the expectation value for theta={theta}", flush=True)
save_result({"theta": theta, "expectation_value": math.cos(theta)})

Start the jobs

Get the workflow by its title, and call run() one time for each input. Save the job IDs to a file:

import json

from qiskit_ibm_catalog import ManagedWorkflowClient

client = ManagedWorkflowClient()
my_workflow = client.load("my-workflow")

thetas = [0.1, 0.2, 0.3]

job_ids = {
    f"theta-{theta}": my_workflow.run(theta=theta).job_id for theta in thetas
}

with open("job_ids.json", "w") as f:
    json.dump(job_ids, f)

• Check every input first. If the workflow has an argument schema, call validate_arguments() on each input before the loop.
• Save the job IDs to a file. You can then collect the results from a new session.
• Give each run's files a unique name. All runs share the workflow's file storage. See Best practice: give each run's files a unique name.
• Stay under the active job limit. A managed workflow does not queue jobs over the limit, so when you reach it, start more jobs only after earlier jobs end.

Collect the results

Get each job by its ID, and catch failed jobs so that one failure does not stop the loop:

from qiskit_serverless.exception import QiskitServerlessException

with open("job_ids.json") as f:
    job_ids = json.load(f)

results, errors = {}, {}
for run_name, sweep_job_id in job_ids.items():
    try:
        results[run_name] = client.job(sweep_job_id).result()
    except QiskitServerlessException as error:
        errors[run_name] = str(error)

print(f"{len(results)} jobs finished, {len(errors)} failed")

Output:

3 jobs finished, 0 failed

To rerun the inputs that failed, call run() again with the same arguments.

Active job limit

You can have up to 50 jobs that are queued, initializing, running, or canceling at the same time. This limit counts all of your jobs, including jobs of other workflows. If you exceed this limit, run() raises a QiskitServerlessException and does not create or queue the job:

| Message: Http bad request.
| Code: 429
| Details: Active job limit reached. The maximum allowed is 50.

Next steps