uniqc.backend_adapter.task.result_types module

Unified result types for all quantum backends.

This module defines a standardized result format that all platform adapters must convert their outputs to. This ensures consistent handling of results regardless of which quantum cloud platform was used.

The UnifiedResult dataclass provides: - Measurement counts and probabilities in a consistent format - Platform identification and task metadata - Optional advanced results (expectation values, statevector) - Raw platform result for debugging

Usage:

# Create from counts
result = UnifiedResult.from_counts(
    counts={"00": 512, "11": 488},
    platform="quafu",
    task_id="abc123"
)

# Create from probabilities
result = UnifiedResult.from_probabilities(
    probabilities={"00": 0.512, "11": 0.488},
    shots=1000,
    platform="originq",
    task_id="xyz789"
)

class uniqc.backend_adapter.task.result_types.DryRunResult(success, details, warnings=(), error=None, error_kind=None, backend_name=None, circuit_qubits=None, supported_gates=())

Bases: object

Result of a dry-run circuit validation.

A dry-run validates circuit translatability and backend compatibility WITHOUT making any cloud API calls.

Variables:

• success (bool) – True if the circuit passed all validation checks.

• details (str) – Human-readable description of what was checked and the outcome.

• warnings (tuple[str, ...]) – Non-fatal warnings (e.g., no chip_id provided, partial validation).

• error (str | None) – Error message if success is False.

• error_kind (str | None) –

  Coarse classification of error so callers can branch on why the dry-run failed without parsing the message. One of:

  • "unknown_backend" — backend identifier not recognised

  • "sdk_missing" — required platform SDK / extra not installed

  • "credential_missing" — auth token / config missing

  • "circuit_invalid" — translation or basis-set check failed

  • "adapter_init" — adapter constructor itself raised

  • "unknown" — anything not yet classified

  None when success is True.

• backend_name (str | None) – The backend/chip ID used for this dry-run.

• circuit_qubits (int | None) – Number of qubits in the circuit (extracted from OriginIR QINIT line, without making any API call).

• supported_gates (tuple[str, ...]) – Gates confirmed available on the target backend that are also used by this circuit.

Parameters:

• success (bool)

• details (str)

• warnings (tuple[str, ...])

• error (str | None)

• error_kind (str | None)

• backend_name (str | None)

• circuit_qubits (int | None)

• supported_gates (tuple[str, ...])

Note

Any dry-run success followed by actual submission failure is a critical bug. Please report it at the UnifiedQuantum issue tracker.

backend_name: str | None

circuit_qubits: int | None

details: str

error: str | None

error_kind: str | None

success: bool

supported_gates: tuple[str, ...]

warnings: tuple[str, ...]

class uniqc.backend_adapter.task.result_types.UnifiedResult(counts, probabilities, shots, platform, task_id, backend_name=None, execution_time=None, raw_result=None, error_message=None)

Bases: object

Unified quantum execution result format.

All platform adapters must normalize their output to this format, ensuring consistent result handling across different quantum backends.

Variables:

• counts (dict[str, int]) – Measurement counts as dict mapping bitstrings to counts. Example: {“00”: 512, “11”: 488}

• probabilities (dict[str, float]) – Measurement probabilities as dict mapping bitstrings to probs. Example: {“00”: 0.512, “11”: 0.488}

• shots (int) – Total number of shots executed.

• platform (str) – Platform identifier (‘originq’, ‘quafu’, ‘ibm’, ‘dummy’).

• task_id (str) – Unique task identifier from the platform.

• backend_name (str | None) – Name of the quantum backend/hardware used (optional).

• execution_time (float | None) – Execution time in seconds (optional).

• raw_result (Any) – Original platform result object for debugging (optional).

• error_message (str | None) – Error message if execution failed (optional).

Parameters:

• counts (dict[str, int])

• probabilities (dict[str, float])

• shots (int)

• platform (str)

• task_id (str)

• backend_name (str | None)

• execution_time (float | None)

• raw_result (Any)

• error_message (str | None)

Example

>>> result = UnifiedResult.from_counts(
...     counts={"00": 512, "11": 488},
...     platform="quafu",
...     task_id="task-123"
... )
>>> print(result.probabilities)
{'00': 0.512, '11': 0.488}

backend_name: str | None = None

counts: dict[str, int]

error_message: str | None = None

execution_time: float | None = None

classmethod from_counts(counts, platform, task_id, **kwargs)

Create UnifiedResult from measurement counts.

Probabilities are automatically computed from counts.

Parameters:

• counts (dict[str, int]) – Dict mapping bitstrings to measurement counts.

• platform (str) – Platform identifier.

• task_id (str) – Task identifier.

• **kwargs (Any) – Additional attributes (backend_name, execution_time, etc.).

Returns:

UnifiedResult instance with computed probabilities.

Return type:

UnifiedResult

Example

>>> result = UnifiedResult.from_counts(
...     {"00": 512, "11": 488}, "quafu", "task-1"
... )

classmethod from_probabilities(probabilities, shots, platform, task_id, **kwargs)

Create UnifiedResult from probability distribution.

Counts are computed by multiplying probabilities by shots count.

Parameters:

• probabilities (dict[str, float]) – Dict mapping bitstrings to probabilities.

• shots (int) – Number of shots used.

• platform (str) – Platform identifier.

• task_id (str) – Task identifier.

• **kwargs (Any) – Additional attributes.

Returns:

UnifiedResult instance with computed counts.

Return type:

UnifiedResult

Example

>>> result = UnifiedResult.from_probabilities(
...     {"00": 0.5, "11": 0.5}, 1000, "originq", "task-2"
... )

get(key, default=None)

Parameters:

• key (str)

• default (Any)

Return type:

Any

get_expectation(observable='Z')

Compute expectation value for a simple observable.

Currently only supports single-qubit Z expectation value computed from the first qubit’s measurement results.

Parameters:

observable (str) – Observable type (currently only ‘Z’ supported).

Returns:

Expectation value in range [-1, 1].

Return type:

float

Note

This is a simplified implementation. For complex observables, use uniqc.analyzer module.

items()

keys()

platform: str

probabilities: dict[str, float]

raw()

Return the original platform-specific raw result.

This is the unprocessed object/dict returned by the backend adapter before normalization. Use it for debugging, accessing platform-specific fields, or when you need the exact wire-format response.

Returns:

The raw_result attribute (may be None if not preserved).

Return type:

Any

raw_result: Any = None

shots: int

task_id: str

to_dict()

Return flat counts dict for unified output.

All platform adapters normalize their results to this format, ensuring consistent return types regardless of which quantum cloud backend was used.

Returns:

Flat dict mapping bitstrings to measurement counts. Example: {“00”: 512, “1111”: 488}

Return type:

dict[str, int]

to_json_dict()

Return a JSON-serializable representation.

Includes counts, probabilities, shots, platform identifiers and optional metadata. The raw_result field is intentionally omitted because it may hold arbitrary platform-specific objects that are not JSON-serializable; access it via raw() if needed.

Returns:

A plain dict with primitive (JSON-friendly) values only.

Return type:

dict[str, Any]

values()