bloqade.core.device.task.TaskABC

← Module overview

classTaskABC¶source

bloqade.core.device.task.TaskABC

Bases: AuthMixin, ABC, Generic[FutureType]

Abstract base class for kernel tasks.

Signature

class TaskABC(*, context_name: str, qpu_mode: str | None = None, program_language: str, language_version: str = '0.1.0', kernel_serializer: KernelSerializer = JSONSerializer(), group: str | None = None, profile_id: str | UUID | None = None, future_cls: type[FutureType] = Future)

A task collects one or more kernels and per-subtask metadata into a TaskDefinition that can be dry-run or submitted to the backend.

Parameters

Name	Type	Default	Description
context_name	str	required
qpu_mode	str | None	None
program_language	str	required
language_version	str	'0.1.0'
kernel_serializer	KernelSerializer	JSONSerializer()
group	str | None	None
profile_id	str | UUID | None	None
future_cls	type[FutureType]	Future

Attributes

Name	Type	Description
qpu_mode	str | None	Explicit qlam QPU mode used for task submission. When None, qlam-core resolves it from configuration.
program_language	str	Program language identifier stored on the task definition and used when serializing kernels.
language_version	str	Program language version stored on the task definition and used when serializing kernels. Must be a semantic version. Set this directly for a static version, or override the `program_language_version` property if the version needs additional logic. Defaults to "0.1.0".
kernel_serializer	KernelSerializer	Serializer used by the default `serialize_kernel` implementation. It must provide an `encode` method compatible with the value returned by `kernel.dialects.encode(...)`. If `encode` returns bytes, the bytes are base64-encoded before being stored in `Program.content`; if it returns str, the value is used unchanged. Defaults to `kirin.serialization.JSONSerializer`.
future_cls	type[FutureType]	Future class used to construct the return value of `submit_task_definition`. Defaults to `Future`.
group	str | None	Name of the QLAM group for the task definition. When None, the `~/.qsh` config group (`plugins.tasks.group`, then `defaults.group`) is applied at submission time; when that is also unset, QLAM selects the backend default group. Defaults to None.
profile_id	str | UUID | None	Task profile UUID for the task definition. String values are converted to `UUID`. Defaults to None, allowing QLAM to select the effective profile.

propertyprogram_language_version¶source

bloqade.core.device.task.TaskABC.program_language_version

program_language_version: str

Program language version recorded when serializing kernels.

Defaults to the language_version attribute. Override this property in a subclass if the version needs to be computed with additional logic. The value must be a semantic version.

Returns

strstr: Semantic version string.

source

methodserialize_kernel¶source

bloqade.core.device.task.TaskABC.serialize_kernel

def serialize_kernel(kernel: ir.Method) -> str

Serialize a kernel into content suitable for the backend.

The default implementation first converts the kernel to a Kirin serialization module using program_language_version, then passes that module to kernel_serializer.encode. Binary serializer output is base64-encoded so it can travel through the API’s string-valued Program.content field. String serializer output is returned as produced by the serializer.

Parameters

Name	Type	Description
kernel	ir.Method	Kernel to serialize.

Returns

strstr: Serialized kernel content for the submitted `Program`.

source

propertynum_subtasks¶source

bloqade.core.device.task.TaskABC.num_subtasks

num_subtasks: int

Number of subtasks in this task’s definition.

source

methodsummary¶source

bloqade.core.device.task.TaskABC.summary

def summary() -> str

Return a human-readable summary printed on dry-run.

Returns

strstr: Summary describing what would be submitted.

source

methodvalidate_arguments¶source

bloqade.core.device.task.TaskABC.validate_arguments

def validate_arguments() -> None

Validate that argument and metadata lengths match subtask count.

Raises

Type	Description
ValueError	If arguments or metadata length differs from `num_subtasks`.

source

methodget_kernels¶source

bloqade.core.device.task.TaskABC.get_kernels

def get_kernels() -> list[ir.Method]

Return the kernels used to build the task’s programs.

Returns

list[ir.Method]Kernels in program-index order.

source

methodget_arguments¶source

bloqade.core.device.task.TaskABC.get_arguments

def get_arguments() -> list[dict] | None

Return per-subtask argument dictionaries.

Returns

list[dict] | NoneOne argument dictionary per subtask, or None when no arguments are set.

source

methodget_metadata¶source

bloqade.core.device.task.TaskABC.get_metadata

def get_metadata() -> list[dict] | None

Return per-subtask metadata dictionaries.

Returns

list[dict] | NoneOne metadata dictionary per subtask, or None when no metadata is set.

source

methodget_num_shots¶source

bloqade.core.device.task.TaskABC.get_num_shots

def get_num_shots() -> list[int]

Return the per-subtask shot counts.

Returns

list[int]Shot count for each subtask, in subtask order.

source

methodprograms¶source

bloqade.core.device.task.TaskABC.programs

def programs() -> list[Program]

Build the program list for the task definition.

Returns

list[Program]One `Program` per kernel returned by `get_kernels`, serialized via `serialize_kernel`.

source

methodprogram_index_for_subtask¶source

bloqade.core.device.task.TaskABC.program_index_for_subtask

def program_index_for_subtask(i: int) -> int

Return the program index used by subtask i.

The default implementation maps each subtask to its own program. Parameter-scan tasks override this to reuse a single program.

Parameters

Name	Type	Description
i	int	Subtask index.

Returns

intint: Program index.

source

methodcreate_task_definition¶source

bloqade.core.device.task.TaskABC.create_task_definition

def create_task_definition() -> TaskDefinition

Build a TaskDefinition from this task’s kernels and subtasks.

Override this method directly if your use-case doesn’t fit the API contract.

Returns

TaskDefinitionTaskDefinition: Definition ready to be submitted.

source

methodrun_async¶source

bloqade.core.device.task.TaskABC.run_async

Signature

def run_async(*, dry_run: bool, storage: StorageBackend | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS) -> FutureType | None

Validate the task and either dry-run or submit it.

Parameters

Name	Type	Default	Description
dry_run	bool	required
storage	StorageBackend | None	None
fetch_options	ApiFetchOptions	DEFAULT_FETCH_OPTIONS

Other Parameters

Name	Type	Description
dry_run	bool	When True, print a summary and return None. When False, submit the task and return a future.
storage	StorageBackend | None	Storage backend that will receive the task definition and later fetched shots. 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()`.

Returns

FutureType | NoneFuture attached to the submitted task when `dry_run` is False; otherwise None.

Raises

Type	Description
ValueError	If argument or metadata lengths do not match `num_subtasks`.

source

methodsubmit_task_definition¶source

bloqade.core.device.task.TaskABC.submit_task_definition

Signature

def submit_task_definition(*, task_definition: TaskDefinition, storage: StorageBackend | None = None, fetch_options: ApiFetchOptions = DEFAULT_FETCH_OPTIONS) -> 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 task object’s profile_id. The task-level value fills the profile only when the prepared 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

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()`.

Returns

FutureTypeFutureType: Future attached to the created task ID.

Raises

Type	Description
ValueError	If the backend response is missing a task ID.

source