qat.experimental.system_data.materialisers.echo.utils module

Factory helpers for building default echo QPU canonical system data.

These functions produce a fully populated CanonicalSystemData without requiring any external source payload or parse step.

Typical usage

Build a 4-qubit ring topology with all defaults:

from qat.experimental.system_data.materialisers.echo.utils import (
    build_default_echo_topology,
)

builder = build_default_echo_topology(qubit_count=4)
canonical = builder.build()

Override frequencies and connectivity:

builder = build_default_echo_topology(
    qubit_count=3,
    connectivity=[(0, 1), (1, 2)],
    calibration_id="lab-echo-001",
    drive_frequency_hz=5_200_000_000,
    readout_frequency_hz=7_500_000_000,
)
canonical = builder.build()

All parameters have useful defaults that reproduce a standard transmon-style echo QPU. A CanonicalSystemDataBuilder is returned — call build() to produce the frozen CanonicalSystemData. No boundary parse step is required.

Default hardware parameters

Drive frequency: 5.5 GHz (drive_frequency_hz)
Readout frequency: 8.5 GHz (readout_frequency_hz)
Sample time: 1 000 ps / 1 ns (sample_time_ps)
Acquire limit: unlimited / -1 (acquire_limit)
Acquire modes: integrator, scope (acquire_modes)
Default acquire mode: integrator (default_acquire_mode)
Reset methods: passive (reset_methods)
Default reset method: passive (default_reset_method)

build_default_echo_topology(qubit_count=4, connectivity=None, calibration_id='', drive_frequency_hz=5500000000, readout_frequency_hz=8500000000, sample_time_ps=1000, acquire_limit=-1, acquire_modes=None, default_acquire_mode='integrator', reset_methods=None, default_reset_method='passive')

Build a default echo QPU canonical system data instance.

Produces a fully populated CanonicalSystemData with a transmon-inspired signal path for each qubit and a configurable coupling topology. The result is returned directly — no boundary parse step is required.

Per-qubit signal path

For each qubit at index i:

Oscillators: lo_drive_q{i} (drive_frequency_hz), lo_readout_q{i} (readout_frequency_hz).
Ports: port_drive_q{i} (sample_time_ps), port_readout_q{i} (sample_time_ps, acquire-capable).
Channels: ch_drive_q{i}, ch_measure_q{i}, ch_acquire_q{i}.
Modes: drive_q{i}, measure_q{i}, acquire_q{i}.

Coupling topology

Each undirected edge in connectivity produces two directed QubitCouplingData entries (both directions). If connectivity is None, a ring topology is generated via generate_echo_ring_connectivity().

type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.qubit_count:: int
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.qubit_count:: Number of qubits to include in the topology.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.connectivity:: Optional[list[tuple[int, int]]]
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.connectivity:: Undirected coupling edges as (source_index, target_index) pairs. None generates a ring topology automatically.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.calibration_id:: str
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.calibration_id:: Calibration identifier embedded in the returned record.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.drive_frequency_hz:: int
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.drive_frequency_hz:: Drive channel frequency in Hz. Defaults to 5.5 GHz.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.readout_frequency_hz:: int
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.readout_frequency_hz:: Readout channel frequency in Hz. Defaults to 8.5 GHz.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.sample_time_ps:: int
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.sample_time_ps:: Port sample period in picoseconds. Defaults to 1 000 ps (1 ns).
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.acquire_limit:: int
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.acquire_limit:: Maximum acquisitions per execution batch; -1 is unlimited.
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.acquire_modes:: Optional[list[str]]
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.acquire_modes:: Supported acquisition mode type strings. Defaults to ["integrator", "scope"].
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.default_acquire_mode:: str
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.default_acquire_mode:: Default acquisition mode type. Defaults to "integrator".
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.reset_methods:: Optional[list[str]]
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.reset_methods:: Supported reset strategy type strings. Defaults to ["passive"].
type _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.default_reset_method:: str
param _sphinx_paramlinks_qat.experimental.system_data.materialisers.echo.utils.build_default_echo_topology.default_reset_method:: Default reset strategy type. Defaults to "passive".
rtype:: CanonicalSystemDataBuilder
returns:: CanonicalSystemDataBuilder populated with the echo QPU topology. Call build() to produce the frozen CanonicalSystemData.
raises ValueError:: If qubit_count is negative, or if any connectivity index is out of range for qubit_count.

generate_echo_ring_connectivity(qubit_count)

Return undirected ring connectivity edges for qubit_count qubits.

Parameters:: qubit_count¶ (int) – Number of qubits in the lattice.
Return type:: list[tuple[int, int]]
Returns:: List of undirected (source_index, target_index) pairs. Returns an empty list for qubit_count <= 1 and a single pair for qubit_count == 2.
Raises:: ValueError – If qubit_count is negative.