feat!: added shots arg to run_async

[jasonhan3]

closes https://github.com/QuEraComputing/bloqade-internal/issues/398

Nonbreaking change to pass in "shots" argument to "run_async".

• Sets the "shots" value in the TaskDefinition to whatever the user inputs via "run_async" (instead of the stored shots on the task)
• Overrides/updates the dry-run printing for the summary.

BREAKING CHANGES

• Gets rid of "num_shots" from device.task() and from storing it on the tasks. (This changes some public API's)
• Have "dry_run" default to True.

Summary

Move shot-count configuration from task creation to execution. Tasks no longer
store shot counts; run_async() supplies them when it builds the QLAM task
definition.

• TaskABC.run_async() now defaults to a one-shot dry run.
• shots: int | list[int] = 1 controls the QLAM subtask counts.
• An integer broadcasts to every subtask; a list supplies one count per
  subtask.
• Direct QLAM definition creation requires an explicit num_shots value.

Breaking changes

Task factories no longer accept num_shots

Remove num_shots from all task factories:

• Device.task(...)
• Device.batch_task(...)
• Device.parameter_scan(...)

Before:

task = device.batch_task(kernels, num_shots=100)
future = task.run_async(dry_run=False)

After:

task = device.batch_task(kernels)
future = task.run_async(dry_run=False, shots=100)

For per-subtask counts, pass a list when running:

future = task.run_async(dry_run=False, shots=[100, 200])

Task objects no longer store shot counts

SingleKernelTask, KernelBatchTask, and ParameterScanTask no longer have
a num_shots field, and TaskABC.get_num_shots() has been removed. Code that
reads or mutates those fields must instead provide shots to run_async() or
num_shots to create_task_definition().

run_async() now defaults to a dry run and one shot

The new signature is:

task.run_async(*, dry_run: bool = True, shots: int | list[int] = 1)

Consequences:

• task.run_async() now prints a one-shot dry-run summary and returns None.
• Calls that are intended to submit must continue to pass dry_run=False.
• task.run_async(dry_run=False) submits one shot per subtask unless shots
  is explicitly supplied.
• shots=None is no longer supported.

create_task_definition() requires num_shots

The new signature is:

task.create_task_definition(*, num_shots: int | list[int])

Custom TaskABC subclasses that override this method must update their
override to accept and use that keyword argument.

Implementation details

• Every QLAM Subtask is created with a concrete shot count.
• Per-subtask shot-count lists are validated against the number of subtasks
  and raise a clear ValueError when lengths differ.
• Single-kernel and batch summaries show the effective shot counts, including
  the default of one shot.

Testing

• uv run pytest — 262 passed
• uv run ruff check .
• uv run pyright
• uv run just coverage — 95% total coverage

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://QuEraComputing.github.io/bloqade-core/pr-preview/pr-99/
Built to branch gh-pages at 2026-08-11 15:56 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[github-actions]

☂️ Code Coverage

current status: ✅

Overall Coverage

Statements	Covered	Coverage	Threshold	Status
1583	1505	95%	0%	🟢

New Files

No new covered files...

Modified Files

File	Coverage	Status
src/bloqade/core/device/device.py	100%	🟢
src/bloqade/core/device/task.py	99%	🟢
TOTAL	99%	🟢

updated for commit: da55687 by action🐍

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!