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:<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[source]

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)[source]

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

  • "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.

Parameters:

  • raw (str)

  • kind (str)

  • provider (str | None)

  • chip_name (str | None)

  • topology_spec (str | None)

  • mps_kwargs (dict[str, Any] | None)

chip_name: str | None
kind: str
mps_kwargs: dict[str, Any] | None
property needs_provider_sdk: bool
provider: str | None
raw: str
topology_spec: str | None
uniqc.backend_adapter.preflight.ensure_backend_ready(backend, *, max_age_hours=None, refresh=None)[source]

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

Parameters:

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

  • max_age_hours (float | None) – 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 (bool | None) – 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:
Return type:

Any | None

uniqc.backend_adapter.preflight.has_provider_credentials(provider)[source]

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.

Parameters:

provider (str)

Return type:

bool

uniqc.backend_adapter.preflight.parse_backend_target(name)[source]

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").

Parameters:

name (str)

Return type:

BackendTarget