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, Quark, 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)

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.

is_available()

Always available if C++ simulator is installed.

platform = 'dummy'

class uniqc.backend_adapter.backend.IBMBackend(name=None, config=None, cache_dir=None)

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

check_proxy()

Check if the configured proxy is available.

Returns:

True if proxy is configured and reachable, False otherwise.

Note

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

get_proxy_config()

Get the current proxy configuration.

Returns:

Dict with ‘http’ and/or ‘https’ proxy URLs, or None if not configured.

platform = 'ibm'

test_connectivity()

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.LogicalQubitBackend(name=None, config=None, cache_dir=None)

Bases: QuantumBackend

Backend for the LogicalQubit cloud platform (逻辑比特).

This backend connects to the LogicalQubit cloud service via lqcloud.

platform = 'logicalqubit'

class uniqc.backend_adapter.backend.OriginQBackend(name=None, config=None, cache_dir=None)

Bases: QuantumBackend

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

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

platform = 'originq'

class uniqc.backend_adapter.backend.QuantumBackend(name=None, config=None, cache_dir=None)

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

• adapter – The underlying quantum adapter instance.

• config – Backend-specific configuration dictionary.

property adapter

Get or create the underlying adapter instance.

Returns:

The quantum adapter for this backend.

Raises:

RuntimeError – If the adapter cannot be initialized.

clear_cache()

Clear the cache for this backend instance.

get_circuit_adapter()

Get the circuit adapter for translating circuits.

Returns:

The quantum adapter that handles circuit translation.

classmethod get_instance(name=None, config=None, use_cache=True, cache_dir=None)

Get or create a backend instance (factory method).

Parameters:

• name – Optional name for the instance.

• config – Optional configuration dictionary.

• use_cache – Whether to use/load cache. Defaults to True.

• cache_dir – Optional custom cache directory.

Returns:

A backend instance.

is_available()

Check if this backend is available.

Returns:

True if the backend is properly configured and ready to use.

classmethod list_available()

Check if this backend type is available.

Returns:

True if the backend can be instantiated and is configured.

classmethod load_from_cache(cache_dir=None)

Load a backend instance from cache.

Parameters:

cache_dir – Optional custom cache directory path.

Returns:

Loaded backend instance or None if cache doesn’t exist or is invalid.

platform = ''

query(task_id)

Query a task’s status and result.

Parameters:

task_id – 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)

Query multiple tasks’ status and merge results.

Parameters:

task_ids – List of task identifiers.

Returns:

‘status’, ‘result’ (list of results).

Return type:

Dict with keys

save_to_cache()

Save this backend instance configuration to cache.

submit(circuit, *, shots=1000, **kwargs)

Submit a circuit to the backend.

Parameters:

• circuit – Provider-native circuit object or OriginIR string.

• shots – Number of measurement shots.

• **kwargs – Additional provider-specific parameters.

Returns:

Task ID assigned by the backend.

submit_batch(circuits, *, shots=1000, **kwargs)

Submit multiple circuits as a batch.

Parameters:

• circuits – List of provider-native circuit objects or OriginIR strings.

• shots – Number of measurement shots.

• **kwargs – Additional provider-specific parameters.

Returns:

Task ID(s) assigned by the backend.

translate_circuit(originir)

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

Parameters:

originir – Circuit in OriginIR format.

Returns:

Provider-specific circuit object.

class uniqc.backend_adapter.backend.QuarkBackend(name=None, config=None, cache_dir=None)

Bases: QuantumBackend

Backend for the QuarkStudio quantum cloud (BAQIS ScQ).

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

platform = 'quark'

class uniqc.backend_adapter.backend.TianyanBackend(name=None, config=None, cache_dir=None)

Bases: QuantumBackend

Backend for the TianYan quantum cloud platform (天衍).

This backend connects to the TianYan cloud service via cqlib for executing quantum circuits on TianYan quantum computers and simulators.

platform = 'tianyan'

uniqc.backend_adapter.backend.clear_backend_cache(cache_dir=None)

Clear all backend caches.

Parameters:

cache_dir – Optional custom cache directory. Uses default if None.

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

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 – The platform name (‘originq’, ‘quark’, ‘ibm’, or ‘dummy’).

• config – Optional configuration dictionary for the backend.

• use_cache – Whether to use cache. Defaults to True.

• cache_dir – 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.

Example

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

uniqc.backend_adapter.backend.list_backends()

Return a flat list of registered backend names.

Returns:

Sorted list of backend name strings, e.g. ['ibm', 'originq', 'quark'].

Example

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

uniqc.backend_adapter.backend.list_backends_by_platform()

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'},
    'quark': {'available': False, 'platform': 'quark'},
    ...
}

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)

Register a custom backend class.

Parameters:

• name – The platform name to register.

• backend_class – The backend class to register.

• allow_override – Whether to allow overriding existing registrations.

Raises:

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

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)

Unregister a backend.

Parameters:

name – The platform name to unregister.

Raises:

ValueError – If the backend is not registered.