API reference¶

Bases: QdacMixin, QProgram

QProgram pre-combined with QdacMixin.

Behaves exactly like qprogram.QProgram, with editor autocomplete for qp.qdac.*.

Mixin that adds a typed .qdac property to a QProgram subclass.

Combine it with qprogram.QProgram through multiple inheritance, listing one mixin per vendor. qprogram_qdac.QProgram is that combination already made.

qdac: QdacNamespace

Bases: VendorNamespace

The QDAC vendor namespace, reached as program.qdac.<operation>().

Available on every QProgram instance once qprogram_qdac is imported. Each method type-checks its arguments through the signature, builds the matching operation, and appends it to whichever block the program has open.

wait_trigger(bus: str, port: int) -> None

51
52
53
54
55
56
57
58
59
60
61
62

def wait_trigger(self, bus: str, port: int) -> None:
    """Append a [`WaitTrigger`][qprogram_qdac.WaitTrigger] operation.

    Args:
        bus (str): QDAC channel whose trigger input the sequencer listens on.
        port (int): Trigger input port number on the chassis.

    Raises:
        ValidationError: If ``bus`` is a [`BusRef`][qprogram.BusRef] from another schema than the
            one attached to the program.
    """
    self._append(WaitTrigger(bus=bus, port=port))

set_trigger(
    bus: str,
    duration: int,
    position: TriggerPosition = "start",
    outputs: Iterable[int] = (),
) -> None

64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

def set_trigger(
    self,
    bus: str,
    duration: int,
    position: TriggerPosition = "start",
    outputs: Iterable[int] = (),
) -> None:
    """Append a [`SetTrigger`][qprogram_qdac.SetTrigger] operation.

    Args:
        bus (str): QDAC channel whose trigger outputs are being configured.
        duration (int): Trigger-active duration in nanoseconds.
        position (TriggerPosition): Sequence event at which the triggers fire, one of
            ``"start"``, ``"step"``, ``"end"``, ``"end_step"``. Default ``"start"``.
        outputs (Iterable[int]): Trigger output indices to arm. Any iterable of ints will do:
            ``set``, ``list``, ``tuple``, generator. Empty by default, which the
            ``qdac.empty-trigger-outputs`` predicate rejects at validation time.

    Raises:
        ValidationError: If ``bus`` is a [`BusRef`][qprogram.BusRef] from another schema than the
            one attached to the program.
    """
    self._append(SetTrigger(bus=bus, duration=duration, position=position, outputs=outputs))

set_offset(bus: str, offset: float | Expression) -> None

 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100

def set_offset(self, bus: str, offset: float | Expression) -> None:
    """Append a [`SetOffset`][qprogram_qdac.SetOffset] operation.

    Args:
        bus (str): QDAC channel whose DC offset is being set.
        offset (float | Expression): Target offset in volts. Accepts a literal or any
            [`Expression`][qprogram.Expression], a loop-bound [`Variable`][qprogram.Variable] included.

    Raises:
        ValidationError: If ``bus`` is a [`BusRef`][qprogram.BusRef] from another schema than the
            one attached to the program.
    """
    self._append(SetOffset(bus=bus, offset=offset))

play(
    bus: str,
    waveform: Waveform,
    dwell: int = 1,
    delay: int = 0,
    repetitions: int = 1,
    stepped: bool = False,
) -> None

102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

def play(  # ruff: ignore[too-many-arguments]  bus, envelope and the engine's four timing controls
    self,
    bus: str,
    waveform: Waveform,
    dwell: int = 1,
    delay: int = 0,
    repetitions: int = 1,
    stepped: bool = False,
) -> None:
    """Append a [`Play`][qprogram_qdac.Play] operation.

    Args:
        bus (str): QDAC channel that emits the waveform.
        waveform (Waveform): Single-channel [`Waveform`][qprogram.waveforms.Waveform] to emit. A
            ``str`` alias is accepted here too, to be resolved later by
            [`with_waveforms`][qprogram.QProgram.with_waveforms].
        dwell (int): Per-sample dwell time in nanoseconds. Default ``1``.
        delay (int): Delay before the first sample, in nanoseconds. Default ``0``.
        repetitions (int): How many times the envelope is emitted. Default ``1``.
        stepped (bool): ``True`` for discrete-step output, ``False`` for continuous
            interpolated output. Default ``False``.

    Raises:
        ValidationError: If ``bus`` is a [`BusRef`][qprogram.BusRef] from another schema than the
            one attached to the program.
    """
    self._append(
        Play(
            bus=bus,
            waveform=waveform,
            dwell=dwell,
            delay=delay,
            repetitions=repetitions,
            stepped=stepped,
        ),
    )

Bases: Operation

A halt on a QDAC channel until an external trigger arrives on one input port.

This is how a QDAC sequence lines up with hardware on another instrument, a qblox sequencer's set_trigger for instance. The QDAC sequencer stops until the trigger fires, and emits no waveform while it waits.

Parameters:

• bus (str) –

  QDAC channel whose trigger input the sequencer listens on.

• port (int) –

  Trigger input port number on the chassis, typically 1-based.

84
85
86

def __init__(self, bus: str, port: int) -> None:
    self.bus = bus
    self.port = port

required_capabilities() -> set[str]

88
89
90

def required_capabilities(self) -> set[str]:
    """Return the single ``vendor.qdac.wait_trigger`` token."""
    return {"vendor.qdac.wait_trigger"}

Bases: Operation

An arming of one or more QDAC trigger outputs at a chosen sequence position.

The QDAC chassis carries an internal trigger bus with several output lines. This operation arms a subset of them to fire for duration nanoseconds at a sequence event: sequence start, every step, sequence end, or every step's end.

Parameters:

• bus (str) –

  QDAC channel whose trigger outputs are being configured.

• duration (int) –

  Trigger-active duration in nanoseconds.

• position (TriggerPosition, default: 'start' ) –

  Sequence event at which the triggers fire, one of "start", "step", "end", "end_step". Default "start".

• outputs (Iterable[int] | str, default: () ) –

  Trigger output indices to arm. Any iterable of ints, or a comma-separated string of them. Empty by default, which the qdac.empty-trigger-outputs predicate rejects at validation time.

Attributes:

• outputs (tuple[int, ...]) –

  The argument as stored, sorted and deduplicated on the way in, so {2, 1} and [1, 2, 1] produce equal operations.

Raises:

• TypeError –

  If outputs is not iterable, or holds an element of a type int() will not take.

• ValueError –

  If outputs is a string whose comma-separated fields are not integers.

119
120
121
122
123
124
125
126
127
128
129

def __init__(
    self,
    bus: str,
    duration: int,
    position: TriggerPosition = "start",
    outputs: Iterable[int] | str = (),
) -> None:
    self.bus = bus
    self.duration = duration
    self.position: TriggerPosition = position
    self.outputs: tuple[int, ...] = _normalize_outputs(outputs)

required_capabilities() -> set[str]

131
132
133

def required_capabilities(self) -> set[str]:
    """Return the single ``vendor.qdac.set_trigger`` token."""
    return {"vendor.qdac.set_trigger"}

Bases: Operation

A static DC offset on a QDAC channel.

The channel holds offset volts until another operation changes it.

Parameters:

• bus (str) –

  QDAC channel whose DC offset is being set.

• offset (float | Expression) –

  Target offset in volts. Accepts a literal or any Expression, a loop-bound Variable included. A swept offset is re-uploaded once per iteration, which is what the qprogram_qdac.profiles constraint on the enclosing loop expresses.

149
150
151

def __init__(self, bus: str, offset: float | Expression) -> None:
    self.bus = bus
    self.offset = offset

required_capabilities() -> set[str]

153
154
155
156
157

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qdac.set_offset`` plus the tokens contributed by the ``offset`` expression."""
    from qprogram.protocol import expression_tokens  # ruff: ignore[import-outside-top-level]

    return {"vendor.qdac.set_offset"} | expression_tokens(self.offset)

Bases: Operation

An envelope emitted from a QDAC channel's waveform engine.

The channel comes from bus, so the operation routes to that bus's capability slot like every other QDAC operation. The rest of the arguments are the waveform-engine program: the envelope and its timing.

Parameters:

• bus (str) –

  QDAC channel that emits the waveform.

• waveform (Waveform) –

  Single-channel Waveform whose envelope is uploaded to the waveform engine. A str alias is accepted here too, to be resolved later by with_waveforms.

• dwell (int, default: 1 ) –

  Per-sample dwell time in nanoseconds, which sets the emission rate. Default 1.

• delay (int, default: 0 ) –

  Delay in nanoseconds between sequence start and the first sample. Default 0.

• repetitions (int, default: 1 ) –

  How many times the engine emits the envelope in total, the first emission included. Default 1.

• stepped (bool, default: False ) –

  True to step through the samples discretely, re-arming the DAC for each one, False for continuous interpolated output. Default False.

184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

def __init__(  # ruff: ignore[too-many-arguments]  bus, envelope and the engine's four timing controls
    self,
    bus: str,
    waveform: Waveform,
    dwell: int = 1,
    delay: int = 0,
    repetitions: int = 1,
    stepped: bool = False,
) -> None:
    self.bus = bus
    self.waveform = waveform
    self.dwell = dwell
    self.delay = delay
    self.repetitions = repetitions
    self.stepped = stepped

required_capabilities() -> set[str]

200
201
202
203
204
205
206
207
208
209
210
211
212
213

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qdac.play`` plus the tokens describing the waveform.

    ``waveform.single`` is always required, since the engine drives one channel. A registered
    waveform class contributes its per-class token from [`qprogram.protocol.waveform_token`][]
    on top, ``waveform.ramp`` for a [`Ramp`][qprogram.waveforms.Ramp] for instance.
    """
    from qprogram.protocol import waveform_token  # ruff: ignore[import-outside-top-level]

    caps = {"vendor.qdac.play", "waveform.single"}
    tok = waveform_token(self.waveform)
    if tok is not None:
        caps.add(tok)
    return caps