bloqade.core.device.device.Device
classDevice¶source
bloqade.core.device.device.Device
Bases: AuthMixin, Generic[FutureType]
Create legacy tasks and finalize or submit task builders.
Signature
class Device(*, context_name: str, qpu_mode: str | None = None, program_language: str = 'squin', language_version: str = '0.1.0', future_cls: type[FutureType] = Future, kernel_serializer: KernelSerializer = JSONSerializer(), validation_suite: ValidationSuite | None = None, dialect_group: ir.DialectGroup | None = None)Legacy factory methods return task objects that submit themselves. For the builder API, the device supplies serialization and validation context and owns dry-run and submission through run_async.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
context_name | str | required | |
qpu_mode | str | None | None | |
program_language | str | 'squin' | |
language_version | str | '0.1.0' | |
future_cls | type[FutureType] | Future | |
kernel_serializer | KernelSerializer | JSONSerializer() | |
validation_suite | ValidationSuite | None | None | |
dialect_group | ir.DialectGroup | None | None |
Attributes
| Name | Type | Description |
|---|---|---|
qpu_mode | str | None | Explicit qlam QPU mode used by tasks created from this device. When None, qlam-core resolves it from configuration. |
program_language | str | Language name placed on builder-generated task definitions. Defaults to ``"squin"``. |
language_version | str | Language version used when serializing builder kernels. Defaults to ``"0.1.0"``. |
future_cls | type[FutureType] | Future class used by tasks created from this device. Defaults to `Future`. |
kernel_serializer | KernelSerializer | Default serializer passed to created tasks. The serializer is used by `TaskABC.serialize_kernel`; it should provide an `encode` method for Kirin serialization modules. Defaults to `kirin.serialization.JSONSerializer`. |
methodrun_async¶source
bloqade.core.device.device.Device.run_async
Signature
def run_async(task_builder: TaskBuilder, *, dry_run: bool, group: str | None = None, profile_id: str | UUID | None = None, storage: StorageBackend | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS) -> FutureType | NoneValidate and finalize a builder, optionally submitting it.
A dry run performs the same kernel validation and serialization as a
submission, prints the builder summary, and returns None without
authenticating, writing storage, or calling QLAM. Finalization does not
mutate the builder, so it remains editable after a dry run.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
task_builder | TaskBuilder | required | Incrementally assembled task to finalize. |
dry_run | bool | required | |
group | str | None | None | |
profile_id | str | UUID | None | None | |
storage | StorageBackend | None | None | |
fetch_options | ApiFetchOptions | DEFAULT_FETCH_OPTIONS |
Other Parameters
| Name | Type | Description |
|---|---|---|
dry_run | bool | When true, print a preview without submitting. When false, submit and return a future. |
group | str | None | Optional QLAM group name or UUID string for this submission. Defaults to configured group precedence. |
profile_id | str | UUID | None | Optional task profile UUID. Used when the finalized task definition does not already specify a profile. Defaults to None. |
storage | StorageBackend | None | Storage for the submitted task definition. Ignored during a dry run. |
fetch_options | ApiFetchOptions | Fetch configuration attached to the returned future. Ignored during a dry run. |
Returns
FutureType | None``None`` for a dry run; otherwise the future associated with the submitted QLAM task.
methodsubmit_task_definition¶source
bloqade.core.device.device.Device.submit_task_definition
Signature
def submit_task_definition(*, task_definition: TaskDefinition, storage: StorageBackend | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS, group: str | None = None, profile_id: str | UUID | None = None) -> FutureTypeSubmit a prepared task definition and return a future.
When the definition does not set a group ID, a task-level group name
takes precedence over the ~/.qsh config group (plugins.tasks.group,
then defaults.group). The selected name is resolved before
submission. When neither is set, the group is omitted and QLAM selects
the backend default group.
An existing task_definition.profile_id takes precedence over the
profile_id keyword argument. The keyword argument fills the profile
only when the definition does not already specify one. After
submission, the profile returned by QLAM is stored as the effective
profile for the task.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
task_definition | TaskDefinition | required | |
storage | StorageBackend | None | None | |
fetch_options | ApiFetchOptions | DEFAULT_FETCH_OPTIONS | |
group | str | None | None | |
profile_id | str | UUID | None | None |
Other Parameters
| Name | Type | Description |
|---|---|---|
task_definition | TaskDefinition | Task definition to submit. |
storage | StorageBackend | None | Storage backend that will receive the task definition. When None, a fresh `DictStorage` is used (in-memory; not persisted across processes). Defaults to None. |
fetch_options | ApiFetchOptions | Pagination and polling options attached to the returned future. Defaults to `ApiFetchOptions()`. |
group | str | None | Optional QLAM group name or UUID string. Used when `task_definition.group_id` is None. Defaults to configured group precedence. |
profile_id | str | UUID | None | Optional task profile UUID. Used only when `task_definition.profile_id` is None. Defaults to None. |
Returns
FutureTypeFutureType: Future attached to the created task ID.
Raises
| Type | Description |
|---|---|
ValueError | If the backend response is missing a task ID. |
methodtask¶source
bloqade.core.device.device.Device.task
Signature
def task(kernel: ir.Method, num_shots: int = 1, arguments: dict | None = None, metadata: dict | None = None, program_language: str = 'squin', language_version: str = '0.1.0', kernel_serializer: KernelSerializer | None = None, group: str | None = None, profile_id: str | UUID | None = None) -> SingleKernelTask[FutureType]Create a task for one kernel.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
kernel | ir.Method | required | The kernel to execute. |
num_shots | int | 1 | Number of shots to run for the kernel. Defaults to 1. |
arguments | dict | None | None | Argument dictionary for the kernel. Defaults to None. |
metadata | dict | None | None | Metadata for the single subtask. When provided, it is wrapped in a one-element list to match the task API. Defaults to None. |
program_language | str | 'squin' | Program language to store in the task definition. Defaults to "squin". |
language_version | str | '0.1.0' | Semantic version of the program language to store in the task definition. Defaults to "0.1.0". |
kernel_serializer | KernelSerializer | None | None | Serializer for this task's kernel. When None, the device's `kernel_serializer` is used. Defaults to None. |
group | str | None | None | Name of the QLAM group for this task definition. When None, the configured group is used at submission time. |
profile_id | str | UUID | None | None | Task profile UUID for this task definition. String values are converted to `UUID`. Defaults to None, allowing QLAM to select the effective profile. |
Returns
SingleKernelTask[FutureType]A task object ready for dry-run or submission.
methodbatch_task¶source
bloqade.core.device.device.Device.batch_task
Signature
def batch_task(kernels: list[ir.Method], arguments: list[dict] | None = None, metadata: list[dict[str, Any]] | None = None, num_shots: list[int] | int = 1, program_language: str = 'squin', language_version: str = '0.1.0', kernel_serializer: KernelSerializer | None = None, group: str | None = None, profile_id: str | UUID | None = None) -> KernelBatchTask[FutureType]Create a task containing one subtask per kernel.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
kernels | list[ir.Method] | required | Kernels to execute. |
arguments | list[dict] | None | None | Per-kernel argument dictionaries. Defaults to None. |
metadata | list[dict[str, Any]] | None | None | Per-kernel metadata dictionaries. Defaults to None. |
num_shots | list[int] | int | 1 | Shot count for each kernel, or one value to broadcast to every kernel. Defaults to 1. |
program_language | str | 'squin' | Program language to store in the task definition. Defaults to "squin". |
language_version | str | '0.1.0' | Semantic version of the program language to store in the task definition. Defaults to "0.1.0". |
kernel_serializer | KernelSerializer | None | None | Serializer for this task's kernels. When None, the device's `kernel_serializer` is used. Defaults to None. |
group | str | None | None | Name of the QLAM group for this task definition. When None, the configured group is used at submission time. |
profile_id | str | UUID | None | None | Task profile UUID for this task definition. String values are converted to `UUID`. Defaults to None, allowing QLAM to select the effective profile. |
Returns
KernelBatchTask[FutureType]A batch task object ready for dry-run or submission.
methodparameter_scan¶source
bloqade.core.device.device.Device.parameter_scan
Signature
def parameter_scan(kernel: ir.Method, arguments: list[dict], metadata: list[dict] | None = None, num_shots: list[int] | int = 1, program_language: str = 'squin', language_version: str = '0.1.0', kernel_serializer: KernelSerializer | None = None, group: str | None = None, profile_id: str | UUID | None = None) -> ParameterScanTask[FutureType]Create a parameter-scan task for one kernel.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
kernel | ir.Method | required | Kernel to execute for each parameter set. |
arguments | list[dict] | required | Argument dictionaries, one per subtask. |
metadata | list[dict] | None | None | Metadata dictionaries, one per subtask. Defaults to None. |
num_shots | list[int] | int | 1 | Shot count for each parameter set, or one value to broadcast to every subtask. Defaults to 1. |
program_language | str | 'squin' | Program language to store in the task definition. Defaults to "squin". |
language_version | str | '0.1.0' | Semantic version of the program language to store in the task definition. Defaults to "0.1.0". |
kernel_serializer | KernelSerializer | None | None | Serializer for the scanned kernel. When None, the device's `kernel_serializer` is used. Defaults to None. |
group | str | None | None | Name of the QLAM group for this task definition. When None, the configured group is used at submission time. |
profile_id | str | UUID | None | None | Task profile UUID for this task definition. String values are converted to `UUID`. Defaults to None, allowing QLAM to select the effective profile. |
Returns
ParameterScanTask[FutureType]A parameter-scan task object ready for dry-run or submission.