Skip to content

bloqade.core.device.device.Device

← Module overview

classDevicesource

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

NameTypeDefaultDescription
context_namestrrequired
qpu_modestr | NoneNone
program_languagestr'squin'
language_versionstr'0.1.0'
future_clstype[FutureType]Future
kernel_serializerKernelSerializerJSONSerializer()
validation_suiteValidationSuite | NoneNone
dialect_groupir.DialectGroup | NoneNone

Attributes

NameTypeDescription
qpu_modestr | NoneExplicit qlam QPU mode used by tasks created from this device. When None, qlam-core resolves it from configuration.
program_languagestrLanguage name placed on builder-generated task definitions. Defaults to ``"squin"``.
language_versionstrLanguage version used when serializing builder kernels. Defaults to ``"0.1.0"``.
future_clstype[FutureType]Future class used by tasks created from this device. Defaults to `Future`.
kernel_serializerKernelSerializerDefault 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_asyncsource

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 | None

Validate 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

NameTypeDefaultDescription
task_builderTaskBuilderrequiredIncrementally assembled task to finalize.
dry_runboolrequired
groupstr | NoneNone
profile_idstr | UUID | NoneNone
storageStorageBackend | NoneNone
fetch_optionsApiFetchOptionsDEFAULT_FETCH_OPTIONS

Other Parameters

NameTypeDescription
dry_runboolWhen true, print a preview without submitting. When false, submit and return a future.
groupstr | NoneOptional QLAM group name or UUID string for this submission. Defaults to configured group precedence.
profile_idstr | UUID | NoneOptional task profile UUID. Used when the finalized task definition does not already specify a profile. Defaults to None.
storageStorageBackend | NoneStorage for the submitted task definition. Ignored during a dry run.
fetch_optionsApiFetchOptionsFetch 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.

source

methodsubmit_task_definitionsource

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) -> FutureType

Submit 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

NameTypeDefaultDescription
task_definitionTaskDefinitionrequired
storageStorageBackend | NoneNone
fetch_optionsApiFetchOptionsDEFAULT_FETCH_OPTIONS
groupstr | NoneNone
profile_idstr | UUID | NoneNone

Other Parameters

NameTypeDescription
task_definitionTaskDefinitionTask definition to submit.
storageStorageBackend | NoneStorage backend that will receive the task definition. When None, a fresh `DictStorage` is used (in-memory; not persisted across processes). Defaults to None.
fetch_optionsApiFetchOptionsPagination and polling options attached to the returned future. Defaults to `ApiFetchOptions()`.
groupstr | NoneOptional QLAM group name or UUID string. Used when `task_definition.group_id` is None. Defaults to configured group precedence.
profile_idstr | UUID | NoneOptional 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

TypeDescription
ValueErrorIf the backend response is missing a task ID.
source

methodtasksource

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

NameTypeDefaultDescription
kernelir.MethodrequiredThe kernel to execute.
num_shotsint1Number of shots to run for the kernel. Defaults to 1.
argumentsdict | NoneNoneArgument dictionary for the kernel. Defaults to None.
metadatadict | NoneNoneMetadata for the single subtask. When provided, it is wrapped in a one-element list to match the task API. Defaults to None.
program_languagestr'squin'Program language to store in the task definition. Defaults to "squin".
language_versionstr'0.1.0'Semantic version of the program language to store in the task definition. Defaults to "0.1.0".
kernel_serializerKernelSerializer | NoneNoneSerializer for this task's kernel. When None, the device's `kernel_serializer` is used. Defaults to None.
groupstr | NoneNoneName of the QLAM group for this task definition. When None, the configured group is used at submission time.
profile_idstr | UUID | NoneNoneTask 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.

source

methodbatch_tasksource

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

NameTypeDefaultDescription
kernelslist[ir.Method]requiredKernels to execute.
argumentslist[dict] | NoneNonePer-kernel argument dictionaries. Defaults to None.
metadatalist[dict[str, Any]] | NoneNonePer-kernel metadata dictionaries. Defaults to None.
num_shotslist[int] | int1Shot count for each kernel, or one value to broadcast to every kernel. Defaults to 1.
program_languagestr'squin'Program language to store in the task definition. Defaults to "squin".
language_versionstr'0.1.0'Semantic version of the program language to store in the task definition. Defaults to "0.1.0".
kernel_serializerKernelSerializer | NoneNoneSerializer for this task's kernels. When None, the device's `kernel_serializer` is used. Defaults to None.
groupstr | NoneNoneName of the QLAM group for this task definition. When None, the configured group is used at submission time.
profile_idstr | UUID | NoneNoneTask 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.

source

methodparameter_scansource

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

NameTypeDefaultDescription
kernelir.MethodrequiredKernel to execute for each parameter set.
argumentslist[dict]requiredArgument dictionaries, one per subtask.
metadatalist[dict] | NoneNoneMetadata dictionaries, one per subtask. Defaults to None.
num_shotslist[int] | int1Shot count for each parameter set, or one value to broadcast to every subtask. Defaults to 1.
program_languagestr'squin'Program language to store in the task definition. Defaults to "squin".
language_versionstr'0.1.0'Semantic version of the program language to store in the task definition. Defaults to "0.1.0".
kernel_serializerKernelSerializer | NoneNoneSerializer for the scanned kernel. When None, the device's `kernel_serializer` is used. Defaults to None.
groupstr | NoneNoneName of the QLAM group for this task definition. When None, the configured group is used at submission time.
profile_idstr | UUID | NoneNoneTask 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.

source