API reference¶

def acquire(
    self,
    bus: str,
    weights: IQWaveform | str,
    fields: Iterable[MeasurementField] = (MeasurementField.IQ,),
    *,
    name: str | None = None,
) -> MeasurementHandle:
    """Append an [`Acquire`][qprogram_qblox.Acquire] operation.

    The handle's name comes from the same per-bus counter core
    [`measure`][qprogram.QProgram.measure] draws on, so two acquisitions on ``q[0].readout`` produce
    ``q0/readout/m0`` and ``q0/readout/m1`` whether or not a core ``measure`` also runs on that
    qubit. A raw-string bus carries no coordinates to build that prefix from, so it falls back
    to the bare ``m0``, ``m1``, ... counter shared by every raw-string measurement.

    Args:
        bus (str): Readout bus to acquire on.
        weights (IQWaveform | str): Integration weights, either a concrete
            [`IQWaveform`][qprogram.waveforms.IQWaveform] or a string alias.
        fields (Iterable[MeasurementField]): Which measurement fields to produce, as an iterable
            of [`MeasurementField`][qprogram.MeasurementField] members. Default ``(MeasurementField.IQ,)``;
            `RAW` asks for the raw ADC trace.
        name (str | None): Explicit measurement name. Auto-allocated when omitted.

    Returns:
        The [`MeasurementHandle`][qprogram.MeasurementHandle] this acquisition writes to, for retrieving the
        result and for referencing the outcome in a conditional.

    Raises:
        ValidationError: If ``name`` is empty, is not a string, or is already used by another
            measurement in the program, if ``fields`` names a field that is not registered, or
            if ``bus`` is a [`BusRef`][qprogram.BusRef] from another schema than the one attached
            to the program.
    """
    return self._append_measurement(
        Acquire,
        bus=bus,
        weights=weights,
        fields=fields,
        name=name,
    )

def set_markers(self, bus: str, mask: str) -> None:
    """Append a [`SetMarkers`][qprogram_qblox.SetMarkers] operation.

    Args:
        bus (str): Bus whose marker outputs to drive.
        mask (str): Four characters of ``0`` and ``1``, one per marker line, e.g. ``"0001"``.

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

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

    Args:
        bus (str): Bus whose trigger outputs to arm.
        duration (int): Trigger-active duration in nanoseconds.
        outputs (list[int] | int | None): Trigger output indices to arm, one index or a list of
            them. ``None`` leaves the selection to the platform.
        position (str): Point in the operation at which the trigger fires, either ``"start"`` or
            ``"end"``. Default ``"start"``.

    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, outputs=outputs, position=position))

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

    Args:
        bus (str): Bus whose sequencer waits.
        duration (int): Timeout in nanoseconds, after which the sequencer stops waiting.
        port (int | None): Trigger input port to listen on. ``None`` leaves the choice to the
            platform.

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

def set_acquisition_threshold(self, bus: str, value: float | Expression) -> None:
    """Append a [`SetAcquisitionThreshold`][qprogram_qblox.SetAcquisitionThreshold] operation.

    Host-side-only: the platform realizes it as a slow-control parameter write at execution
    time, not as a sequencer instruction. A vendor namespace can expose operations whose effect
    is entirely off-sequencer, and the platform decides at execution time how to realize each
    one.

    Args:
        bus (str): Readout bus whose discrimination threshold to set.
        value (float | Expression): Threshold, in volts after integration. Accepts an
            [`Expression`][qprogram.Expression] so an enclosing loop can sweep it.

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

def set_acquisition_rotation(self, bus: str, angle: float | Expression) -> None:
    """Append a [`SetAcquisitionRotation`][qprogram_qblox.SetAcquisitionRotation] operation.

    The companion to `set_acquisition_threshold`: the integrated IQ point is rotated by
    ``angle`` before the comparison against the threshold, so the two populations separate along
    one axis. Host-side-only as well, a parameter write rather than a sequencer instruction.

    Args:
        bus (str): Readout bus whose acquisition rotation to set.
        angle (float | Expression): Rotation angle in radians, the unit convention of core
            [`set_phase`][qprogram.QProgram.set_phase]. Accepts an [`Expression`][qprogram.Expression] so an
            enclosing loop can sweep it, which is how it is normally calibrated.

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

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qblox.acquire`` plus the weights and requested-field tokens.

    ``waveform.iq`` is always required, since an acquisition integrates an IQ pair. String
    weights contribute ``waveform.alias``; concrete weights contribute the per-class token from
    [`qprogram.protocol.waveform_token`][] when their class is registered. The
    ``measure.fields.<name>`` tokens come from
    [`required_capabilities`][qprogram.operations.operation.MeasurementOperation.required_capabilities].
    """
    from qprogram.protocol import waveform_token  # ruff: ignore[import-outside-top-level]

    caps = super().required_capabilities() | {"vendor.qblox.acquire", "waveform.iq"}
    if isinstance(self.weights, str):
        caps.add("waveform.alias")
    else:
        tok = waveform_token(self.weights)
        if tok is not None:
            caps.add(tok)
    return caps

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qblox.set_markers``, the operation's identity token."""
    return {"vendor.qblox.set_markers"}

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qblox.set_trigger``, the operation's identity token."""
    return {"vendor.qblox.set_trigger"}

def required_capabilities(self) -> set[str]:
    """Return ``vendor.qblox.wait_trigger``, the operation's identity token."""
    return {"vendor.qblox.wait_trigger"}

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

    return {"vendor.qblox.set_acquisition_threshold"} | expression_tokens(self.value)

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

    return {"vendor.qblox.set_acquisition_rotation"} | expression_tokens(self.angle)