mqt.core.qdmi¶

QDMI sessions, devices, and jobs.

Submodules¶

mqt.core.qdmi.builtin_driver

Package Contents¶

One initialized QDMI driver session.

property devices: list[Device]¶: The devices visible to this authenticated session.

property device_ids: list[str]¶: The stable IDs of devices visible to this session.

get_device(device_id: str) → Device¶: Find a device by stable ID within this session.

open_device(device_id: str, *, driver_path: str | PathLike | None = None, token: str | None = None, auth_file: str | PathLike | None = None, auth_url: str | None = None, username: str | None = None, password: str | None = None, project_id: str | None = None, custom1: str | None = None, custom2: str | None = None, custom3: str | None = None, custom4: str | None = None, custom5: str | None = None) → Device¶: Open a client-visible device by stable ID in a fresh session.

device_ids() → list[str]¶: Return the stable IDs visible to a fresh QDMI driver session.

class Job¶

A job represents a submitted quantum program execution.

check() → Job¶: Returns the current status of the job.

wait(timeout: int = 0) → bool¶

Waits for the job to complete.

Parameters:: timeout – The maximum time to wait in seconds. If 0, waits indefinitely.
Returns:: True if the job completed within the timeout, False otherwise.

cancel() → None¶: Cancels the job.

get_shots(program_index: int = 0) → list[str]¶: Returns the raw shot results from the job.

get_counts(program_index: int = 0) → dict[str, int]¶: Returns the measurement counts from the job.

get_dense_statevector(program_index: int = 0) → list[complex]¶: Returns the dense statevector from the job (typically only available from simulator devices).

get_dense_probabilities(program_index: int = 0) → list[float]¶: Returns the dense probabilities from the job (typically only available from simulator devices).

get_sparse_statevector(program_index: int = 0) → dict[str, complex]¶: Returns the sparse statevector from the job (typically only available from simulator devices).

get_sparse_probabilities(program_index: int = 0) → dict[str, float]¶: Returns the sparse probabilities from the job (typically only available from simulator devices).

query_custom_property(custom_property: CustomProperty, value_type: type[str]) → str | None¶

query_custom_property(custom_property: CustomProperty, value_type: type[bool]) → bool | None

query_custom_property(custom_property: CustomProperty, value_type: type[int]) → int | None

query_custom_property(custom_property: CustomProperty, value_type: type[float]) → float | None

query_custom_property(custom_property: CustomProperty, value_type: type[bytes]) → bytes | None

Query an implementation-defined custom job property.

The caller must provide the type documented by the device implementation. Use bytes to retrieve the value without interpretation. Returns None when the custom slot is unsupported.

get_custom_result(custom_property: CustomProperty, value_type: type[str]) → str | None¶

get_custom_result(custom_property: CustomProperty, value_type: type[bool]) → bool | None

get_custom_result(custom_property: CustomProperty, value_type: type[int]) → int | None

get_custom_result(custom_property: CustomProperty, value_type: type[float]) → float | None

get_custom_result(custom_property: CustomProperty, value_type: type[bytes]) → bytes | None

Return an implementation-defined custom job result.

The caller must provide the type documented by the device implementation. Use bytes to retrieve the value without interpretation. Returns None when the custom slot is unsupported.

property id: str¶: The job ID.

property program_format: ProgramFormat¶: The format of the submitted program.

get_program(program_index: int = 0) → str¶
get_program(value_type: type[bytes], program_index: int = 0) → bytes: Return one submitted program’s exact bytes by input index.

property num_programs: int¶: The number of programs in input order.

get_program_status(program_index: int = 0) → Job | None¶: Return one program outcome, or None when unsupported.

get_results(result: int, program_index: int = 0) → bytes¶: Returns an indexed result as exact bytes.

property num_shots: int¶: The number of shots.

property queue_position: int | None¶: The number of jobs ahead in the queue, or None if unavailable or not applicable in the current state.

__eq__(arg: object, /) → bool¶

__ne__(arg: object, /) → bool¶

class Status¶

Bases: enum.Enum

Enumeration of job status.

CREATED = 0¶

SUBMITTED = 1¶

QUEUED = 2¶

RUNNING = 3¶

DONE = 4¶

CANCELED = 5¶

FAILED = 6¶

class ProgramFormat¶

Bases: enum.Enum

Enumeration of program formats.

QASM2 = 0¶

QASM3 = 1¶

QIR_BASE_STRING = 2¶

QIR_BASE_MODULE = 3¶

QIR_ADAPTIVE_STRING = 4¶

QIR_ADAPTIVE_MODULE = 5¶

QPY = 7¶

IQM_JSON = 8¶

CUSTOM1 = 999999995¶

CUSTOM2 = 999999996¶

CUSTOM3 = 999999997¶

CUSTOM4 = 999999998¶

CUSTOM5 = 999999999¶

is_binary_program_format(program_format: ProgramFormat) → bool¶

Returns whether a program format carries a binary payload.

QIR_BASE_MODULE, QIR_ADAPTIVE_MODULE, and QPY hold bitcode or another serialized object. Such a payload may contain a null byte and is not text, so the device must receive it as exact bytes. Pass bytes to Device.submit_job() for these formats and str for the others.

Parameters:: program_format – The program format to classify.
Returns:: True if the format requires exact-byte submission.

class CustomProperty¶

Bases: enum.Enum

An implementation-defined custom property or result slot.

CUSTOM1 = 1¶

CUSTOM2 = 2¶

CUSTOM3 = 3¶

CUSTOM4 = 4¶

CUSTOM5 = 5¶

class Device¶

A device represents a quantum device with its properties and capabilities.

class Status¶

Bases: enum.Enum

Enumeration of device status.

OFFLINE = 0¶

IDLE = 1¶

BUSY = 2¶

ERROR = 3¶

MAINTENANCE = 4¶

CALIBRATION = 5¶

name() → str¶: Returns the name of the device.

property id: str¶: The stable client-visible device ID.

version() → str¶: Returns the version of the device.

status() → Device¶: Returns the current status of the device.

library_version() → str¶: Returns the version of the library used to define the device.

qubits_num() → int¶: Returns the number of qubits available on the device.

sites() → list[Device]¶: Returns the list of all sites (zone and regular sites) available on the device.

regular_sites() → list[Device]¶: Returns the list of regular sites (without zone sites) available on the device.

zones() → list[Device]¶: Returns the list of zone sites (without regular sites) available on the device.

operations() → list[Device]¶: Returns the list of operations supported by the device.

coupling_map() → list[tuple[Device, Device]] | None¶: Returns the coupling map of the device as a list of site pairs.

queue_length() → int | None¶: Returns the current queue length, or None if unavailable.

length_unit() → str | None¶: Returns the unit of length used by the device.

length_scale_factor() → float | None¶: Returns the scale factor for length used by the device.

duration_unit() → str | None¶: Returns the unit of duration used by the device.

duration_scale_factor() → float | None¶: Returns the scale factor for duration used by the device.

min_atom_distance() → int | None¶: Returns the minimum atom distance on the device.

supported_program_formats() → list[ProgramFormat]¶: Returns the list of program formats supported by the device.

child_devices() → list[Device]¶: Returns the direct child devices managed by this device.

query_custom_operations(custom_property: CustomProperty) → list[Device] | None¶

Query a custom device property that contains operation handles.

Returns normal Device.Operation objects, or None when the custom slot is unsupported. A supported empty list is returned as an empty list.

query_custom_property(custom_property: CustomProperty, value_type: type[str]) → str | None¶

query_custom_property(custom_property: CustomProperty, value_type: type[bool]) → bool | None

query_custom_property(custom_property: CustomProperty, value_type: type[int]) → int | None

query_custom_property(custom_property: CustomProperty, value_type: type[float]) → float | None

query_custom_property(custom_property: CustomProperty, value_type: type[bytes]) → bytes | None

Query an implementation-defined custom device property.

The caller must provide the type documented by the device implementation. Use bytes to retrieve the value without interpretation. Returns None when the custom slot is unsupported.

submit_job(program: str | bytes | Sequence[str] | Sequence[bytes], program_format: ProgramFormat, num_shots: int | None = None, *, custom1: str | bool | float | bytes | None = None, custom2: str | bool | float | bytes | None = None, custom3: str | bool | float | bytes | None = None, custom4: str | bool | float | bytes | None = None, custom5: str | bool | float | bytes | None = None) → Job¶: Submit one program or an ordered list with common parameters.

try_submit_job(program: str | bytes | Sequence[str] | Sequence[bytes], program_format: ProgramFormat, num_shots: int | None = None, *, custom1: str | bool | float | bytes | None = None, custom2: str | bool | float | bytes | None = None, custom3: str | bool | float | bytes | None = None, custom4: str | bool | float | bytes | None = None, custom5: str | bool | float | bytes | None = None) → Job | None¶: Return no job only when the device rejects the program before submission.

retrieve_job_by_id(job_id: str) → Job¶: Retrieves an existing job by its device-provided ID.

__eq__(arg: object, /) → bool¶

__ne__(arg: object, /) → bool¶

class Site¶

A site represents a potential qubit location on a quantum device.

index() → int¶: Returns the index of the site.

t1() → int | None¶: Returns the T1 coherence time of the site.

t2() → int | None¶: Returns the T2 coherence time of the site.

name() → str | None¶: Returns the name of the site.

x_coordinate() → int | None¶: Returns the x coordinate of the site.

y_coordinate() → int | None¶: Returns the y coordinate of the site.

z_coordinate() → int | None¶: Returns the z coordinate of the site.

is_zone() → bool¶: Returns whether the site is a zone.

x_extent() → int | None¶: Returns the x extent of the site.

y_extent() → int | None¶: Returns the y extent of the site.

z_extent() → int | None¶: Returns the z extent of the site.

module_index() → int | None¶: Returns the index of the module the site belongs to.

submodule_index() → int | None¶: Returns the index of the submodule the site belongs to.

query_custom_property(custom_property: CustomProperty, value_type: type[str]) → str | None¶

query_custom_property(custom_property: CustomProperty, value_type: type[bool]) → bool | None

query_custom_property(custom_property: CustomProperty, value_type: type[int]) → int | None

query_custom_property(custom_property: CustomProperty, value_type: type[float]) → float | None

query_custom_property(custom_property: CustomProperty, value_type: type[bytes]) → bytes | None

Query an implementation-defined custom site property.

The caller must provide the type documented by the device implementation. Use bytes to retrieve the value without interpretation. Returns None when the custom slot is unsupported.

__eq__(arg: object, /) → bool¶

__ne__(arg: object, /) → bool¶

class Operation¶

An operation represents a quantum operation that can be performed on a quantum device.

name(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → str¶: Returns the name of the operation.

qubits_num(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None¶: Returns the number of qubits the operation acts on.

parameters_num(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int¶: Returns the number of parameters the operation has.

duration(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None¶: Returns the duration of the operation.

fidelity(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → float | None¶: Returns the fidelity of the operation.

interaction_radius(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None¶: Returns the interaction radius of the operation.

blocking_radius(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None¶: Returns the blocking radius of the operation.

idling_fidelity(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → float | None¶: Returns the idling fidelity of the operation.

is_zoned() → bool¶: Returns whether the operation is zoned.

sites() → list[Device] | None¶: Returns the list of sites the operation can be performed on.

site_pairs() → list[tuple[Device, Device]] | None¶: Returns the list of site pairs the local 2-qubit operation can be performed on.

mean_shuttling_speed(sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None¶: Returns the mean shuttling speed of the operation.

query_custom_property(custom_property: CustomProperty, value_type: type[str], sites: Sequence[Device] = ..., params: Sequence[float] = ...) → str | None¶

query_custom_property(custom_property: CustomProperty, value_type: type[bool], sites: Sequence[Device] = ..., params: Sequence[float] = ...) → bool | None

query_custom_property(custom_property: CustomProperty, value_type: type[int], sites: Sequence[Device] = ..., params: Sequence[float] = ...) → int | None

query_custom_property(custom_property: CustomProperty, value_type: type[float], sites: Sequence[Device] = ..., params: Sequence[float] = ...) → float | None

query_custom_property(custom_property: CustomProperty, value_type: type[bytes], sites: Sequence[Device] = ..., params: Sequence[float] = ...) → bytes | None

Query an implementation-defined custom operation property.

The caller must provide the type documented by the device implementation. Use bytes to retrieve the value without interpretation. Returns None when the custom slot is unsupported.

__eq__(arg: object, /) → bool¶

__ne__(arg: object, /) → bool¶