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

Parameters:

platform (str)
kwargs (dict[str, Any] | None)
extra (Any)

Return type:

BackendOptions

platform: Platform¶

shots: int = 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.

Return type:: dict[str, Any]

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.

Parameters:: platform (str)
Return type:: BackendOptions

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 (str) – Platform name — one of "originq", "quafu", "ibm", "dummy".
kwargs (dict[str, Any] | None) – Optional keyword arguments dict. Merged with any additional keyword arguments passed via **extra.
extra (Any)

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 (BackendOptions | UnifiedOptions | dict[str, Any] | None) – 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 (str) – 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.
platform (dataclasses.InitVar[Platform])
shots (int)

available_qubits: int = 16¶

available_topology: list[list[int]] | None = None¶

chip_characterization: Any = None¶

noise_model: Any = None¶

platform: dataclasses.InitVar[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.

Return type:: dict[str, Any]

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.
platform (dataclasses.InitVar[Platform])
shots (int)

auto_mapping: bool = True¶

chip_id: str | None = None¶

circuit_optimize: bool = True¶

platform: dataclasses.InitVar[Platform] = 'ibm'¶

task_name: str | None = 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.

Return type:: dict[str, Any]

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.
platform (dataclasses.InitVar[Platform])
shots (int)

auto_mapping: bool = False¶

backend_name: str = 'originq:WK_C180'¶

circuit_optimize: bool = True¶

measurement_amend: bool = False¶

platform: dataclasses.InitVar[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.

Return type:: dict[str, Any]

class uniqc.backend_adapter.task.options.QuafuOptions(platform=Platform.QUAFU, shots=1000, chip_id='ScQ-P18', auto_mapping=True, task_name=None, group_name=None, wait=False)[source]¶

Bases: BackendOptions

Options for Quafu (ScQ) backends.

Parameters:

chip_id (str) – Quafu chip identifier, e.g. "ScQ-P18". Default: "ScQ-P18".
auto_mapping (bool) – Enable automatic qubit mapping. Default: True.
task_name (str | None) – Optional task name for the server-side task list.
group_name (str | None) – Optional group name for batch tracking.
wait (bool) – Block until server acknowledges receipt. Default: False.
platform (dataclasses.InitVar[Platform])
shots (int)

auto_mapping: bool = True¶

chip_id: str = 'ScQ-P18'¶

group_name: str | None = None¶

platform: dataclasses.InitVar[Platform] = 'quafu'¶

task_name: str | None = 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.

Return type:: dict[str, Any]

wait: bool = False¶

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 / Quafu-SQC 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.
platform (dataclasses.InitVar[Platform])
shots (int)

chip_id: str = 'Baihua'¶

compile: bool = True¶

compiler: str | None = None¶

correct: bool | None = None¶

open_dd: str | None = None¶

platform: dataclasses.InitVar[Platform] = 'quark'¶

target_qubits: list[int] | None = None¶

task_name: str | None = 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.

Return type:: dict[str, Any]

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	Quafu	Quark	IBM
`optimize_level=0`	`circuit_optimize=False`	ignored (no knob)	`compile=False`	`circuit_optimize=False`
`optimize_level>=1`	`circuit_optimize=True`	`auto_mapping=True`	`compile=True`	`circuit_optimize=True`
`error_mitigation=True`	`measurement_amend=True`	warn / raise	`correct=True`	warn / raise
`auto_mapping=True`	`auto_mapping=True`	`auto_mapping=True`	warn / raise	`auto_mapping=True`
`backend_name`	`backend_name=...`	`chip_id=...`	`chip_id=...`	`chip_id=...`
`shots`	forwarded	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, Quafu’s group_name, 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: bool = True¶

backend_name: str | None = None¶

error_mitigation: bool = False¶

optimize_level: int = 1¶

shots: int = 1000¶

strict: bool = False¶

to_kwargs(platform)[source]¶

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

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

Parameters:: platform (str)
Return type:: dict[str, Any]

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

Parameters:: platform (str)
Return type:: BackendOptions