uniqc.backend_adapter.task.options module¶

Typed backend options for UnifiedQuantum task submission.

This module provides a typed, platform-agnostic interface for specifying backend-specific options when calling submit_task() and submit_batch(). The existing **kwargs interface remains fully supported; BackendOptions is an additive enhancement.

Example

Using the typed interface:

from uniqc.backend_adapter.task.options import OriginQOptions
from uniqc import submit_task

opts = OriginQOptions(backend_name="originq:WK_C180", circuit_optimize=True)
task_id = submit_task(circuit, "originq", shots=1000, options=opts)

Equivalent using the legacy interface:

task_id = submit_task(circuit, "originq", shots=1000,
                      backend_name="originq:WK_C180", circuit_optimize=True)

class uniqc.backend_adapter.task.options.BackendOptions(platform, shots=1000)[source]¶

Bases: object

Base class for platform-specific backend options.

Subclasses define the options that are relevant for a particular platform. The platform field identifies which backend these options target.

Parameters:

platform (uniqc.backend_adapter.backend_info.Platform) – The target platform.
shots (int) – Number of measurement shots (default: 1000).

classmethod from_kwargs(platform, kwargs=None, **extra)[source]¶

Construct the appropriate BackendOptions from a **kwargs dict.

This is a convenience alias for BackendOptionsFactory.from_kwargs().

platform¶

shots = 1000¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.BackendOptionsFactory[source]¶

Bases: object

Factory for constructing BackendOptions from various input forms.

Supports three input forms:

BackendOptions instance — returned unchanged.
**kwargs dict — converted to the appropriate platform subclass.
None — returns a default options object for the platform.

Example

>>> opts = BackendOptionsFactory.from_kwargs("originq", {"circuit_optimize": False})
>>> type(opts).__name__
'OriginQOptions'
>>> opts.to_kwargs()["circuit_optimize"]
False

classmethod create_default(platform)[source]¶: Return a default BackendOptions for the given platform.

classmethod from_kwargs(platform, kwargs=None, **extra)[source]¶

Construct the appropriate BackendOptions from a **kwargs dict.

Accepts both forms for backwards compatibility:

BackendOptionsFactory.from_kwargs("originq", {"shots": 100})
BackendOptionsFactory.from_kwargs("originq", shots=100)

Parameters:

platform – Platform name — one of "originq", "quark", "ibm", "dummy".
kwargs – Optional keyword arguments dict. Merged with any additional keyword arguments passed via **extra.

Returns:

The appropriate platform-specific subclass.

Return type:

BackendOptions

Raises:

BackendOptionsError – If the platform is unknown.

classmethod normalize_options(options, platform)[source]¶

Normalise mixed input to a validated BackendOptions instance.

This is the main integration point for submit_task().

Parameters:

options – Either a BackendOptions instance, a UnifiedOptions instance (translated to the platform’s specific options), a plain dict (treated as **kwargs), or None (returns platform defaults).
platform – Platform name.

Returns:

Validated options object.

Return type:

BackendOptions

Raises:

BackendOptionsError – If options is not a BackendOptions, UnifiedOptions, dict, or None.

class uniqc.backend_adapter.task.options.DummyOptions(platform=Platform.DUMMY, shots=1000, noise_model=None, chip_characterization=None, available_qubits=16, available_topology=None)[source]¶

Bases: BackendOptions

Options for the local dummy simulator.

Parameters:

noise_model (Any | None) – Optional noise model for noisy simulation. Supported keys: depol_1q, depol_2q, depol (fallback for both).
chip_characterization (ChipCharacterization | None) – Chip characterization data. When provided, the simulator derives realistic noise parameters from per-qubit and per-pair calibration data (T1/T2, gate fidelities, readout errors). Cannot be used together with noise_model (noise_model takes precedence).
available_qubits (int) – Number of qubits available in the dummy simulator. Default: 16.
available_topology (list[list[int]] | None) – Connectivity graph as list of [u, v] edge pairs. If None, all-to-all connectivity is assumed.

available_qubits = 16¶

available_topology = None¶

chip_characterization = None¶

noise_model = None¶

platform = 'dummy'¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.IBMOptions(platform=Platform.IBM, shots=1000, chip_id=None, auto_mapping=True, circuit_optimize=True, task_name=None)[source]¶

Bases: BackendOptions

Options for IBM Quantum backends.

Parameters:

chip_id (str | None) – IBM backend name (e.g. "ibm_kyoto"). Optional; if None the IBM adapter’s default backend is used.
auto_mapping (bool) – Enable automatic qubit mapping. Default: True.
circuit_optimize (bool) – Enable circuit optimisation. Default: True.
task_name (str | None) – Optional task name for server-side tracking.

auto_mapping = True¶

chip_id = None¶

circuit_optimize = True¶

platform = 'ibm'¶

task_name = None¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.LogicalQubitOptions(platform=Platform.LOGICALQUBIT, shots=1000, backend_name=None, initial_layout=None, readout_correction=False)[source]¶

Bases: BackendOptions

Options for LogicalQubit (逻辑比特) backends.

Parameters:

backend_name (str | None) – LogicalQubit backend name. None defers to the adapter / server-side default.
initial_layout (list[int] | None) – Optional initial qubit layout, passed through to the platform.
readout_correction (bool) – Enable readout error mitigation. Default: False.

backend_name = None¶

initial_layout = None¶

platform = 'logicalqubit'¶

readout_correction = False¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.OriginQOptions(platform=Platform.ORIGINQ, shots=1000, backend_name='originq:WK_C180', circuit_optimize=True, measurement_amend=False, auto_mapping=False)[source]¶

Bases: BackendOptions

Options for OriginQ Cloud backends.

Parameters:

backend_name (str) – Full OriginQ backend name, e.g. "originq:WK_C180". Default: "originq:WK_C180".
circuit_optimize (bool) – Enable circuit optimisation on the backend. Default: True.
measurement_amend (bool) – Enable measurement error mitigation. Default: False.
auto_mapping (bool) – Enable automatic qubit mapping. Default: False.

auto_mapping = False¶

backend_name = 'originq:WK_C180'¶

circuit_optimize = True¶

measurement_amend = False¶

platform = 'originq'¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.QuarkOptions(platform=Platform.QUARK, shots=1000, chip_id='Baihua', task_name=None, compile=True, compiler=None, correct=None, open_dd=None, target_qubits=None)[source]¶

Bases: BackendOptions

Options for QuarkStudio backends.

Parameters:

chip_id (str) – QuarkStudio chip name, e.g. "Baihua" or "Dongling".
task_name (str | None) – Optional server-side task name.
compile (bool) – Whether QuarkStudio should compile the OpenQASM2 circuit. Default: True.
compiler (str | None) – Optional compiler backend: "quarkcircuit", "qsteed", "qiskit", or None.
correct (bool | None) – Optional readout correction flag.
open_dd (str | None) – Optional dynamical decoupling mode such as "XY4" or "CPMG".
target_qubits (list[int] | None) – Optional target qubits passed in the QuarkStudio task options.

chip_id = 'Baihua'¶

compile = True¶

compiler = None¶

correct = None¶

open_dd = None¶

platform = 'quark'¶

target_qubits = None¶

task_name = None¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.TianyanOptions(platform=Platform.TIANYAN, shots=1000, machine_name='tianyan_sw', task_name=None)[source]¶

Bases: BackendOptions

Options for TianYan (天衍) backends.

Parameters:

machine_name (str) – TianYan machine name, e.g. "tianyan176" (hardware) or "tianyan_sw" (cloud simulator). Default: "tianyan_sw".
task_name (str | None) – Optional experiment name for server-side tracking.

machine_name = 'tianyan_sw'¶

platform = 'tianyan'¶

task_name = None¶

to_kwargs()[source]¶

Render the options as a **kwargs dict for submit_task().

Subclasses must implement this method to produce the kwargs shape expected by the underlying adapter.

class uniqc.backend_adapter.task.options.UnifiedOptions(optimize_level=1, error_mitigation=False, auto_mapping=True, shots=1000, backend_name=None, strict=False)[source]¶

Bases: object

Cross-platform task-submission options.

UnifiedOptions lets you write backend-agnostic submission code: pass the same instance to uniqc.submit_task() against any platform and uniqc translates the high-level intent (optimise, mitigate readout, auto-map qubits) into each platform’s specific BackendOptions payload.

Translation table — warn / raise indicates the option is not supported on that platform; the behaviour is governed by strict (default False → warnings.warn(); True → raise BackendOptionsError):

Unified option	OriginQ	Quark	IBM
`optimize_level=0`	`circuit_optimize=False`	`compile=False`	`circuit_optimize=False`
`optimize_level>=1`	`circuit_optimize=True`	`compile=True`	`circuit_optimize=True`
`error_mitigation=True`	`measurement_amend=True`	`correct=True`	warn / raise
`auto_mapping=True`	`auto_mapping=True`	warn / raise	`auto_mapping=True`
`backend_name`	`backend_name=...`	`chip_id=...`	`chip_id=...`
`shots`	forwarded	forwarded	forwarded

Per-platform BackendOptions instances remain a fully-supported “escape hatch” for platform-specific knobs that have no unified counterpart (Quark’s open_dd, IBM’s task_name etc.).

Parameters:

optimize_level (int) – Cross-platform optimisation strength. 0 disables compilation / optimisation on every platform that exposes such a knob. Any value >= 1 enables it. Higher integers are reserved for future use by platforms that distinguish multiple optimisation tiers; for now >= 1 is treated identically across platforms.
error_mitigation (bool) – Enable readout-error mitigation when the platform supports it.
auto_mapping (bool) – Enable automatic logical-to-physical qubit mapping.
shots (int) – Number of measurement shots. Forwarded verbatim.
backend_name (str | None) – Optional chip identifier. Translated to the platform’s native chip-selection key (backend_name on OriginQ, chip_id elsewhere). When None the platform’s default chip is used.
strict (bool) – When True, unsupported options raise BackendOptionsError. When False (default), they are emitted as UserWarning and silently dropped.

auto_mapping = True¶

backend_name = None¶

error_mitigation = False¶

optimize_level = 1¶

shots = 1000¶

strict = False¶

to_kwargs(platform)[source]¶

Render as a **kwargs dict for the given platform.

Convenience shortcut for self.to_platform_options(platform).to_kwargs().

to_platform_options(platform)[source]¶

Translate to the platform-specific BackendOptions subclass.

Unknown platforms raise BackendOptionsError. Unsupported options trigger warnings.warn() (or BackendOptionsError when strict=True).