bloqade.core.device.result.Result

← Module overview

classResult¶source

bloqade.core.device.result.Result

Result view over stored shots.

Signature

class Result(*, storage: StorageBackend, shot_filter: ShotFilter = _default_shot_filter())

Public import paths

• from bloqade.core.device import Result
• from bloqade.core.device.future import Result

Merge-oriented methods assume each selected task ID has the same subtask structure.

Parameters

Name	Type	Default	Description
storage	StorageBackend	required
shot_filter	ShotFilter	_default_shot_filter()

Attributes

Name	Type	Description
storage	StorageBackend	Storage backend that holds shots and task metadata.
shot_filter	ShotFilter	Filter used when reading shots and deriving subtask scope. Defaults to the DETECTED frame type.

propertystorage_filter¶source

bloqade.core.device.result.Result.storage_filter

storage_filter: StorageFilter

Return the subtask-level portion of shot_filter.

Returns

StorageFilterStorageFilter: Filter containing task IDs, subtask indices, and task-subtask pairs from `shot_filter`.

source

methodvalidate¶source

bloqade.core.device.result.Result.validate

def validate() -> None

Validate that selected task IDs can be merged by subtask index.

Compatible task IDs have the same program_index and equal arguments for each shared subtask_index. Different shot counts are allowed, and None and empty dictionaries are treated as equivalent arguments.

Raises

Type	Description
ValueError	If selected task IDs disagree on `program_index` or arguments for the same `subtask_index`.

source

methodshot_results¶source

bloqade.core.device.result.Result.shot_results

def shot_results(verify: bool = True) -> list[np.ndarray]

Return physical shot bitstrings grouped by merged subtask.

Parameters

Name	Type	Default	Description
verify	bool	True	Whether to validate that selected task IDs can be merged before reading shots. Defaults to True.

Returns

list[np.ndarray]One two-dimensional boolean array per merged subtask, ordered by subtask index.

Raises

Type	Description
ValueError	If `verify` is True and selected task IDs cannot be merged.

source

methodarguments¶source

bloqade.core.device.result.Result.arguments

def arguments(verify: bool = True) -> list[dict | None]

Return subtask arguments after merging selected task IDs.

Parameters

Name	Type	Default	Description
verify	bool	True	Whether to validate that selected task IDs can be merged before reading arguments. Defaults to True.

Returns

list[dict | None]One arguments entry per merged subtask, ordered by subtask index.

Raises

Type	Description
ValueError	If `verify` is True and selected task IDs cannot be merged.

source

methodfull_arguments¶source

bloqade.core.device.result.Result.full_arguments

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

Return all stored subtask arguments without merging task IDs.

Returns

list[dict | None]Arguments for every selected stored subtask row, including `None` for rows without arguments.

source

methodsubtasks¶source

bloqade.core.device.result.Result.subtasks

def subtasks(verify: bool = True) -> list[dict]

Return subtasks merged across selected task IDs.

The merged view is ordered by subtask_index, removes ambiguous per-task fields (task_id and metadata), and aggregates num_shots. Use full_subtasks when task IDs or metadata must be preserved.

Parameters

Name	Type	Default	Description
verify	bool	True	Whether to validate that selected task IDs can be merged before returning subtasks. Defaults to True.

Returns

list[dict]Merged subtask dictionaries ordered by subtask index.

Raises

Type	Description
ValueError	If `verify` is True and selected task IDs cannot be merged.

source

methodfull_subtasks¶source

bloqade.core.device.result.Result.full_subtasks

def full_subtasks() -> list[dict]

Return selected stored subtasks without merging task IDs.

If selected task IDs share the same subtask structure, this view contains one row per task and subtask.

Returns

list[dict]Full subtask dictionaries selected by `storage_filter`.

source

methodgroup_shots_by_metadata¶source

bloqade.core.device.result.Result.group_shots_by_metadata

Signature

def group_shots_by_metadata(shots: Sequence[Sequence[ShotValue]], metadata_keys: Sequence[str]) -> dict[tuple[Hashable, ...], list[ShotValue]]

Aggregate per-subtask shots by selected user-metadata values.

shots must contain one sequence per entry of subtasks, in that same order. For a result merged from multiple task IDs, every full subtask contributing to one merged subtask must agree on the requested metadata values.

Parameters

Name	Type	Description
shots	Sequence[Sequence[ShotValue]]	Per-subtask shot sequences to aggregate.
metadata_keys	Sequence[str]	User-metadata keys whose values form each group key.

Returns

(dict[tuple[Hashable, ...], list[ShotValue]], dict[tuple[Hashable, ...], list[ShotValue]], dict[tuple[Hashable, ...], list[ShotValue]])A dictionary mapping metadata-value tuples to flattened shot lists. The order within each list follows ``subtasks()`` order, then the order supplied within each corresponding shot sequence.

Raises

Type	Description
ValueError	If ``shots`` does not align with the selected merged subtasks, a full subtask has invalid/missing user metadata, a requested key is missing, metadata disagrees across merged task IDs, or a key value is unhashable.

source

methodtask_ids¶source

bloqade.core.device.result.Result.task_ids

def task_ids() -> set[str]

Return task IDs selected by this result view.

Returns

set[str]Task IDs from `shot_filter.task_ids` when set; otherwise all task IDs known to storage.

source

methodwhere_subtasks¶source

bloqade.core.device.result.Result.where_subtasks

def where_subtasks(predicate: Callable[[dict], bool]) -> Self

Return a result narrowed to subtasks matching a predicate.

The predicate sees only subtasks in the scope of self.shot_filter; the returned result inherits that scope intersected with the matches.

Parameters

Name	Type	Description
predicate	Callable[[dict], bool]	Predicate applied to each selected subtask dictionary.

Returns

SelfSelf: A narrowed result view.

source

methodwhere_arguments¶source

bloqade.core.device.result.Result.where_arguments

def where_arguments(predicate: Callable[[dict | None], bool]) -> Self

Return a result narrowed by subtask arguments.

The predicate sees only subtasks in the scope of self.shot_filter; the returned result inherits that scope intersected with the matches.

NOTE: the Subtask model coerces bool values in arguments to float (True -> 1.0, False -> 0.0). Predicates that rely on identity (is True) or strict types will silently match nothing for bool-valued arguments. Use == 1 or > 0 instead, or store non-bool discriminators.

Parameters

Name	Type	Description
predicate	Callable[[dict | None], bool]	Predicate applied to each selected subtask's arguments.

Returns

SelfSelf: A narrowed result view.

source

methodwhere_metadata¶source

bloqade.core.device.result.Result.where_metadata

def where_metadata(predicate: Callable[[dict | None], bool]) -> Self

Return a result narrowed by JSON-decoded user metadata.

Expects user_metadata to be a JSON-serialized dict; non-JSON values raise. To filter on raw strings instead, use where_subtasks and parse manually. The predicate sees only subtasks in the scope of self.shot_filter; the returned result inherits that scope intersected with the matches.

Parameters

Name	Type	Description
predicate	Callable[[dict | None], bool]	Predicate applied to each selected subtask's decoded `user_metadata`.

Returns

SelfSelf: A narrowed result view.

source

methodwhere_shots¶source

bloqade.core.device.result.Result.where_shots

Signature

def where_shots(predicate: Callable[[ShotResult], bool], predicate_filter: ShotFilter | None = None) -> Self

Return a result narrowed by shot-level predicate.

predicate_filter selects the shots the predicate evaluates against; defaults to self.shot_filter (predicate sees the same shots the current result fetches). The returned result inherits self.shot_filter’s scope (notably frame_type) intersected with the matching shot pairs.

To precondition on one frame and return another, such as SORTED-was-all-1 -> DETECTED, pass predicate_filter=replace(self.shot_filter, frame_type='SORTED').

Parameters

Name	Type	Default	Description
predicate	Callable[[ShotResult], bool]	required	Predicate applied to each shot selected by `predicate_filter`.
predicate_filter	ShotFilter | None	None	Filter used only for predicate evaluation. When None, `self.shot_filter` is used. Defaults to None.

Returns

SelfSelf: A narrowed result view.

source