uniqc.backend_adapter.backend module¶

Unified backend management for quantum computing platforms.

This module provides a centralized Backend management system with: - Abstract base class QuantumBackend defining a unified interface - Factory pattern for backend instance creation/retrieval - Caching mechanism for backend instances - Integration with existing adapters (OriginQ, Quafu, IBM)

Usage:

# Get or create a backend instance
backend = get_backend('originq')

# List all available backends
available = list_backends_by_platform()

# Submit a circuit
task_id = backend.submit(circuit, shots=1000)

# Query task status
result = backend.query(task_id)

class uniqc.backend_adapter.backend.DummyBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: QuantumBackend

Local noisy simulator backend that mimics real quantum hardware.

This backend executes circuits locally using chip characterization data to derive realistic noise parameters, providing a faithful simulation of actual quantum hardware without cloud API access.

It is registered as "dummy" in the backend registry and can be used like any other backend:

from uniqc.backend_adapter.backend import get_backend

# From chip characterization
backend = get_backend("dummy:local:simulator", config={"chip_characterization": chip})
task_id = backend.submit(circuit, shots=1000)

# With explicit chip_id (fetches from OriginQ)
backend = get_backend("dummy:originq:WK_C180")

# Noiseless (perfect simulator)
backend = get_backend("dummy:local:simulator")

Configuration (config dict):

chip_characterization:: A ChipCharacterization object with per-qubit and per-pair calibration data. The backend converts T1/T2, gate fidelities, and readout errors into realistic noise parameters automatically.
chip_id:: OriginQ chip identifier (e.g. "WK_C180"). When set, the backend fetches the chip characterization from OriginQ and uses it to configure noise. Cannot be used together with chip_characterization.
noise_model:: Explicit noise model dict. Keys: depol_1q, depol_2q, depol (fallback). Overrides chip-derived noise.
available_qubits:: Number of qubits available for simulation.
available_topology:: List of [u, v] edges defining the connectivity graph.

Note

When neither chip_characterization nor chip_id is provided, the backend performs a noiseless (perfect) simulation.

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

is_available()[source]¶

Always available if C++ simulator is installed.

Return type:: bool

platform: ClassVar[str] = 'dummy'¶

class uniqc.backend_adapter.backend.IBMBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: QuantumBackend

Backend for IBM Quantum via Qiskit.

This backend connects to IBM Quantum services for executing quantum circuits on IBM quantum computers and simulators.

Proxy Configuration:: Proxies can be configured in multiple ways (in priority order): 1. Explicit config dict passed to constructor 2. Environment variables (HTTP_PROXY, HTTPS_PROXY) 3. config.yaml configuration file

Example

>>> # Using config file
>>> backend = get_backend('ibm')
>>> # Check proxy availability
>>> backend.check_proxy()
True
>>> # Test IBM connectivity
>>> result = backend.test_connectivity()
>>> print(result['success'])
True

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

check_proxy()[source]¶

Check if the configured proxy is available.

Returns:: True if proxy is configured and reachable, False otherwise.
Return type:: bool

Note

If no proxy is configured, returns True (direct connection).

get_proxy_config()[source]¶

Get the current proxy configuration.

Returns:: Dict with ‘http’ and/or ‘https’ proxy URLs, or None if not configured.
Return type:: dict[str, str] | None

platform: ClassVar[str] = 'ibm'¶

test_connectivity()[source]¶

Test connectivity to IBM Quantum services.

Returns:

success (bool)
message (str)
proxy_used (dict | None)
response_time_ms (float | None)

Return type:

dict with connectivity test results. Keys

class uniqc.backend_adapter.backend.OriginQBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: QuantumBackend

Backend for OriginQ Cloud (本源量子云).

This backend connects to the OriginQ Cloud service for executing quantum circuits on OriginQ quantum computers and simulators.

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

platform: ClassVar[str] = 'originq'¶

class uniqc.backend_adapter.backend.QuafuBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: QuantumBackend

Backend for BAQIS Quafu (ScQ) quantum cloud platform.

This backend connects to the Quafu service for executing quantum circuits on superconducting quantum computers.

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

VALID_CHIP_IDS = frozenset({'Dongling', 'ScQ-P10', 'ScQ-P10C', 'ScQ-P136', 'ScQ-P18'})¶

platform: ClassVar[str] = 'quafu'¶

validate_chip_id(chip_id)[source]¶

Validate if the chip ID is valid for Quafu.

Parameters:: chip_id (str) – The chip identifier to validate.
Returns:: True if the chip ID is valid.
Return type:: bool

class uniqc.backend_adapter.backend.QuantumBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: ABC

Abstract base class for quantum backend management.

This class provides a unified interface for all quantum computing backends, wrapping the underlying adapters and providing caching capabilities.

Variables:

name – The name of this backend instance.
platform (ClassVar[str]) – The platform identifier (e.g., ‘originq’, ‘quafu’, ‘ibm’).
adapter – The underlying quantum adapter instance.
config – Backend-specific configuration dictionary.

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

property adapter: QuantumAdapter¶

Get or create the underlying adapter instance.

Returns:: The quantum adapter for this backend.
Raises:: RuntimeError – If the adapter cannot be initialized.

clear_cache()[source]¶

Clear the cache for this backend instance.

Return type:: None

get_circuit_adapter()[source]¶

Get the circuit adapter for translating circuits.

Returns:: The quantum adapter that handles circuit translation.
Return type:: QuantumAdapter

classmethod get_instance(name=None, config=None, use_cache=True, cache_dir=None)[source]¶

Get or create a backend instance (factory method).

Parameters:

name (str | None) – Optional name for the instance.
config (dict[str, Any] | None) – Optional configuration dictionary.
use_cache (bool) – Whether to use/load cache. Defaults to True.
cache_dir (Path | str | None) – Optional custom cache directory.

Returns:

A backend instance.

Return type:

QuantumBackend

is_available()[source]¶

Check if this backend is available.

Returns:: True if the backend is properly configured and ready to use.
Return type:: bool

classmethod list_available()[source]¶

Check if this backend type is available.

Returns:: True if the backend can be instantiated and is configured.
Return type:: bool

classmethod load_from_cache(cache_dir=None)[source]¶

Load a backend instance from cache.

Parameters:: cache_dir (Path | str | None) – Optional custom cache directory path.
Returns:: Loaded backend instance or None if cache doesn’t exist or is invalid.
Return type:: QuantumBackend | None

platform: ClassVar[str] = ''¶

query(task_id)[source]¶

Query a task’s status and result.

Parameters:

task_id (str) – Task identifier.

Returns:

‘status’: ‘success’ | ‘failed’ | ‘running’
’result’: Execution result (when status is ‘success’ or ‘failed’)

Return type:

Dict with keys

query_batch(task_ids)[source]¶

Query multiple tasks’ status and merge results.

Parameters:: task_ids (list[str]) – List of task identifiers.
Returns:: ‘status’, ‘result’ (list of results).
Return type:: Dict with keys

save_to_cache()[source]¶

Save this backend instance configuration to cache.

Return type:: None

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

Submit a circuit to the backend.

Parameters:

circuit (Any) – Provider-native circuit object or OriginIR string.
shots (int) – Number of measurement shots.
**kwargs (Any) – Additional provider-specific parameters.

Returns:

Task ID assigned by the backend.

Return type:

str

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

Submit multiple circuits as a batch.

Parameters:

circuits (list[Any]) – List of provider-native circuit objects or OriginIR strings.
shots (int) – Number of measurement shots.
**kwargs (Any) – Additional provider-specific parameters.

Returns:

Task ID(s) assigned by the backend.

Return type:

str | list[str]

translate_circuit(originir)[source]¶

Translate an OriginIR circuit to the platform’s native format.

Parameters:: originir (str) – Circuit in OriginIR format.
Returns:: Provider-specific circuit object.
Return type:: Any

class uniqc.backend_adapter.backend.QuarkBackend(name=None, config=None, cache_dir=None)[source]¶

Bases: QuantumBackend

Backend for QuarkStudio / Quafu-SQC.

This backend uses the quarkstudio package and submits OpenQASM 2.0 task dictionaries through quark.Task.

Parameters:

name (str | None)
config (dict[str, Any] | None)
cache_dir (Path | str | None)

platform: ClassVar[str] = 'quark'¶

uniqc.backend_adapter.backend.clear_backend_cache(cache_dir=None)[source]¶

Clear all backend caches.

Parameters:: cache_dir (Path | str | None) – Optional custom cache directory. Uses default if None.
Return type:: None

uniqc.backend_adapter.backend.get_backend(name, *, config=None, use_cache=True, cache_dir=None)[source]¶

Get or create a backend instance by name.

This is the main factory function for obtaining backend instances. It uses the BACKENDS registry to look up the appropriate backend class and returns a configured instance.

Parameters:

name (str) – The platform name (‘originq’, ‘quafu’, ‘quark’, ‘ibm’, or ‘dummy’).
config (dict[str, Any] | None) – Optional configuration dictionary for the backend.
use_cache (bool) – Whether to use cache. Defaults to True.
cache_dir (Path | str | None) – Optional custom cache directory path.

Returns:

A configured QuantumBackend instance.

Raises:

ValueError – If the backend name is not recognized.
RuntimeError – If the backend cannot be initialized.

Return type:

QuantumBackend

Example

>>> backend = get_backend('originq')
>>> task_id = backend.submit(circuit, shots=1000)

uniqc.backend_adapter.backend.list_backends()[source]¶

Return a flat list of registered backend names.

Returns:: Sorted list of backend name strings, e.g. ['ibm', 'originq', 'quafu', 'quark'].
Return type:: list[str]

Example

>>> list_backends()
['dummy', 'ibm', 'originq', 'quafu', 'quark']

uniqc.backend_adapter.backend.list_backends_by_platform()[source]¶

List all backends grouped by platform with detailed status.

Returns:

A dictionary mapping backend names to their information, e.g.:

{
    'originq': {'available': True, 'platform': 'originq'},
    'quafu': {'available': False, 'platform': 'quafu'},
    ...
}

Return type:

dict[str, dict[str, Any]]

Example

>>> backends = list_backends_by_platform()
>>> for name, info in backends.items():
...     print(f"{name}: {'available' if info['available'] else 'unavailable'}")

uniqc.backend_adapter.backend.register_backend(name, backend_class, allow_override=False)[source]¶

Parameters:

name (str) – The platform name to register.
backend_class (type[QuantumBackend]) – The backend class to register.
allow_override (bool) – Whether to allow overriding existing registrations.

Raises:

ValueError – If the name is already registered and override is False.

Return type:

None

Example

>>> class MyBackend(QuantumBackend):
...     platform = "my_platform"
...     def _create_adapter(self):
...         return MyAdapter()
...
>>> register_backend("my_platform", MyBackend)

uniqc.backend_adapter.backend.unregister_backend(name)[source]¶

Unregister a backend.

Parameters:: name (str) – The platform name to unregister.
Raises:: ValueError – If the backend is not registered.
Return type:: None