qat.experimental.system_data.canonical.schema module

Canonical dataclass schema for experimental quantum system data.

This module defines the immutable, schema-first representation used by the experimental system-data layer to describe calibration metadata, resources, signal paths, qubits, operations, and related top-level attributes.

class AcquireDefinitionData(*, id, delay=None, sync=None, width=None, weights=None)

Bases: object

Acquisition timing and weighting configuration for a mode or operation.

This models signal-capture settings. State-interpretation probabilities are modeled separately so capture and interpretation remain decoupled.

Variables:

  • id – Acquisition definition identifier.

  • delay – Acquisition start delay in picoseconds.

  • sync – Whether acquisition timing is coupled to the measurement window; if True, the acquire window is derived from the measurement pulse timing (after applying delay), and if False an independent acquire width is used.

  • width – Acquisition window width in picoseconds when sync is False.

  • weights – Optional integration weights as per-sample coefficients. Values are typically absent (None) or a tuple of float/complex samples.

delay: int | None
id: str
sync: bool | None
weights: tuple[complex | float, ...] | None
width: int | None
class AcquireModeData(*, type, attributes=())

Bases: object

Supported acquisition mode descriptor for hardware capabilities.

Hardware backends may expose different acquisition modes. This record captures one supported mode and optional metadata about its behavior.

Variables:

  • type – Acquisition mode type.

  • attributes – Additional mode metadata.

attributes: tuple[AttributeEntry, ...]
type: str
class AcquireOperationStepData(*, mode_id, acquire_definition)

Bases: object

Single acquisition step in an operation expansion.

A step links an operation to a mode and an acquisition definition to apply on that mode.

Variables:

  • mode_id – Referenced mode identifier.

  • acquire_definition – Acquisition definition identifier or inline definition.

acquire_definition: str | AcquireDefinitionData
mode_id: str
class AttributeEntry(*, key, value)

Bases: object

A generic key/value entry carried on canonical records.

This is an intentional extension point for legacy or target-specific details that are not promoted to typed top-level fields.

Note

A tuple of these is preferable to a dict of attributes to preserve immutability and ordering, and to allow for duplicate keys if necessary.

Variables:

  • key – Attribute key.

  • value – Attribute value.

key: str
value: Any
class CanonicalSystemData(*, calibration_id='', acquire_limit=-1, acquire_modes=(), default_acquire_mode=None, reset_methods=(), default_reset_method=None, oscillators=(), ports=(), channels=(), qubits=(), couplings=(), external_resources=(), metadata=())

Bases: object

Canonical system data used by the experimental stack.

Variables:

  • calibration_id – Calibration identifier.

  • acquire_limit – Maximum allowed acquisitions for a single execution batch.

  • acquire_modes – Supported acquisition mode descriptors for hardware capabilities.

  • default_acquire_mode – Optional default acquisition mode type selected from acquire_modes.

  • reset_methods – Supported reset-strategy descriptors for hardware capabilities.

  • default_reset_method – Optional default reset strategy type selected from reset_methods.

  • oscillators – Canonical oscillator configurations used as frequency references.

  • ports – Canonical physical port descriptors with ID-based references.

  • channels – Canonical logical channel calibrations bound to physical ports.

  • qubits – Canonical calibration records for device-level qubit abstractions.

  • couplings – Directional coupling metadata between qubit pairs.

  • external_resources – Canonical descriptors for external hardware resources.

  • metadata – Additional top-level system metadata entries.

acquire_limit: int
acquire_modes: tuple[AcquireModeData, ...]
calibration_id: str
channels: tuple[ChannelData, ...]
couplings: tuple[QubitCouplingData, ...]
default_acquire_mode: str | None
default_reset_method: str | None
external_resources: tuple[ExternalResourceData, ...]
metadata: tuple[AttributeEntry, ...]
oscillators: tuple[OscillatorData, ...]
ports: tuple[PortData, ...]
qubits: tuple[QubitData, ...]
reset_methods: tuple[ResetData, ...]
class ChannelData(*, id, port_id, frequency, oscillator_reference=None, scale=1 + 0j, imbalance=1.0, phase_offset=0.0)

Bases: object

Canonical logical channel calibration bound to a physical port.

Channel records represent the calibrated operating point used by waveform generation and execution layers.

Variables:

  • id – Channel identifier.

  • port_id – Referenced physical port identifier.

  • frequency – Target channel frequency in Hz.

  • oscillator_reference – Optional referenced oscillator identifier used as the frequency anchor for derived mixing calculations.

  • scale – Complex scaling factor.

  • imbalance – IQ gain imbalance factor.

  • phase_offset – IQ phase offset in radians.

frequency: int
id: str
imbalance: float
oscillator_reference: str | None
phase_offset: float
port_id: str
scale: complex
class DelayOperationStepData(*, mode_id, duration)

Bases: object

Single delay step in an operation expansion.

A step links an operation to a mode and a delay duration to apply on that mode.

Variables:

  • mode_id – Referenced mode identifier.

  • duration – Delay duration in picoseconds.

duration: int
mode_id: str
class ExternalResourceData(*, id, object_type=None, attributes=())

Bases: object

Canonical descriptor for an external hardware resource.

These resources are typically instruments, controllers, or other backend-facing entities that are referenced by signal-path objects. Attributes are intentionally unstructured as different backends may have widely varying resource data requirements.

Variables:

  • id – Resource identifier that remains consistent across references and calibration snapshots for the same underlying external device.

  • object_type – Optional descriptive label from the source system. E.g. in a Qblox-backed setup this might be values such as Cluster, ClusterModule, QCM-RF, QRM-RF, or LocalOscillator.

  • attributes – Additional unstructured metadata.

attributes: tuple[AttributeEntry, ...]
id: str
object_type: str | None
class LinearMapToRealMethodData(*, method='linear_map_complex_to_real', mean_z_map_args=(1 + 0j, 0j))

Bases: object

Threshold discriminator using a calibrated complex-to-real projection.

This canonical record mirrors the linear_map_complex_to_real method in the runtime model. Each complex IQ readout is projected with two complex coefficients a and b from mean_z_map_args using Re(a * IQ + b) and then thresholded by sign into integer keys 0 and 1.

Variables:

  • method – Discriminator identifying this post-processing method variant.

  • mean_z_map_args – Two complex coefficients used by the linear projection.

mean_z_map_args: tuple[complex, complex]
method: Literal['linear_map_complex_to_real']
class MaxLikelihoodDiscriminateParams(*, location, label=None)

Bases: object

IQ-plane centroid descriptor for a single integer discriminate key.

Each entry represents one measurement outcome in a maximum-likelihood classifier. The integer output value and disallowed behavior are encoded by the key in MaxLikelihoodMethodData.states:

  • Non-negative keys (>= 0) represent allowed states.

  • Negative keys (< 0) represent disallowed/background states.

Variables:

  • location – Complex IQ-plane centroid associated with this state.

  • label – Optional human-readable state label for display and diagnostics.

label: str | None
location: complex
class MaxLikelihoodMethodData(*, method='max_likelihood', states, noise_est=1.0, p_min=0.0, transform=None, offset=None)

Bases: object

Maximum-likelihood discriminator for IQ measurement results.

This canonical record mirrors the max_likelihood method in the runtime model. A shot is assigned to the state with highest normalised likelihood, computed from state centroids in states and the noise variance noise_est.

p_min enables outlier rejection: if the winning normalised likelihood is below the threshold, the shot is treated as background and should be discarded by post-selection.

transform and offset optionally describe an affine IQ pre-transform applied before likelihood evaluation.

Variables:

  • method – Discriminator identifying this post-processing method variant.

  • states – Entries mapping integer discriminate keys to state centroids.

  • noise_est – Global Gaussian noise variance used in likelihood evaluation.

  • p_min – Minimum normalised likelihood required for acceptance.

  • transform – Optional real (2, 2) affine IQ transform matrix.

  • offset – Optional real length-2 IQ offset vector.

method: Literal['max_likelihood']
noise_est: float
offset: tuple[float, float] | None
p_min: float
states: tuple[tuple[int, MaxLikelihoodDiscriminateParams], ...]
transform: tuple[tuple[float, float], tuple[float, float]] | None
class ModeData(*, id, channel_id, waveform_definitions=(), acquire_definitions=None, post_process_method=None, preselect_disallowed_states=None)

Bases: object

A named mode that packages data for a targeted transition or operation.

Modes typically represent a specific transition or operation at a lattice site, such as f01 drive, standard transmon readout, or cross resonance.

A mode binds that intent to a concrete channel (which may be shared by multiple modes) and stores the calibration context needed to generate instructions through that channel.

Modes are not restricted to single-transition behavior; they can also represent richer operations (for example Raman-style gates) while following the same principles: channel binding plus waveform and acquisition definitions for the intended action.

Variables:

  • id – Unique mode identifier.

  • channel_id – Referenced channel identifier used for mode signal delivery and/or acquisition.

  • waveform_definitions – Waveform definitions available in this mode (see WaveformData), for example pi/2 and pi pulses for an f01 mode.

  • acquire_definitions – Acquisition definitions available in this mode (see AcquireDefinitionData).

  • post_process_method – Optional canonical post-processing method.

  • preselect_disallowed_states – Integer state keys discarded during pre-selection.

acquire_definitions: tuple[AcquireDefinitionData, ...] | None
channel_id: str
id: str
post_process_method: LinearMapToRealMethodData | MaxLikelihoodMethodData | None
preselect_disallowed_states: frozenset[int] | None
waveform_definitions: tuple[WaveformData, ...]
class OperationData(*, id, operation_steps=())

Bases: object

Canonical operation definition composed of ordered steps.

Operations may represent native hardware primitives or composite virtual instructions expanded into nested steps.

Variables:

  • id – Operation identifier.

  • operation_steps – Ordered operation steps or nested operations.

id: str
operation_steps: tuple[PulseOperationStepData | AcquireOperationStepData | DelayOperationStepData | SyncOperationStepData | OperationData, ...]
class OscillatorData(*, id, frequency, external_resource_id=None)

Bases: object

Canonical oscillator configuration for a signal path.

An oscillator captures a reusable frequency reference that may be shared by one or more channels and optionally links to the external resource that implements it.

Variables:

  • id – Oscillator identifier.

  • frequency – Oscillator frequency in Hz.

  • external_resource_id – Optional linked external resource identifier.

external_resource_id: str | None
frequency: int
id: str
class PortData(*, id, sample_time, block_size=1, min_blocks=1, max_blocks=-1, acquire_allowed=False, external_resource_id=None)

Bases: object

Canonical physical port data with ID-based references.

A port models a physical input/output connection to one or more quantum devices. It captures acquisition capability and timing granularity constraints. block_size is the canonical replacement for the legacy samples_per_clock_cycle concept.

Variables:

  • id – Port identifier.

  • sample_time – Sample period in picoseconds.

  • block_size – Hardware block granularity in samples. Together with sample_time, this defines the timing granularity for the port.

  • min_blocks – Minimum number of blocks required for a valid operation on this port. This is a hardware constraint that may be used to validate operation definitions.

  • max_blocks – Maximum number of blocks allowed for a valid operation on this port. This is a hardware constraint that may be used to validate operation definitions, or -1 to indicate no maximum.

  • acquire_allowed – Whether acquisition is allowed on this port.

  • external_resource_id – Optional linked external resource identifier.

acquire_allowed: bool
block_size: int
external_resource_id: str | None
id: str
max_blocks: int
min_blocks: int
sample_time: int
class ProbabilityEntry(*, prepared_state, measured_state, probability)

Bases: object

A single probability entry for a given state preparation and measurement outcome.

Variables:

  • prepared_state – The state that was prepared.

  • measured_state – The state that was measured.

  • probability – The conditional probability of observing measured_state given that prepared_state was prepared.

measured_state: int
prepared_state: int
probability: float
class PulseOperationStepData(*, mode_id, waveform_definition)

Bases: object

Single step in an operation expansion.

A step links an operation to a mode and a pulse definition to apply on that mode.

Variables:

  • mode_id – Referenced mode identifier.

  • waveform_definition – Waveform definition identifier or inline definition.

mode_id: str
waveform_definition: str | WaveformData
class QubitCouplingData(*, source_qubit_id, target_qubit_id, gate_fidelities)

Bases: object

Directional coupling metadata between two qubits.

This is intentionally lightweight and stores only connectivity direction plus per-gate fidelity estimates.

Variables:

  • source_qubit_id – Source qubit identifier.

  • target_qubit_id – Target qubit identifier.

  • gate_fidelities – Two-qubit gate fidelity entries for this directed qubit pair.

gate_fidelities: tuple[TwoQubitGateFidelityData, ...]
source_qubit_id: str
target_qubit_id: str
class QubitData(*, id, index, modes=(), operations=(), readout_probability=None)

Bases: object

Canonical calibration data for a device-level qubit abstraction.

This qubit represents the implementation-level unit exposed by the system data. It may be realized by multiple underlying physical elements, but is treated as one qubit resource at higher abstraction layers. It is therefore distinct from both microscopic physical components and QEC logical qubits.

Variables:

  • id – Qubit identifier.

  • index – Qubit index.

  • modes – Modes supported by this qubit.

  • operations – Operation definitions available on this qubit.

  • readout_probability – Optional readout confusion probabilities.

id: str
index: int
modes: tuple[ModeData, ...]
operations: tuple[OperationData, ...]
readout_probability: ReadoutProbabilityData | None
class ReadoutProbabilityData(*, probability_entries)

Bases: object

Readout confusion probabilities stored as explicit state-pair entries.

The entries capture conditional probabilities p(measured|prepared) for a prepared and measured state pair, rather than requiring a fixed binary confusion-matrix layout.

Variables:

probability_entries – Probability entries for prepared/measured state pairs.

probability_entries: tuple[ProbabilityEntry, ...]
class ResetData(*, type, attributes=())

Bases: object

Supported reset-strategy descriptor for hardware capabilities.

Hardware backends may expose different reset strategies. This record captures one supported strategy and optional metadata about its behavior.

Variables:

  • type – Reset strategy type (for example passive).

  • attributes – Additional reset strategy metadata. (for example, a passive reset might include a duration attribute for the expected T1 decay time).

attributes: tuple[AttributeEntry, ...]
type: str
class SyncOperationStepData(*, mode_ids)

Bases: object

Single synchronization step in an operation expansion.

A step links an operation to a set of modes for synchronization.

Variables:

mode_ids – Referenced mode identifiers.

mode_ids: frozenset[str]
class TwoQubitGateFidelityData(*, gate, fidelity)

Bases: object

Two-qubit gate fidelity data for a qubit pair.

Variables:

  • gate – Two-qubit gate identifier.

  • fidelity – Fidelity of the two-qubit gate.

fidelity: float
gate: str
class WaveformData(*, id, shape=None, width=None, rise=None, amp=None, drag=None, phase=None, amp_setup=None)

Bases: object

Parameterized waveform definition used by operations and modes.

This captures reusable waveform parameters independently from where or when the pulse is applied.

Variables:

  • id – Waveform definition identifier.

  • shape – Named waveform shape.

  • width – Waveform width in picoseconds.

  • rise – Rise fraction or rise time in picoseconds, depending on shape semantics. Time values must be defined as integer picoseconds, while fractional values are defined as floats in the range [0.0, 1.0].

  • amp – Waveform amplitude.

  • drag – DRAG coefficient.

  • phase – Waveform phase in radians.

  • amp_setup – Optional setup/plateau amplitude.

amp: float | None
amp_setup: float | None
drag: float | None
id: str
phase: float | None
rise: int | float | None
shape: str | None
width: int | None