uniqc.backend_adapter.task.adapters.base module

Base adapter interface for quantum cloud backends.

Every backend adapter must implement this interface, providing: 1. Translation from OriginIR string to the provider’s native circuit type. 2. Task submission via the provider’s Python SDK (not raw REST). 3. Task status query and result retrieval. 4. Dry-run validation without making any network calls.

The adapter layer replaces all direct requests REST calls within the task modules. Each adapter is a stateful object that holds the provider session / client and configuration.

Dry-run Validation

Every adapter implements dry_run(originir, shots, **kwargs) to validate a circuit offline before submission. This checks:

  1. OriginIR parses without error.

  2. All gates are supported by the target backend.

  3. Qubit count fits within the backend’s limits.

  4. The native circuit object is structurally valid.

No cloud API calls are made. A dry-run success followed by actual submission failure is a critical bug — please report it at the issue tracker.

class uniqc.backend_adapter.task.adapters.base.QuantumAdapter[source]

Bases: ABC

Abstract base class for quantum cloud backend adapters.

Subclass this for each backend (originq_cloud, quafu, ibm, …). Each adapter is instantiated once per task module and reused.

Class attributes:

name: Adapter identifier. max_native_batch_size: Maximum number of circuits the adapter

can pack into a single platform-side job. uniqc relies on this to auto-shard oversized batches; see uniqc.backend_adapter.task_manager.submit_batch(). The base default is 1 (no native batching, one platform job per circuit). Adapters that natively support grouped submission override this — see OriginQAdapter (200, configurable via originq.task_group_size) and QiskitAdapter (100).

dry_run(originir, *, shots=1000, **kwargs)[source]

Validate a circuit without making network calls.

Subclasses must implement this method. The default implementation raises NotImplementedError.

Validation checklist (where determinable offline): 1. OriginIR parses without error. 2. All gates are supported by the target backend. 3. Qubit count fits within the backend’s limits. 4. The native circuit object is structurally valid.

This method must NOT make any cloud API calls. All checks must be local-only.

Parameters:

  • originir (str) – Circuit in OriginIR format.

  • shots (int) – Number of measurement shots (for shots-limit validation).

  • **kwargs (Any) – Adapter-specific options (e.g. chip_id for IBM/Quafu).

Returns:

DryRunResult with success=True/False, details, warnings, and metadata.

Raises:

NotImplementedError – Subclasses must implement this method.

Return type:

DryRunResult

Note

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

is_available()[source]

Return True if the required packages / credentials are configured.

Defaults to False so that subclasses must explicitly opt-in, avoiding the risk of an unconfigured adapter incorrectly reporting availability.

Return type:

bool

list_backends()[source]

Return raw backend metadata from the platform API.

Returns a list of dicts with at least a "name" key. The dict shape is platform-specific; the caller is responsible for normalising the data into BackendInfo objects.

Raises:

Exception – If the platform API call fails (auth error, network error, etc.). Subclasses should propagate the original exception type so callers can distinguish auth failures from network failures.

Return type:

list[dict[str, Any]]

max_native_batch_size: int = 1
name: str = 'base'
abstractmethod query(taskid)[source]

Query a single task’s status and result.

Parameters:

taskid (str) – Task identifier.

Returns:

  • status: 'success' | 'failed' | 'running'

  • result: execution result (present when status is 'success' or 'failed')

Return type:

dict with keys

abstractmethod query_batch(taskids)[source]

Query multiple tasks’ status and merge results.

Overall status is the worst case: 'failed' > 'running' > 'success'.

Parameters:

taskids (list[str]) – List of task identifiers.

Returns:

status, result (list of results).

Return type:

dict with keys

abstractmethod submit(circuit, *, shots=1000, **kwargs)[source]

Submit a circuit to the backend and return a task ID.

Parameters:

  • circuit (Any) – Provider-native circuit object (result of translate_circuit).

  • shots (int) – Number of measurement shots.

  • **kwargs (Any) – Additional provider-specific parameters (e.g. chip_id, auto_mapping, circuit_optimize).

Returns:

Task ID assigned by the backend.

Return type:

str

abstractmethod submit_batch(circuits, *, shots=1000, **kwargs)[source]

Submit multiple circuits as a single batch.

Parameters:

  • circuits (list[Any]) – List of provider-native circuit objects.

  • shots (int) – Number of measurement shots.

  • **kwargs (Any) – Additional provider-specific parameters.

Returns:

Task IDs (one per circuit), or a single task ID if the backend returns a group ID.

Return type:

list[str]

abstractmethod translate_circuit(originir)[source]

Translate an OriginIR circuit string to the provider’s native circuit type.

Parameters:

originir (str) – Circuit in OriginIR format.

Returns:

Provider-specific circuit object.

Return type:

Any