uniqc.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()

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

# Query task status
result = backend.query(task_id)
class uniqc.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. uniqc.yml 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.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.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.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

uniqc.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.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’, or ‘ibm’).

  • 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.list_backends()[source]#

List all available backends and their 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()
>>> for name, info in backends.items():
...     print(f"{name}: {'available' if info['available'] else 'unavailable'}")
uniqc.backend.register_backend(name, backend_class, allow_override=False)[source]#

Register a custom backend class.

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