qat.experimental.system_data.materialisers.builder module

Fluent builder for canonical system data.

Provides a chained with_* API that accepts primitive arguments and constructs the corresponding canonical schema objects internally. The final frozen CanonicalSystemData is assembled on build().

Example:

from qat.experimental.system_data.materialisers.builder import (
    CanonicalSystemDataBuilder,
)

canonical = (
    CanonicalSystemDataBuilder()
    .with_calibration_id("cal-001")
    .with_acquire_mode("integrator")
    .with_default_acquire_mode("integrator")
    .with_reset_method("passive")
    .with_default_reset_method("passive")
    .with_port("p0", sample_time=1000)
    .with_channel("ch0", port_id="p0", frequency=5_000_000_000)
    .with_qubit("q0", index=0)
    .with_metadata("source", "my-lab")
    .build()
)

To produce a payload for the materialisation boundary use CanonicalSystemDataBuilder.build_payload():

from qat.experimental.system_data.materialisers import boundary

result = boundary.materialise(
    source_payload=CanonicalSystemDataBuilder()
    .with_calibration_id("cal-001")
    .build_payload()
)

class CanonicalSystemDataBuilder

Bases: object

Fluent builder for CanonicalSystemData.

All with_* methods accept primitive arguments and build the corresponding canonical objects internally, applying sensible defaults for optional fields. Methods mutate the builder in place and return self, enabling a chained call style. The final frozen CanonicalSystemData is only constructed on build().

Example:

canonical = (
    CanonicalSystemDataBuilder()
    .with_calibration_id("cal-001")
    .with_acquire_mode("integrator")
    .with_default_acquire_mode("integrator")
    .with_reset_method("passive")
    .with_default_reset_method("passive")
    .with_port("p0", sample_time=1000)
    .with_channel("ch0", port_id="p0", frequency=5_000_000_000)
    .with_qubit("q0", index=0)
    .with_metadata("source", "my-lab")
    .build()
)

build()

Construct and return the CanonicalSystemData from accumulated state.

This method is non-destructive: the builder’s state is unchanged and build() may be called again, producing an equal instance. The constructed model is passed to validate() before being returned.

Return type:: CanonicalSystemData
Returns:: Frozen CanonicalSystemData reflecting all accumulated calls.

build_payload()

Build a source payload mirroring CanonicalSystemData’s field structure.

Produces a shallow dict mapping each CanonicalSystemData field name to its current value, plus the structural version key required by materialise_model().

Return type:: dict[str, Any]
Returns:: Dict with one key per CanonicalSystemData field plus the _version entry.

data_field = 'model'

versioning_key = '_version'

with_acquire_limit(acquire_limit)

Set the maximum allowed acquisitions per execution batch.

Parameters:: acquire_limit¶ (int) – Acquisition limit, or -1 for unlimited.
Return type:: CanonicalSystemDataBuilder
Returns:: This builder instance.

with_acquire_mode(type, *, attributes=())

Append a supported acquisition mode descriptor.

Parameters:

type¶ (str) – Acquisition mode type string, for example "integrator" or "scope".
attributes¶ (tuple[AttributeEntry, ...]) – Optional additional mode metadata entries.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_calibration_id(calibration_id)

Set the calibration identifier.

Parameters:: calibration_id¶ (str) – Calibration identifier string.
Return type:: CanonicalSystemDataBuilder
Returns:: This builder instance.

with_channel(id, port_id, frequency, *, oscillator_reference=None, scale=1 + 0j, imbalance=1.0, phase_offset=0.0)

Append a logical channel calibration.

Parameters:

id¶ (str) – Channel identifier.
port_id¶ (str) – Referenced physical port identifier.
frequency¶ (int) – Target channel frequency in Hz.
oscillator_reference¶ (Optional[str]) – Optional referenced oscillator identifier.
scale¶ (complex) – Complex scaling factor. Defaults to 1+0j.
imbalance¶ (float) – IQ gain imbalance factor. Defaults to 1.0.
phase_offset¶ (float) – IQ phase offset in radians. Defaults to 0.0.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_coupling(source_qubit_id, target_qubit_id, *, gate_fidelities=())

Append a directed coupling descriptor between two qubits.

Parameters:

source_qubit_id¶ (str) – Source qubit identifier.
target_qubit_id¶ (str) – Target qubit identifier.
gate_fidelities¶ (tuple[TwoQubitGateFidelityData, ...]) – Per-gate fidelity entries for this directed pair. Defaults to an empty tuple.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_default_acquire_mode(mode)

Set the default acquisition mode type.

Parameters:: mode¶ (str) – Acquisition mode type string. Should match an entry added via with_acquire_mode().
Return type:: CanonicalSystemDataBuilder
Returns:: This builder instance.

with_default_reset_method(method)

Set the default reset strategy type.

Parameters:: method¶ (str) – Reset strategy type string. Should match an entry added via with_reset_method().
Return type:: CanonicalSystemDataBuilder
Returns:: This builder instance.

with_external_resource(id, *, object_type=None, attributes=())

Append an external hardware resource descriptor.

Parameters:

id¶ (str) – Resource identifier.
object_type¶ (Optional[str]) – Optional descriptive label from the source system.
attributes¶ (tuple[AttributeEntry, ...]) – Additional unstructured metadata.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_metadata(key_or_entry, value=None)

Append a metadata entry.

Accepts either an AttributeEntry directly, or a (key, value) shorthand:

builder.with_metadata(AttributeEntry(key="k", value="v"))
# or equivalently:
builder.with_metadata("k", "v")

Parameters:

key_or_entry¶ (str | AttributeEntry) – An AttributeEntry or a metadata key string.
value¶ (Optional[Any]) – Metadata value, required when key_or_entry is a string.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

Raises:

TypeError – If key_or_entry is a string but no value is supplied, or if key_or_entry is an AttributeEntry but value is also supplied.

with_oscillator(id, frequency, *, external_resource_id=None)

Append an oscillator configuration.

Parameters:

id¶ (str) – Oscillator identifier.
frequency¶ (int) – Oscillator frequency in Hz.
external_resource_id¶ (Optional[str]) – Optional linked external resource identifier.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_port(id, sample_time, *, block_size=1, min_blocks=1, max_blocks=-1, acquire_allowed=False, native_waveform_shapes=(), external_resource_id=None)

Append a physical port descriptor.

Parameters:

id¶ (str) – Port identifier.
sample_time¶ (int) – Sample period in picoseconds.
block_size¶ (int) – Hardware block granularity in samples. Defaults to 1.
min_blocks¶ (int) – Minimum blocks required per operation. Defaults to 1.
max_blocks¶ (int) – Maximum blocks allowed per operation, or -1 for no maximum. Defaults to -1.
acquire_allowed¶ (bool) – Whether acquisition is permitted on this port. Defaults to False.
native_waveform_shapes¶ (tuple[str, ...]) – Natively supported waveform shape names.
external_resource_id¶ (Optional[str]) – Optional linked external resource identifier.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_qubit(id, index, *, modes=(), operations=(), readout_probability=None)

Append a qubit calibration record.

Parameters:

id¶ (str) – Qubit identifier.
index¶ (int) – Qubit index.
modes¶ (tuple[ModeData, ...]) – Modes supported by this qubit. Defaults to an empty tuple.
operations¶ (tuple[OperationData, ...]) – Operation definitions available on this qubit. Defaults to an empty tuple.
readout_probability¶ (Optional[ReadoutProbabilityData]) – Optional readout confusion probabilities.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

with_reset_method(type, *, attributes=())

Append a supported reset strategy descriptor.

Parameters:

type¶ (str) – Reset strategy type string, for example "passive" or "active".
attributes¶ (tuple[AttributeEntry, ...]) – Optional additional strategy metadata entries.

Return type:

CanonicalSystemDataBuilder

Returns:

This builder instance.

build_version_structure_hash()

Build a structural hash of CanonicalSystemData for version mismatch detection.

Recurses through all type hints on CanonicalSystemData and its children. Each field contributes a field_name[type_description] token; dataclass children are expanded in-place and generic wrappers are preserved around their recursed descriptions.

Return type:: str
Returns:: String hash of the joined field-type description string.