qat.experimental.system_data.materialisers.operations.defaults module

Default operation construction functions for standard superconducting-qubit gate sets.

This module provides functions that construct canonical OperationData instances for the standard single-qubit gate set (X_pi_2, X_pi, Z, X, U, measure) and multi-qubit gates (CNOT via ECR decomposition).

These factories are designed for use by materialiser plugins such as the PuRR materialiser, but are not tied to any specific source format.

Mode IDs

The following mode IDs are assumed to exist on the target qubit:

  • drive — main qubit drive channel, used for X pulses and virtual Z frame shifts.

  • measure — measurement pulse channel.

  • acquire — signal acquisition channel.

When constructing topology-aware two-qubit operations, the following coupling mode IDs are also expected:

  • <target>.cross_resonance — cross-resonance drive mode addressed on the coupled

    target qubit.

  • <control>.cross_resonance_cancellation — cancellation-tone mode on the control

    qubit.

Waveform and acquire-definition IDs

The following identifiers are assumed to match waveform and acquire definitions present in the mode’s calibration data, as built by the PuRR qubit materialiser:

  • x_pi_2 — half-pi X pulse.

  • x_pi — full-pi X pulse.

  • zx_pi_4 — ZX(π/4) cross-resonance pulse.

  • zx_neg_pi_4 — ZX(−π/4) cross-resonance pulse (phase-inverted).

  • measure — measurement pulse.

  • acquire — acquisition definition.

class DefaultOperationBuilder(qubit_id, coupled_qubit_ids=(), control_qubit_ids=(), has_x_pi=True, reset_methods=(), default_reset_method=None, ddrop_delay_ps=None)

Bases: AbstractOperationBuilder

Builds the default transmon gate-set operation set for a single qubit.

Each operation is a method that returns an OperationData instance. Subclasses can override individual methods to customise or replace specific operations without touching the rest of the set — no knowledge of operation IDs is required.

Topology parameters are supplied at construction time so all methods share consistent qubit context.

Usage — default set:

ops = DefaultOperationBuilder(
    qubit_id="q0",
    coupled_qubit_ids=("q1",),
    control_qubit_ids=("q2",),
    has_x_pi=True,
).build()

Usage — subclass override:

class CustomOperationBuilder(DefaultOperationBuilder):
    def make_z_operation(self) -> OperationData:
        return ...  # hardware-specific Z decomposition

ops = CustomOperationBuilder(qubit_id="q0").build()

Usage — data-level extension at the call site:

ops = DefaultOperationBuilder(qubit_id="q0").build(
    extra_operations=(my_custom_gate,)
)

Constructor parameters are inherited from AbstractOperationBuilder.

make_cnot_operation(target_qubit_id)

Return the CNOT gate targeting target_qubit_id.

Return type:

OperationData

make_delay_operation()

Return the delay operation (duration in picoseconds).

Return type:

OperationData

make_ecr_operation(target_qubit_id)

Return the ECR gate targeting target_qubit_id.

Return type:

OperationData

make_had_operation()

Return the Hadamard gate.

Return type:

OperationData

make_id_gate()

Return the identity gate.

Return type:

OperationData

make_initiate_operation()

Return the initiate operation.

Return type:

OperationData

make_measure_operation()

Return the measure operation.

Return type:

OperationData

make_private_single_qubit_operations()

Return private pulse primitives used by default gate decompositions.

Return type:

tuple[OperationData, ...]

make_reset_operation()

Return the reset operation.

Return type:

OperationData

make_rx_gate()

Return the Rx(θ) gate.

Return type:

OperationData

make_ry_gate()

Return the Ry(θ) gate.

Return type:

OperationData

make_rz_gate()

Return the Rz(θ) gate.

Return type:

OperationData

make_s_operation()

Return the S gate.

Return type:

OperationData

make_sdg_operation()

Return the Sdg gate.

Return type:

OperationData

make_sx_operation()

Return the SX (√X) gate.

Return type:

OperationData

make_sxdg_operation()

Return the SXdg (√X†) gate.

Return type:

OperationData

make_t_operation()

Return the T gate.

Return type:

OperationData

make_tdg_operation()

Return the Tdg gate.

Return type:

OperationData

make_two_qubit_operations()

Return topology-derived two-qubit operations for this qubit.

Includes control-side ZX/ECR/CNOT for coupled_qubit_ids and target-side cancellation operations for control_qubit_ids.

Return type:

tuple[OperationData, ...]

make_u1_gate()

Return the U1(λ) gate.

Return type:

OperationData

make_u2_gate()

Return the U2(φ,λ) gate.

Return type:

OperationData

make_u_gate()

Return the U(θ,φ,λ) gate.

Return type:

OperationData

make_x_gate()

Return the X (Pauli-X) fixed-angle alias gate: rx(π).

Return type:

OperationData

make_y_gate()

Return the Y (Pauli-Y) fixed-angle alias gate: ry(π).

Return type:

OperationData

make_z_operation()

Return the fixed-angle Z gate alias (rz(π)).

Return type:

OperationData

make_zx_neg_pi_4_cancellation_operation(control_qubit_id)

Return the ZX(−π/4) cancellation-tone primitive for control_qubit_id.

Return type:

OperationData

make_zx_operation(target_qubit_id)

Return the ZX(θ) gate targeting target_qubit_id.

Return type:

OperationData

make_zx_pi_4_cancellation_operation(control_qubit_id)

Return the ZX(π/4) cancellation-tone primitive for control_qubit_id.

Return type:

OperationData

make_ccnot_operation(target_qubit_id, second_control_id)

Return a CCNOT (Toffoli) gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for ccnot operations.

Parameters:

  • target_qubit_id (str) – Identifier of the target qubit.

  • second_control_id (str) – Identifier of the second control qubit.

Return type:

OperationData

make_cnot_operation(target_qubit_id)

Return a CNOT gate owned by the control qubit, targeting target_qubit_id.

Decomposes as:

ECR(ctrl, tgt) → X(ctrl) → rz(ctrl, −π/2) → rx(tgt, −π/2)

The ECR operation is referenced as ecr_{target_qubit_id} and must be defined as a separately-owned operation on the same control qubit.

Parameters:

target_qubit_id (str) – Identifier of the target qubit (e.g. "q1").

Return type:

OperationData

make_cswap_operation(target1_id, target2_id)

Return a CSWAP (Fredkin) gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for cswap operations.

Parameters:

  • target1_id (str) – Identifier of the first target qubit.

  • target2_id (str) – Identifier of the second target qubit.

Return type:

OperationData

make_cx_operation(target_qubit_id)

Return a CX (controlled-X) gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for cX operations.

Parameters:

target_qubit_id (str) – Identifier of the target qubit.

Return type:

OperationData

make_cy_operation(target_qubit_id)

Return a CY (controlled-Y) gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for cY operations.

Parameters:

target_qubit_id (str) – Identifier of the target qubit.

Return type:

OperationData

make_cz_operation(target_qubit_id)

Return a CZ (controlled-Z) gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for cZ operations.

Parameters:

target_qubit_id (str) – Identifier of the target qubit.

Return type:

OperationData

make_ddrop_reset_operation(operation_id='ddrop_reset', *, delay_ps=None)

Return a DDROP reset operation.

Fires a simultaneous pulse on the qubit-side reset mode and the resonator-side readout_reset mode. When delay_ps is provided, a delay step is appended to each mode after the pulse.

Parameters:

delay_ps (Optional[int]) – Post-pulse settling delay in picoseconds, sourced from the ddrop_reset calibration payload. Omit when no delay is calibrated.

Return type:

OperationData

make_default_operations(qubit_id, coupled_qubit_ids=(), control_qubit_ids=(), has_x_pi=True, reset_methods=(), default_reset_method=None, ddrop_delay_ps=None, extra_operations=())

Return the full default operation set for a qubit.

Parameters:

  • qubit_id (str) – Identifier of the qubit that will own these operations.

  • coupled_qubit_ids (tuple[str, ...]) – Identifiers of qubits this qubit drives as the control qubit (e.g. ("q1", "q2")). Generates ZX(±π/4), ECR, and CNOT for each.

  • control_qubit_ids (tuple[str, ...]) – Identifiers of qubits that drive this qubit (i.e. this qubit is the target). Generates ZX cancellation-tone primitives for each.

  • has_x_pi (bool) – Whether a calibrated X(π) pulse is available on the qubit. Controls inclusion of X_pi and the corresponding variants in parameterised rx and ry.

  • reset_methods (tuple[ResetData, ...]) – Supported reset strategies (top-level canonical metadata).

  • default_reset_method (Optional[str]) – Default reset method type selected from reset_methods.

  • ddrop_delay_ps (Optional[int]) – Post-pulse settling delay in picoseconds for DDROP reset, sourced from the ddrop_reset calibration payload. Omit when uncalibrated.

  • extra_operations (tuple[OperationData, ...]) – Additional or replacement operations applied after the full default set (including topology-derived multi-qubit operations) is assembled. Any operation whose id matches a default replaces it in-place (last-wins); new IDs are appended.

Return type:

tuple[OperationData, ...]

Returns:

Tuple of canonical OperationData instances.

make_delay_operation()

Return the delay operation.

Delays the drive mode by duration picoseconds. Corresponds to the QASM3 delay statement and the delay() builder method.

Duration is expressed in picoseconds as an integer, matching the canonical schema convention used by DelayOperationStepData.

Return type:

OperationData

Returns:

A delay operation with a single duration parameter forwarded to a DelayOperationStepData on the drive mode.

make_ecr_operation(target_qubit_id)

Return the ECR (echoed cross-resonance) gate targeting target_qubit_id.

Decomposes as:

ZX(π/4, ctrl→tgt) → X(ctrl, π) → ZX(−π/4, ctrl→tgt)
Parameters:

target_qubit_id (str) – Identifier of the target qubit (e.g. "q1").

Return type:

OperationData

make_had_operation()

Return the Hadamard gate.

Implemented as the sequence Z then ry(π/2), i.e. rz(π) followed by ry(π/2), matching InstructionBuilder.had().

Return type:

OperationData

make_id_gate()

Return the identity gate.

id in QASM2 qelib1.inc is a no-op. Represented as an unconditional variant with no operation steps.

Return type:

OperationData

make_initiate_operation()

Return the initiate operation.

For the default transmon gate set this is a no-op: the qubit is assumed to be in a known ground state before a circuit begins and requires no explicit initialisation pulse. Qubit types that do require active initialisation (e.g. spin qubits, cat qubits, or mid-circuit reset strategies) should override this with a concrete variant that drives the appropriate hardware sequence.

Return type:

OperationData

make_measure_operation()

Return the measure gate.

Sends a measurement pulse on the measure mode (using the measure waveform definition) and captures the qubit response on the acquire mode (using the acquire acquire definition).

Return type:

OperationData

make_passive_reset_operation(operation_id='passive_reset', *, duration_ps)

Return a passive reset operation.

Passive reset is represented as a delay on the drive mode, with a fixed duration in picoseconds sourced from the canonical reset metadata.

Return type:

OperationData

make_reset_operation(reset_methods=(), default_reset_method=None)

Return the public reset operation.

The reset method is selected from top-level reset metadata: default_reset_method identifies the method type, which is resolved against reset_methods and mapped to the method’s operation_name attribute.

Return type:

OperationData

make_rx_gate(has_x_pi=True)

Return the Rx(θ) gate with conditional hardware-native variants.

The canonical parameterized X-axis rotation. All named X-axis gates (X, SX, SXdg) are fixed-angle aliases of this operation.

Variant selection:

  • θ ≈ π/2 → X_pi_2 (always available; no direct_x_pi guard)

  • θ ≈ −π/2 → rz(−π) → X_pi_2 → rz(π)

    (always available; no direct_x_pi guard)

  • θ ≈ π, direct_x_pi capability present → X_pi (only when has_x_pi)

  • θ ≈ −π, direct_x_pi capability present → rz(−π) → X_pi → rz(π)

    (only when has_x_pi)

  • default → decompose via U gate

Default angle is π.

Parameters:

has_x_pi (bool) – Whether a calibrated X(π) pulse is available on the qubit. When False the two X_pi-referencing variants are omitted, leaving 3 variants.

Return type:

OperationData

make_ry_gate(has_x_pi=True)

Return the Ry(θ) gate with conditional hardware-native variants.

The canonical parameterized Y-axis rotation. The named gate Y is a fixed-angle alias of this operation.

Variant selection mirrors the QuantumInstructionBuilder.Y dispatch:

  • θ ≈ π/2 → rz(−π/2) → X_pi_2 → rz(π/2)

  • θ ≈ −π/2 → rz( π/2) → X_pi_2 → rz(−π/2)

  • θ ≈ π, direct_x_pi present → rz(−π/2) → X_pi → rz(π/2) (only when has_x_pi)

  • θ ≈ −π, direct_x_pi present → rz( π/2) → X_pi → rz(−π/2) (only when has_x_pi)

  • default → decompose via U(theta, phi=0, lambda=0)

Default angle is π.

Parameters:

has_x_pi (bool) – Whether a calibrated X(π) pulse is available on the qubit. When False the two X_pi-referencing variants are omitted, leaving 3 variants.

Return type:

OperationData

make_rz_gate(own_qubit_id=None, coupled_qubit_ids=())

Return the Rz(θ) virtual rotation gate.

The canonical parameterized Z-axis rotation. All named Z-axis gates (Z, S, Sdg, T, Tdg) are fixed-angle aliases of this operation.

Applies a virtual Rz rotation as a sequence of reference-frame phase shifts, mirroring QuantumInstructionBuilder._hw_Z():

  • drive mode on the owning qubit (always).

  • {target}.cross_resonance_cancellation mode on the owning qubit, for each coupled target qubit.

  • {own_qubit_id}.cross_resonance mode on each coupled target qubit (cross-qubit reference, only when own_qubit_id is provided).

No physical pulse is emitted; the runtime implements each step as a frame-offset update.

Parameters:

  • own_qubit_id (Optional[str]) – Identifier of the qubit that owns this operation. Required for generating the cross-qubit CR mode phase shifts.

  • coupled_qubit_ids (tuple[str, ...]) – Identifiers of target qubits this qubit drives as control.

Return type:

OperationData

make_s_operation()

Return the S gate: rz(π/2).

Return type:

OperationData

make_sdg_operation()

Return the Sdg gate: rz(−π/2).

Return type:

OperationData

make_swap_operation(target_qubit_id)

Return a SWAP gate placeholder.

Not yet implemented in QuantumInstructionBuilder. The builder raises NotImplementedError for swap operations.

Parameters:

target_qubit_id (str) – Identifier of the target qubit.

Return type:

OperationData

make_sx_operation()

Return the SX (√X) gate: rx(π/2).

Return type:

OperationData

make_sxdg_operation()

Return the SXdg (√X†) gate: rx(−π/2).

Return type:

OperationData

make_t_operation()

Return the T gate: rz(π/4).

Return type:

OperationData

make_tdg_operation()

Return the Tdg gate: rz(−π/4).

Return type:

OperationData

make_u1_gate()

Return the U1(λ) gate: rz(λ).

u1(λ) in QASM2 qelib1.inc is equivalent to U(0, 0, λ), which reduces to a pure Z rotation. Implemented by delegating directly to rz.

Return type:

OperationData

Returns:

A u1 operation that forwards lambda to rz as the θ argument.

make_u2_gate()

Return the U2(φ, λ) gate: U(π/2, φ, λ).

u2(φ, λ) in QASM2 qelib1.inc is equivalent to U(π/2, φ, λ).

Return type:

OperationData

Returns:

A u2 operation that delegates to U with a fixed theta=π/2.

make_u_gate()

Return the U(θ, φ, λ) gate.

Decomposition matches QuantumInstructionBuilder.U() and is expressed in terms of rz and X_pi_2 primitives.

Return type:

OperationData

make_x_gate()

Return the X (Pauli-X) gate: rx(π).

Return type:

OperationData

make_x_pi_2_operation()

Return the X(π/2) pulse primitive.

Applies a calibrated half-pi X pulse on the drive mode using the x_pi_2 waveform definition.

Return type:

OperationData

make_x_pi_operation()

Return the X(π) pulse primitive.

Applies a calibrated full-pi X pulse on the drive mode using the x_pi waveform definition.

Return type:

OperationData

make_y_gate()

Return the Y (Pauli-Y) gate: ry(π).

Return type:

OperationData

make_z_gate()

Return the Z (Pauli-Z) gate: rz(π).

Return type:

OperationData

make_zx_neg_pi_4_cancellation_operation(control_qubit_id)

Return the ZX(−π/4) cancellation-tone primitive (owned by the target qubit).

Parameters:

control_qubit_id (str) – Identifier of the driving control qubit (e.g. "q0").

Return type:

OperationData

make_zx_operation(target_qubit_id, own_qubit_id)

Return the ZX(θ) cross-resonance entangling gate owned by the control qubit.

Supports θ = π/4 and θ = −π/4, which are the only angles available in the QuantumInstructionBuilder. For any other angle the unconditional fallback variant contains an ErrorOperationStepData step that signals NotImplementedError at execution time.

Variants (in evaluation order):

  1. isclose(θ, π/4) — fires the zx_pi_4 CR pulse and references the matching cancellation tone on the target qubit.

  2. isclose(θ, −π/4) — fires the zx_neg_pi_4 CR pulse and references the matching cancellation tone on the target qubit.

  3. (unconditional fallback) — raises NotImplementedError; general ZX(θ) is not yet supported.

Parameters:

  • target_qubit_id (str) – Identifier of the target (driven) qubit (e.g. "q1").

  • own_qubit_id (str) – Identifier of the owning control qubit (e.g. "q0").

Return type:

OperationData

make_zx_pi_4_cancellation_operation(control_qubit_id)

Return the ZX(π/4) cancellation-tone primitive (owned by the target qubit).

Fires the zx_pi_4 waveform on the {control_qubit_id}.cross_resonance_cancellation mode to suppress leakage during the control qubit’s CR drive.

Parameters:

control_qubit_id (str) – Identifier of the driving control qubit (e.g. "q0").

Return type:

OperationData