uniqc.backend_adapter.preflight module

Backend preflight: hard checks before running anything on a backend.

This module enforces a strict policy before any execution path that talks to a real provider (or to a dummy:<provider>:<chip> noisy simulator that depends on real provider data):

1. Required dependency installed. If a backend identifier names a provider whose SDK is missing, raise MissingDependencyError with a precise install hint.

2. Chip characterization cache present and fresh. For backends that carry a <provider>:<chip> tag, look up the cached ChipCharacterization. If absent or older than max_age_hours, attempt to refresh via the provider SDK. On refresh failure, raise the underlying error verbatim.

3. No silent fallbacks. There is no “fall back to whatever cache we have lying around” path: the pipeline either has the data the backend identifier claims or it stops.

Backend identifier grammar

local pure local simulator (no chip data) local:simulator alias of local dummy:local:simulator alias of local dummy:local:virtual-line-N line-topology local simulator dummy:local:virtual-grid-RxC grid-topology local simulator dummy:local:mps-linear-N[:k=v...] MPS local simulator dummy:virtual:<name> user-defined noisy virtual machine dummy:<provider>:<chip> noisy local sim using provider chip data <provider>:<chip> direct submission to the provider <provider> provider with default chip

exception uniqc.backend_adapter.preflight.BackendPreflightError

Bases: RuntimeError

Raised when a backend’s pre-execution checks fail.

Examples: chip cache cannot be fetched, refresh failed because the provider SDK threw, etc. The underlying cause is chained via __cause__ so callers can inspect it.

class uniqc.backend_adapter.preflight.BackendTarget(raw, kind, provider=None, chip_name=None, topology_spec=None, mps_kwargs=None, virtual_name=None)

Bases: object

Parsed backend identifier.

kind is one of:

• "local": pure local simulator (no provider data)

• "local_topology": local sim with synthetic virtual topology

• "local_mps": local MPS simulator on a linear chain

• "virtual": user-defined noisy virtual machine (YAML config)

• "dummy_provider": noisy local sim using provider chip data

• "provider": direct submission to a real provider

For dummy_provider and provider, provider and chip_name are populated. For virtual, virtual_name holds the config name under ~/.uniqc/backend/virtual/.

chip_name

kind

mps_kwargs

property needs_provider_sdk

provider

raw

topology_spec

virtual_name

uniqc.backend_adapter.preflight.ensure_backend_ready(backend, *, max_age_hours=None, refresh=None)

Perform every pre-execution check for backend and return chip data.

Parameters:

• backend – Backend identifier (see module docstring grammar).

• max_age_hours – If set and the chip cache is older than this, attempt a refresh. None (default) disables age-based refresh — only missing-cache triggers a refresh attempt.

• refresh – True to force-refresh, False to forbid refresh, None (default) to follow the policy above.

Returns:

The loaded ChipCharacterization for any backend that carries a <provider>:<chip> tag, otherwise None for pure local backends.

Raises:

• MissingDependencyError – Required SDK / extension missing.

• BackendPreflightError – Cache refresh failed, or any other pre-execution check tripped.

• ValueError – Malformed backend identifier.

uniqc.backend_adapter.preflight.has_provider_credentials(provider)

Return True iff the provider has its API token / config set up.

Uses the standard uniqc.config.load_<provider>_config() loaders; they raise when credentials are missing. Returns False for unknown providers (no credentials = nothing to detect). Does not hit the network.

uniqc.backend_adapter.preflight.parse_backend_target(name)

Parse a backend identifier into a BackendTarget.

Raises ValueError for malformed identifiers. The bare aliases "dummy" and "dummy:local" are no longer accepted — callers must use the canonical "dummy:local:simulator" form (or just "local").