API reference¶

def variable(
    self,
    id: str,  # ruff: ignore[builtin-argument-shadowing]
    *,
    label: str | None = None,
    units: str | None = None,
    description: str | None = None,
) -> Variable:
    """Declare a new [`Variable`][qprogram.Variable] on this program.

    Args:
        id (str): Short identifier matching ``[A-Za-z_][A-Za-z0-9_]*``. Doubles as the ``.qp``
            identifier and must be unique within the program.
        label (str | None): Human-readable name for plots and results.
        units (str | None): Unit string (e.g. ``"Hz"``, ``"ns"``).
        description (str | None): Longer free-form description.

    Returns:
        The new [`Variable`][qprogram.Variable].

    Raises:
        ValidationError: If ``id`` already exists on this program.
    """
    if any(v.id == id for v in self._variables):
        msg = f"Variable {id!r} is already declared on this QProgram"
        raise ValidationError(msg)
    var = Variable(id, label=label, units=units, description=description)
    self._variables.append(var)
    return var

def measurement_handles(self) -> list[MeasurementHandle]:
    """Return the canonical [`MeasurementHandle`][qprogram.MeasurementHandle] for every measurement in the AST.

    Walks the body in declaration order and returns ``op.handle`` for each
    `MeasurementOperation`. The returned handles are the *same Python instances* the AST
    stores — writing per-measurement values via ``handle._set_value(...)`` is immediately visible
    to every [`MeasurementRef`][qprogram.MeasurementRef], whether the program was built in Python or loaded from a
    ``.qp`` file.

    Returns:
        One handle per measurement, in declaration order.
    """
    return [op.handle for op in _walk_measurement_ops(self._body)]

@classmethod
def register_vendor(cls, name: str, namespace_cls: type[VendorNamespace]) -> None:
    """Register a [`VendorNamespace`][qprogram.VendorNamespace] subclass under ``name``.

    After registration, ``program.<name>`` returns the namespace on any [`QProgram`][qprogram.QProgram] instance.

    Re-registering the *same* namespace class under the same name is a no-op (import-time
    side-effect modules may run twice); registering a different class under a taken name is
    an error — silently replacing another vendor's namespace would be a supply-chain hazard.

    Args:
        name (str): Vendor identifier (also used as the dot-prefix in ``.qp`` operation names).
            Must not be a reserved keyword, the ``"core"`` sentinel, or the name of any
            [`QProgram`][qprogram.QProgram] attribute (which would make the namespace unreachable — vendor
            lookup happens in ``__getattr__``, after normal attribute resolution).
        namespace_cls (type[VendorNamespace]): The [`VendorNamespace`][qprogram.VendorNamespace] subclass
            to instantiate lazily.

    Raises:
        ValueError: If ``name`` is reserved, shadows a ``QProgram`` attribute, or is already
            registered to a different namespace class.
    """
    existing = cls._vendor_registry.get(name)
    if existing is namespace_cls:
        # idempotent re-registration
        return
    if is_reserved_vendor(name):
        msg = (
            f"vendor name {name!r} is reserved (see qprogram.RESERVED_KEYWORDS plus the "
            f"'core' sentinel); pick a different namespace for this vendor extension"
        )
        raise ValueError(msg)
    # ``hasattr`` covers methods and properties; the frozenset covers the public *instance*
    # attributes assigned in ``__init__`` (invisible on the class but they shadow vendor
    # dispatch on every instance, since ``__getattr__`` only runs after normal lookup fails).
    if hasattr(cls, name) or name in _PUBLIC_INSTANCE_ATTRS:
        msg = (
            f"vendor name {name!r} collides with a QProgram attribute; the namespace would "
            f"be unreachable because normal attribute lookup wins over vendor dispatch"
        )
        raise ValueError(msg)
    if existing is not None:
        msg = (
            f"vendor name {name!r} is already registered to "
            f"{existing.__module__}.{existing.__qualname__}; refusing to replace it"
        )
        raise ValueError(msg)
    cls._vendor_registry[name] = namespace_cls

def play(self, bus: str, waveform: Waveform | IQWaveform | str) -> None:
    """Append a [`Play`][qprogram.operations.Play] op — play a waveform on a bus.

    Args:
        bus (str): Bus to play on.
        waveform (Waveform | IQWaveform | str): Concrete waveform, or a string alias resolved
            later by `with_waveforms`.

    Raises:
        ValidationError: If ``bus`` comes from another schema, or a concrete waveform's channel
            count does not match the bus's (an IQ pulse on a single-channel bus, or vice versa).
    """
    self._validate_bus(bus)
    _validate_waveform_channel(bus, waveform)
    self._append_to_active(Play(bus=bus, waveform=waveform))

def measure(
    self,
    bus: str,
    waveform: IQWaveform | str,
    weights: IQWaveform | str,
    *,
    name: str | None = None,
    fields: Iterable[MeasurementField] = (MeasurementField.IQ,),
) -> MeasurementHandle:
    """Play a readout pulse, acquire the result, and return a stable handle.

    Args:
        bus (str): Readout bus (must have ``acquires=True``).
        waveform (IQWaveform | str): Readout pulse — concrete
            [`IQWaveform`][qprogram.waveforms.IQWaveform] or a string alias.
        weights (IQWaveform | str): Integration weights — same shape options as ``waveform``.
        name (str | None): Explicit handle name. When omitted, an auto-name is allocated using
            the convention described on `_allocate_measurement_name`.
        fields (Iterable[MeasurementField], optional): Which measurement fields to produce — an
            iterable of `MeasurementField` members (registered field-name
            strings are also accepted, which is how vendors extend the set). Default
            ``(MeasurementField.IQ,)``; `STATE` requests
            classification, `RAW` the raw ADC trace. Order and
            duplicates don't matter — the stored tuple is canonical. An unknown field name
            raises [`ValidationError`][qprogram.ValidationError] here, at the call site.

    Returns:
        The [`MeasurementHandle`][qprogram.MeasurementHandle] identifying this measurement; pass it to
        ``result.get(...)``.

    Raises:
        ValidationError: If ``bus`` has no ADC, comes from another schema, a waveform's channel
            count does not match the bus's, ``name`` collides with another measurement, or
            ``fields`` is a bare string, is not iterable, requests nothing, or names something
            other than a registered field.
    """
    self._validate_bus(bus)
    _validate_acquires(bus)
    _validate_waveform_channel(bus, waveform)
    _validate_waveform_channel(bus, weights)
    allocated = self._allocate_measurement_name(bus, requested=name)
    handle = MeasurementHandle(allocated)
    handle._auto_named = name is None
    self._append_to_active(
        Measure(bus=bus, waveform=waveform, weights=weights, handle=handle, fields=fields),
    )
    return handle

def wait(self, bus: str, duration: int | Expression) -> None:
    """Append a [`Wait`][qprogram.operations.Wait] — idle on ``bus`` for ``duration`` ns.

    Args:
        bus (str): Bus to idle on.
        duration (int | Expression): Wait duration in nanoseconds. Accepts an
            [`Expression`][qprogram.Expression] for sweeps.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(Wait(bus=bus, duration=duration))

def sync(self, buses: list[str] | None = None) -> None:
    """Append a [`Sync`][qprogram.operations.Sync] — synchronize buses to a common time reference.

    Args:
        buses (list[str] | None): Buses to sync, or ``None`` to sync every bus currently active
            in the program.

    Raises:
        ValidationError: If ``buses`` is an empty list — ambiguous between "sync nothing"
            and "sync everything"; pass ``None`` for the sync-all form. Also if a listed bus
            comes from another schema.
    """
    # The user-facing keyword is ``buses`` for readability; the AST attribute is ``targets``
    # (see `Sync`).
    if buses is not None and len(buses) == 0:
        msg = "sync([]) is ambiguous; pass None (or no argument) to sync all buses"
        raise ValidationError(msg)
    if buses:
        for b in buses:
            self._validate_bus(b)
    self._append_to_active(Sync(targets=buses))

def set_frequency(self, bus: str, frequency: float | Expression) -> None:
    """Append a [`SetFrequency`][qprogram.operations.SetFrequency] — retune the NCO on ``bus``.

    Args:
        bus (str): Bus whose oscillator to retune.
        frequency (float | Expression): New frequency in Hz. Accepts an
            [`Expression`][qprogram.Expression] for sweeps.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(SetFrequency(bus=bus, frequency=frequency))

def set_phase(self, bus: str, phase: float | Expression) -> None:
    """Append a [`SetPhase`][qprogram.operations.SetPhase] — set the NCO phase on ``bus``.

    Args:
        bus (str): Bus whose oscillator phase to set.
        phase (float | Expression): Phase in radians. Accepts an
            [`Expression`][qprogram.Expression] for sweeps.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(SetPhase(bus=bus, phase=phase))

def reset_phase(self, bus: str) -> None:
    """Append a [`ResetPhase`][qprogram.operations.ResetPhase] — reset the NCO phase on ``bus`` to zero.

    Args:
        bus (str): Bus whose oscillator phase to reset.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(ResetPhase(bus=bus))

def set_gain(self, bus: str, gain: float | Expression) -> None:
    """Append a [`SetGain`][qprogram.operations.SetGain] — set the output gain on ``bus``.

    Args:
        bus (str): Bus whose output gain to set.
        gain (float | Expression): New gain. Accepts an [`Expression`][qprogram.Expression] for
            sweeps.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(SetGain(bus=bus, gain=gain))

def set_offset(
    self,
    bus: str,
    offset_path0: float | Expression,
    offset_path1: float | Expression | None = None,
) -> None:
    """Append a [`SetOffset`][qprogram.operations.SetOffset] — set DC offset on one or both paths of ``bus``.

    Args:
        bus (str): Bus whose DC offset to set.
        offset_path0 (float | Expression): Offset on path 0 (the only path for single-channel
            buses, I for IQ buses).
        offset_path1 (float | Expression | None): Offset on path 1 (Q for IQ buses). ``None``
            leaves that path's offset unchanged.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(SetOffset(bus=bus, offset_path0=offset_path0, offset_path1=offset_path1))

def set_parameter(
    self,
    bus: str,
    parameter: str,
    value: float | Expression,
) -> None:
    """Append a [`SetParameter`][qprogram.operations.SetParameter] — write a bus-scoped parameter.

    A parameter write is platform configuration rather than a real-time instruction, so
    platforms expose it host-side only.

    Args:
        bus (str): The bus whose parameter is written.
        parameter (str): Name of the parameter to write.
        value (float | Expression): New value. Accepts an [`Expression`][qprogram.Expression] for
            sweeps.

    Raises:
        ValidationError: If ``bus`` comes from another schema.
    """
    self._validate_bus(bus)
    self._append_to_active(SetParameter(bus=bus, parameter=parameter, value=value))

def get_parameter(self, bus: str, parameter: str) -> Variable:
    """Append a [`GetParameter`][qprogram.operations.GetParameter] and return the freshly-declared variable.

    Derives a unique variable id from ``f"{bus}_{parameter}"``, replacing non-word characters
    with underscores and appending a numeric suffix on collision; the original
    ``bus.parameter`` form is kept on the variable's `label` for traceability.

    Args:
        bus (str): The bus whose parameter is read.
        parameter (str): Name of the parameter to read.

    Returns:
        The [`Variable`][qprogram.Variable] the runtime populates with the read value.

    Raises:
        ValidationError: If ``bus`` comes from another schema, or the derived id is not a valid
            [`Variable`][qprogram.Variable] id — which is what a bus or parameter name carrying letters or
            digits outside ASCII produces.
    """
    self._validate_bus(bus)
    base = _sanitize_id(f"{bus}_{parameter}")
    existing = {v.id for v in self._variables}
    var_id = base
    n = 2
    while var_id in existing:
        var_id = f"{base}_{n}"
        n += 1
    var = self.variable(var_id, label=f"{bus}.{parameter}")
    self._append_to_active(GetParameter(variable=var, bus=bus, parameter=parameter))
    return var

def sweep(self, variable: Variable, source: SweepSource | _Unset = _UNSET) -> _SweepBuilder | _LoopContext:
    """Open a [`Sweep`][qprogram.blocks.Sweep] binding ``variable`` to a source's values.

    The DSL's only loop. What varies between a linear ramp, an explicit table, a log-spaced set
    and a composed pattern is the *source*, not the block — and there are two equal-billing ways
    to say which source.

    Pick the values fluently, which is the shorter spelling and needs no source class in scope::

        with program.sweep(freq).from_range(4e9, 6e9, 1e6):
            ...
        with program.sweep(amp).from_linspace(0.0, 1.0, num=101):
            ...
        with program.sweep(det).from_logspace(1e6, 1e9, num=50):
            ...
        with program.sweep(phi).from_values(calibrated_phases):
            ...
        with program.sweep(phi).from_file("phases.npy"):
            ...
        with program.sweep(phi).from_values(base).rotate(by=1).repeat(3):
            ...

    Or pass the source object, which is what you want when you are *computing* the source rather
    than writing it out — and the form that reaches combinator nestings the fluent
    `rotate` / `repeat` shortcuts don't::

        with program.sweep(freq, qp.Range(4e9, 6e9, 1e6)):
            ...
        with program.sweep(phi, qp.Concat(qp.Rotate(base, by=i) for i in range(4))):
            ...
        with program.sweep(freq, source):  # held in a variable, from a scan spec, ...
            ...

    Both build the identical [`Sweep`][qprogram.blocks.Sweep] node and serialize to the identical
    ``.qp`` line. Every registered source has a fluent builder, vendor sources included — see
    `_SweepBuilder`.

    Use ``|`` on the returned context manager to compose several sweeps into a
    [`Parallel`][qprogram.blocks.Parallel] block that advances them in lockstep.

    Args:
        variable (Variable): The [`Variable`][qprogram.Variable] rebound each iteration.
        source (SweepSource, optional): A [`SweepSource`][qprogram.SweepSource]. A bare 1-D
            sequence is accepted as shorthand for [`Values`][qprogram.Values]. Omit it to
            get a `_SweepBuilder` and pick the values with a ``from_*`` method instead.

    Returns:
        A context manager opening the sweep block, or — when ``source`` is omitted — the
        `_SweepBuilder` that produces one.

    Raises:
        ValidationError: If ``source`` is given but is neither a sweep source nor a 1-D sequence
            of values.
    """
    if isinstance(source, _Unset):
        return _SweepBuilder(self, variable)
    return _LoopContext(self, Sweep(variable=variable, source=source))

def average(self, shots: int) -> _AverageContext:
    """Open an averaging block that repeats its body ``shots`` times and averages the results.

    Args:
        shots (int): How many times to repeat the body.

    Returns:
        The context manager that opens the [`Average`][qprogram.blocks.Average] block.
    """
    return _AverageContext(self, shots)

def block(self) -> _BlockContext:
    """Open a generic grouping block — a container that carries no semantics of its own.

    Returns:
        The context manager that opens the [`Block`][qprogram.blocks.Block].
    """
    return _BlockContext(self)

def if_(self, condition: Expression) -> _IfContext:
    """Open an ``if`` arm gated on a measurement-state predicate.

    Build chains with sequential ``with`` blocks::

        with program.if_(m.state == 0):
            program.play(q[0].drive, "id_pulse")
        with program.elif_(m.state == 1):
            program.play(q[0].drive, "pi_pulse")
        with program.else_():
            pass

    The producing measurement **must** request state classification (``fields`` must include
    `STATE`); the validator emits ``missing-classification``
    otherwise.

    Args:
        condition (Expression): A [`Comparison`][qprogram.Comparison] between a
            [`MeasurementRef`][qprogram.MeasurementRef] (from ``handle.state``) and an ``int`` literal.
            That is the only accepted shape.

    Returns:
        The context manager that opens the conditional's first arm.

    Raises:
        ValidationError: If ``condition`` is anything other than a comparison of a
            measurement-state reference against an ``int`` literal.
    """
    self._validate_conditional_condition(condition, where="if_")
    return _IfContext(self, condition)

def elif_(self, condition: Expression) -> _ElifContext:
    """Extend the open ``if_`` chain with another arm.

    Must appear immediately after the matching ``if_()`` / ``elif_()`` at the same nesting level;
    any other append in between closes the chain. Condition shape is the same as `if_`.

    Args:
        condition (Expression): The arm's condition, in the shape `if_` documents.

    Returns:
        The context manager that opens the new arm.

    Raises:
        ValidationError: If ``condition`` has the wrong shape, no conditional chain is open at
            this nesting level, or the chain already has an ``else_()`` arm.
    """
    self._validate_conditional_condition(condition, where="elif_")
    return _ElifContext(self, condition)

def else_(self) -> _ElseContext:
    """Close the open ``if_`` chain with an unconditional arm.

    Must appear immediately after the matching ``if_()`` / ``elif_()`` at the same nesting level.
    At most one ``else_()`` per chain.

    Returns:
        The context manager that opens the ``else`` body.

    Raises:
        ValidationError: If no conditional chain is open at this nesting level, or the chain
            already has an ``else_()`` arm.
    """
    return _ElseContext(self)

def call(self, fragment: Fragment, *args: object, **kwargs: object) -> None:
    """Instantiate a [`Fragment`][qprogram.Fragment] at the current position.

    Appends a first-class [`Call`][qprogram.operations.Call] node — the fragment definition and
    the call site both survive serialization and round-trip through ``.qp``. Use
    `expand` to lower every call into the substituted fragment body.

    Arguments bind to the fragment's parameters with the Python calling convention (positional
    in declaration order, then keywords). Accepted values: numbers, expressions/variables,
    buses (strings or [`BusRef`][qprogram.BusRef]), and waveforms.

    The fragment (and, transitively, any fragment it calls) is registered on this program so
    the ``.qp`` writer can emit its definition.

    Args:
        fragment (Fragment): The fragment to call.
        *args (object): Positional arguments, bound in parameter declaration order.
        **kwargs (object): Keyword arguments, bound by parameter name.

    Raises:
        ValidationError: On a non-Fragment argument, a binding error (missing/extra/duplicate
            parameter, unsupported value type), a name clash with a different fragment already
            used by this program, a schema mismatch, or a call cycle.
    """
    from qprogram.fragments import Fragment, bind_arguments  # ruff: ignore[import-outside-top-level]
    from qprogram.operations.call import Call  # ruff: ignore[import-outside-top-level]

    if not isinstance(fragment, Fragment):
        msg = f"call() expects a Fragment, got {type(fragment).__name__}"
        raise ValidationError(msg)
    if fragment is self:
        msg = f"fragment {fragment.name!r} cannot call itself"
        raise ValidationError(msg)
    bound = bind_arguments(fragment, args, kwargs)
    for value in bound.values():
        if isinstance(value, BusRef):
            self._validate_bus(value)
    self._reconcile_fragment_schema(fragment)
    self._register_fragment(fragment, _stack=())
    self._append_to_active(Call(fragment=fragment, arguments=bound))

def expand(self) -> QProgram:
    """Return a deep copy with every fragment [`Call`][qprogram.operations.Call] inlined.

    The canonical lowering from the composed form to a fragment-free program: each call site is
    replaced by a plain [`Block`][qprogram.blocks.Block] containing the fragment body with parameters substituted
    by the bound arguments. Fragment-local variables are hygienically renamed onto this program
    (``{fragment}_{id}``, numeric suffix on collision); colliding measurement names gain a
    ``_2`` / ``_3`` suffix (the shared handle is renamed, keeping ``handle.state`` conditionals
    consistent). Nested calls expand recursively; expansion is deterministic, so expanding twice
    yields structurally equal programs.

    A program with no calls is deep-copied and returned unchanged in structure.

    Returns:
        A new, fragment-free [`QProgram`][qprogram.QProgram]; the original is untouched. Its fragment
        registry and its ``.qp`` source map are both empty either way, because expansion
        restructures the tree the recorded paths address.

    Raises:
        ValidationError: On a fragment call cycle or a binding used in an incompatible
            position (e.g. a waveform bound to a parameter used inside arithmetic).
    """
    from qprogram.fragments import expand_program  # ruff: ignore[import-outside-top-level]

    return expand_program(self)

def rebind(
    self,
    *,
    schema: BusSchema | None = None,
    elements: Mapping[tuple[str, int | tuple[int, ...]], tuple[str, int | tuple[int, ...]]] | None = None,
    naming: BusNaming | None = None,
    strings: Mapping[str, str] | None = None,
    allow_unported_strings: bool = False,
) -> QProgram:
    """Return a copy of this program with its bus references re-resolved structurally.

    Rather than rewriting bus *strings*, ``rebind`` re-resolves every schema-backed
    [`BusRef`][qprogram.BusRef] through a schema factory, so the result stays a typed ``BusRef``
    (serializing as a ``q[1].drive`` path, not a quoted string) and can re-index a qubit, move to a
    different element, swap naming conventions, or move onto another chip's schema — all checked
    against the schema (an absent bus kind raises ``AttributeError``).

    Auto-allocated measurement names embed the bus (``q0/readout/m0``); ``rebind`` re-derives them for
    the rebound buses while leaving user-supplied names untouched (see
    [`MeasurementHandle`][qprogram.MeasurementHandle]). Fragment calls are expanded first.

    Args:
        schema (BusSchema | None): Target schema. Defaults to the program's current schema
            (re-index within one chip).
        elements (Mapping[tuple[str, int | tuple[int, ...]], tuple[str, int | tuple[int, ...]]] | None):
            Maps ``(element, idx)`` to ``(element, idx)`` — e.g. ``{("q", 0): ("q", 1)}`` to port
            qubit 0's operations onto qubit 1. Unlisted ``(element, idx)`` pairs pass through.
        naming (BusNaming | None): Re-resolve every ref under a new
            [`BusNaming`][qprogram.BusNaming] (cross-platform names).
        strings (Mapping[str, str] | None): Escape hatch for raw-string buses (which carry no
            schema metadata): an old→new map. Map a string to itself to mark it intentionally
            untouched.
        allow_unported_strings (bool, optional): When ``False`` (default), a raw-string bus not
            covered by ``strings`` raises — a partial port is a loud choice, not a silent
            accident. Set ``True`` to leave uncovered raw-string buses in place.

    Returns:
        A new [`QProgram`][qprogram.QProgram]; the original is untouched.

    Raises:
        ValidationError: If ``naming`` is given without a schema, or raw-string buses are left
            unported without ``allow_unported_strings``.
        AttributeError: If a rebound ``(element, idx, kind)`` does not resolve against the target
            schema (e.g. the target element lacks that bus kind).
        KeyError: If the target schema's naming pattern names a placeholder other than
            ``{element}``, ``{index}`` or ``{kind}``.
        ValueError: If the target schema's naming pattern is not a well-formed format string.
    """
    program = self.expand() if self.fragments else copy.deepcopy(self)
    target_schema = schema if schema is not None else program._schema
    if naming is not None:
        if target_schema is None:
            msg = "rebind(naming=...) requires the program to have a schema to re-resolve against"
            raise ValidationError(msg)
        target_schema = naming_substituted_schema(target_schema, naming)
    element_map = dict(elements or {})
    string_map = dict(strings or {})
    unported: set[str] = set()

    # swap in lockstep; None stays None for raw-string programs
    program._schema = target_schema

    _map_bus_attrs(
        program._body,
        lambda bus: _rebind_bus(bus, target_schema, element_map, string_map, unported),
    )

    if unported and not allow_unported_strings:
        names = ", ".join(repr(b) for b in sorted(unported))
        msg = (
            f"rebind left raw-string bus(es) unported: {names}. Raw strings carry no schema metadata "
            f"to re-resolve — map them via strings={{...}} (map a name to itself to keep it), or pass "
            f"allow_unported_strings=True to leave them in place."
        )
        raise ValidationError(msg)

    program._rederive_auto_measurement_names()

    for bus in _iter_bus_attrs(program._body):
        program._validate_bus(bus)

    return program

def with_waveforms(
    self,
    waveforms: WaveformLibrary | Mapping[str, Waveform | IQWaveform],
) -> QProgram:
    """Return a copy with string waveform names resolved to concrete waveforms, scoped per bus.

    For each operation whose waveform attribute is still a string, the name is looked up against
    ``waveforms`` *for that operation's bus* — so a shared name like ``"pi_pulse"`` can resolve to a
    different concrete pulse on ``q[0].drive`` than on ``q[1].drive``. Concrete waveforms and names
    with no matching entry pass through unchanged. Each replacement re-runs the channel-type check,
    so an IQ pulse landing on a single-channel bus is caught here rather than at the hardware compiler.

    Args:
        waveforms (WaveformLibrary | Mapping[str, Waveform | IQWaveform]): A
            [`WaveformLibrary`][qprogram.WaveformLibrary] (resolved per bus), or a plain
            ``{name: waveform}`` mapping (one global tier, resolved on every bus).

    Returns:
        A new [`QProgram`][qprogram.QProgram] with matching names replaced; the original is untouched.

    Raises:
        ValidationError: If a resolved waveform's channel count does not match its bus's, or if
            ``waveforms`` is a mapping keyed by anything other than non-empty strings.
    """
    library = waveforms if isinstance(waveforms, WaveformLibrary) else WaveformLibrary.from_mapping(waveforms)
    new_program = copy.deepcopy(self)
    _resolve_waveforms(new_program._body, library)
    return new_program

def from_range(self, start: float, stop: float, step: float = 1) -> _LoopContext:
    """Sweep a ramp from ``start`` to ``stop`` in increments of ``step``, both ends inclusive.

    Builds [`Range`][qprogram.Range], which is where the validation rules live.

    Args:
        start (float): First value (inclusive).
        stop (float): Final value (inclusive).
        step (float, optional): Increment between consecutive points. Defaults to ``1``.

    Returns:
        The context manager that opens the sweep block.
    """
    return self._bind(Range(start, stop, step))

def from_linspace(self, start: float, stop: float, num: int) -> _LoopContext:
    """Sweep ``num`` evenly spaced points from ``start`` to ``stop``, both ends inclusive.

    Builds [`Linspace`][qprogram.Linspace] — the ramp to prefer when you know the point count
    rather than the spacing.

    Args:
        start (float): First value (inclusive).
        stop (float): Final value (inclusive).
        num (int): Number of points. ``1`` yields ``[start]``.

    Returns:
        The context manager that opens the sweep block.
    """
    return self._bind(Linspace(start, stop, num))

def from_logspace(self, start: float, stop: float, num: int) -> _LoopContext:
    """Sweep ``num`` points spaced evenly on a log scale between ``start`` and ``stop``.

    Builds [`Logspace`][qprogram.Logspace]. Both bounds are actual values, not exponents.

    Args:
        start (float): First value (inclusive). Must be strictly positive.
        stop (float): Final value (inclusive). Must be strictly positive.
        num (int): Number of points.

    Returns:
        The context manager that opens the sweep block.
    """
    return self._bind(Logspace(start, stop, num))

def from_values(self, points: npt.ArrayLike) -> _LoopContext:
    """Sweep an explicit list of points.

    Builds [`Values`][qprogram.Values], which is ``KIND = "arbitrary"`` even when the points
    happen to be evenly spaced — use `from_range` or `from_linspace` when the sweep
    really is a ramp and you want a platform to be able to compile it as one.

    Args:
        points (ArrayLike): Sequence of values to iterate through. Anything
            `numpy.asarray` accepts.

    Returns:
        The context manager that opens the sweep block.
    """
    return self._bind(Values(points))