quelware-client 0.7.2__tar.gz → 0.7.4__tar.gz

{quelware_client-0.7.2 → quelware_client-0.7.4}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.7.4] - 2026-11-02
+
+### Added
+
+- `Session.abort_runs()`, which stops the session's runs on every unit, before the trigger time or part way through. A run stops as a whole, because its instruments share the unit's waveform generators and captures, so it takes no instruments. Waiting for an instrument of a run raises the server's abort error. `AbortFailedError` is raised, once every unit has been asked, when some units failed; `failures` holds the error of each, by unit.
+- `UnitBusyError` is raised also by `Session.abort_runs` while a trigger or initialize of the session is running, and by a trigger or initialize while `abort_runs` is.
+
+## [0.7.3] - 2026-10-01
+
+### Added
+
+- `examples/fixed_timeline.py`, the code of the fixed-timeline tutorial as a script you can run against a system. The docs quote it, and the lint and the type check cover it, so it keeps up with the API.
+- `NotTriggeredError`: `Session.wait_for_results`, `Session.wait_for_result`, `Session.fetch_result` and the same methods of `InstrumentDriver` raise it immediately if an instrument was not in the last trigger on its unit. Before, the request went to the unit, which could hang (armed but not triggered), return an empty result, or fail with `INTERNAL`. Within a session, each unit has at most one run: a new trigger on the unit replaces it, and initializing an instrument on the unit clears it. Other sessions on the unit have their own runs.
+- `UnitBusyError`: `Session.trigger` and `Session.initialize` raise it immediately if a trigger or initialize of the same session is already running on the unit.
+- `InitializeFailedError`: `Session.initialize` raises it, once every unit has finished, when some units failed; `failures` holds the error of each, by unit.
+- `Session.initialize(instrument_ids, parallel=True)`, which initializes the units at the same time, or one after another when not `parallel`, and every unit also after one fails, `Session.fetch_result(instrument_id)` and `Session.wait_for_result(instrument_id, timeout_sec=None)`. The `InstrumentDriver` methods of the same names now call them, so the session knows which instruments can be waited for.
+
+### Changed
+
+- `InstrumentDriver` requires the `session` it belongs to. `create_instrument_driver_fixed_timeline` passes it, so only code that builds a driver directly needs a change.
+- `InstrumentAgent.apply` is renamed `arm`, because it arms the instruments (`InstrumentDriver.apply` configures an instrument). It still calls the `Apply` RPC.
+
 ## [0.7.2] - 2026-09-29
 
 ### Changed

{quelware_client-0.7.2 → quelware_client-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quelware-client
-Version: 0.7.2
+Version: 0.7.4
 Project-URL: Repository, https://github.com/quel-inc/quelware-client
 Project-URL: Documentation, https://quel-inc.github.io/quelware-client/
 Project-URL: Changelog, https://github.com/quel-inc/quelware-client/blob/main/quelware-client/CHANGELOG.md

quelware_client-0.7.4/examples/fixed_timeline.py

@@ -0,0 +1,173 @@
+"""A drive pulse and a readout on fixed-timeline instruments.
+
+The code of the fixed-timeline tutorial, which the docs quote from here. Run it
+against your system:
+
+    python fixed_timeline.py <host> --unit <label>
+"""
+
+# --8<-- [start:imports]
+import argparse
+import asyncio
+
+import numpy as np
+from quelware_core.entities import directives
+from quelware_core.entities.instrument import (
+    FixedTimelineProfile,
+    InstrumentDefinition,
+    InstrumentInfo,
+    InstrumentMode,
+    InstrumentRole,
+)
+
+from quelware_client import create_quelware_client
+from quelware_client.client.helpers.sequencer import Sequencer
+from quelware_client.core import QuelwareClient, Session
+from quelware_client.core.exceptions import RunFailedError
+from quelware_client.core.instrument_driver import (
+    create_instrument_driver_fixed_timeline,
+)
+
+# --8<-- [end:imports]
+
+
+# --8<-- [start:deploy]
+def definition(alias: str, role: InstrumentRole, center_hz: float):
+    return InstrumentDefinition(
+        alias=alias,
+        mode=InstrumentMode.FIXED_TIMELINE,
+        role=role,
+        profile=FixedTimelineProfile(
+            frequency_range_min=center_hz - 2.5e6,
+            frequency_range_max=center_hz + 2.5e6,
+        ),
+    )
+
+
+async def deploy(
+    qc: QuelwareClient, drive_port: str, readout_port: str
+) -> tuple[InstrumentInfo, InstrumentInfo]:
+    async with qc.create_session([drive_port, readout_port]) as session:
+        (drive,) = await session.deploy_instruments(
+            drive_port, [definition("drive", InstrumentRole.TRANSMITTER, 5.0e9)]
+        )
+        (readout,) = await session.deploy_instruments(
+            readout_port,
+            [definition("readout", InstrumentRole.TRANSCEIVER_LOOPBACK, 6.0e9)],
+        )
+    return drive, readout
+
+
+# --8<-- [end:deploy]
+
+
+# --8<-- [start:timeline]
+def build_timeline(
+    inst_info: InstrumentInfo, pulse_start_ns: float, capture: bool
+) -> Sequencer:
+    alias = inst_info.definition.alias
+    sampling_period_ns = inst_info.config.sampling_period_fs * 1e-6
+
+    seq = Sequencer(default_sampling_period_ns=sampling_period_ns)
+    seq.bind(
+        alias,
+        sampling_period_fs=inst_info.config.sampling_period_fs,
+        step_samples=inst_info.config.timeline_step_samples,
+    )
+
+    n = int(200.0 / sampling_period_ns)  # a 200 ns rectangular pulse
+    seq.register_waveform("pulse", np.ones(n, dtype=complex))
+    seq.add_event(alias, "pulse", start_offset_ns=pulse_start_ns)
+    if capture:
+        seq.add_capture_window(
+            alias, "capture", start_offset_ns=pulse_start_ns, length_ns=1000.0
+        )
+    seq.extend_length_ns(100_000.0)  # gap before the next shot
+    seq.set_iterations(1000)  # average over 1000 shots
+    return seq
+
+
+# --8<-- [end:timeline]
+
+
+# --8<-- [start:trigger]
+async def configure(
+    session: Session, inst_info: InstrumentInfo, hz: float, seq: Sequencer
+) -> None:
+    driver = create_instrument_driver_fixed_timeline(session, inst_info)
+    alias = inst_info.definition.alias
+    settings: list[directives.FixedTimelineDirective] = [directives.SetFrequency(hz=hz)]
+    if inst_info.definition.role is not InstrumentRole.TRANSMITTER:
+        settings.append(
+            directives.SetCaptureMode(mode=directives.CaptureMode.AVERAGED_WAVEFORM)
+        )
+    settings.append(seq.export_set_fixed_timeline_directive(alias))
+    await driver.initialize()
+    await driver.apply(settings)
+
+
+async def trigger(
+    session: Session, drive: InstrumentInfo, readout: InstrumentInfo
+) -> None:
+    await configure(session, drive, 5.0e9, build_timeline(drive, 0.0, capture=False))
+    await configure(
+        session, readout, 6.0e9, build_timeline(readout, 300.0, capture=True)
+    )
+    await session.trigger([drive.id, readout.id])
+
+
+# --8<-- [end:trigger]
+
+
+# --8<-- [start:wait]
+async def wait(
+    session: Session, drive: InstrumentInfo, readout: InstrumentInfo
+) -> np.ndarray:
+    try:
+        results = await session.wait_for_results(
+            [drive.id, readout.id], timeout_sec=10.0
+        )
+    except RunFailedError as e:
+        for instrument_id, error in e.failures.items():
+            print(f"{instrument_id} failed: {error}")
+        raise
+    return results[readout.id].iq_waveform_result["capture"][0].iq_array
+
+
+# --8<-- [end:wait]
+
+
+# --8<-- [start:main]
+async def main(host: str, port: int, drive_port: str, readout_port: str) -> None:
+    qc = create_quelware_client(host, port)
+    async with qc:
+        drive, readout = await deploy(qc, drive_port, readout_port)
+        async with qc.create_session([drive.id, readout.id], ttl_ms=10_000) as session:
+            await trigger(session, drive, readout)
+            iq = await wait(session, drive, readout)
+    print(f"captured {len(iq)} samples")
+
+
+# --8<-- [end:main]
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Run a drive pulse and a readout on fixed-timeline instruments."
+    )
+    parser.add_argument("host", help="server host")
+    parser.add_argument("--port", type=int, default=50051, help="server port")
+    parser.add_argument("--unit", required=True, help="unit label")
+    parser.add_argument("--drive-port", default="tx_p02", help="a transmitter port")
+    parser.add_argument(
+        "--readout-port", default="trx_p00p01", help="a transceiver port"
+    )
+    args = parser.parse_args()
+    asyncio.run(
+        main(
+            args.host,
+            args.port,
+            f"{args.unit}:{args.drive_port}",
+            f"{args.unit}:{args.readout_port}",
+        )
+    )

{quelware_client-0.7.2 → quelware_client-0.7.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "quelware-client"
-version = "0.7.2"
+version = "0.7.4"
 description = ""
 readme = "README.md"
 authors = [

{quelware_client-0.7.2 → quelware_client-0.7.4}/src/quelware_client/core/_session.py

@@ -1,7 +1,8 @@
 import asyncio
 import logging
 import math
-from collections.abc import Collection, Mapping
+from collections.abc import Collection, Iterator, Mapping
+from contextlib import contextmanager
 from types import TracebackType
 from typing import cast
 
@@ -15,7 +16,14 @@ from quelware_core.entities.session import SessionToken
 from quelware_core.entities.unit import UnitLabel
 
 from quelware_client.core import AgentContainer
-from quelware_client.core.exceptions import RunFailedError, ServiceUnavailableError
+from quelware_client.core.exceptions import (
+    AbortFailedError,
+    InitializeFailedError,
+    NotTriggeredError,
+    RunFailedError,
+    ServiceUnavailableError,
+    UnitBusyError,
+)
 from quelware_client.core.trigger_count_proposer import (
     FixedOffsetTriggerCountProposer,
     TriggerCountProposer,
@@ -45,6 +53,13 @@ class Session:
         await session.trigger(instrument_ids)
         results = await session.wait_for_results(instrument_ids)
     ```
+
+    Within a session, each unit has at most one run. A new trigger on a unit
+    replaces its run, and initializing an instrument on the unit clears it.
+    Other sessions on the same unit have their own runs. The session remembers
+    which instruments were in the last trigger on each unit, and waits only for
+    those. Another `Session` object built with the same token does not share
+    this record.
     """
 
     def __init__(  # noqa: PLR0913
@@ -90,6 +105,10 @@ class Session:
             self._unit_to_ids.setdefault(ul, []).append(rid)
 
         self._check_lock = not skip_lock_check
+        # instruments in the last trigger on each unit of this session
+        self._triggered: set[ResourceId] = set()
+        # units where a trigger, initialize or abort_runs of this session is running now
+        self._busy_units: set[UnitLabel] = set()
 
     async def open(self):
         """Open the session, locking its resources and obtaining a token.
@@ -262,33 +281,53 @@ class Session:
         instrument_ids: Collection[ResourceId],
         wait_ms: int | None = None,
     ) -> int:
-        """Apply pending configuration and trigger the given instruments.
+        """Arm the given instruments, then trigger them.
 
-        The instruments' configuration is applied first, then a trigger is
-        scheduled. If the manager-side trigger service is unavailable, the
-        client falls back to a client-side trigger: a self-timed trigger for a
-        single unit, or a clock-synchronized trigger across multiple units.
+        Arming puts the configuration of each instrument on its unit's device,
+        as the run of the session there. Then the server schedules a trigger,
+        at which every unit starts. If the server's trigger service is
+        unavailable, the client triggers the units itself: a self-timed trigger
+        for a single unit, or a clock-synchronized trigger across several.
 
         Args:
             instrument_ids: Instruments to trigger.
-            wait_ms: Delay, in milliseconds, from now to when the trigger
-                fires, giving every unit time to start on it. ``None`` leaves
-                it to the server (600 ms across units, 200 ms for one); the
-                server raises a shorter one to 150 ms, and the client-side
-                fallback path to 500 ms.
+            wait_ms: Delay, in milliseconds, from now to when the run starts,
+                giving every unit time to start on it. ``None`` leaves it to
+                the server, which also raises a wait shorter than it allows.
+                When the client triggers the units itself, it waits at least
+                500 ms.
 
         Returns:
             The clock count at which the trigger was scheduled.
+
+        Raises:
+            UnitBusyError: Immediately, if a trigger, initialize or abort_runs of this
+                session is already running on one of the units.
         """
         unit_to_ids = create_unit_to_ids_map(instrument_ids)
+        with self._claiming(unit_to_ids):
+            # arming replaces the session's run on the unit, so forget the old
+            # one now, even if this trigger fails
+            self._forget_runs_on(unit_to_ids)
+            scheduled = await self._arm_and_trigger(
+                instrument_ids, unit_to_ids, wait_ms
+            )
+            self._triggered.update(instrument_ids)
+        return scheduled
 
-        logger.info(f"starting application (token= {self.token} )")
-        apply_coros = [
-            self._agent.instrument(unit_label).apply(self.token, ids)
+    async def _arm_and_trigger(
+        self,
+        instrument_ids: Collection[ResourceId],
+        unit_to_ids: dict[UnitLabel, list[ResourceId]],
+        wait_ms: int | None,
+    ) -> int:
+        logger.info(f"starting arming (token= {self.token} )")
+        arm_coros = [
+            self._agent.instrument(unit_label).arm(self.token, ids)
             for unit_label, ids in unit_to_ids.items()
         ]
-        await asyncio.gather(*apply_coros)
-        logger.info(f"finished application (token= {self.token} )")
+        await asyncio.gather(*arm_coros)
+        logger.info(f"finished arming (token= {self.token} )")
 
         try:
             scheduled = await self._agent.trigger.trigger(
@@ -314,8 +353,10 @@ class Session:
     ) -> dict[ResourceId, ResultContainer]:
         """Wait for the result of every one of the instruments of a run.
 
-        Pass the instruments given to `trigger()`: an instrument without a
-        capture window is waited for as well, and its result is empty.
+        Pass the instruments given to `trigger()`. An instrument without a
+        capture window is waited for too, and its result is empty. Only the
+        instruments in the last trigger on each unit can be waited for, and not
+        after an instrument on that unit is initialized.
 
         Args:
             instrument_ids: Instruments to wait for.
@@ -325,11 +366,14 @@ class Session:
             Each instrument's result.
 
         Raises:
+            NotTriggeredError: Immediately, if an instrument was not in the last
+                trigger on its unit.
             RunFailedError: If any instrument failed, once all of them have
                 finished, with the error of each that failed and the results of
                 the others.
             TimeoutError: If some are still running when ``timeout_sec`` runs out.
         """
+        self._ensure_triggered(instrument_ids)
         tasks = {
             asyncio.ensure_future(
                 self._agent.instrument(extract_unit_label(rid)).wait_for_result(
@@ -361,6 +405,172 @@ class Session:
             raise RunFailedError(failures, results)
         return results
 
+    async def initialize(
+        self, instrument_ids: Collection[ResourceId], parallel: bool = True
+    ) -> None:
+        """Initialize the given instruments.
+
+        An initialized instrument is empty: armed, it plays and captures
+        nothing until it is given a timeline again. This also clears the
+        session's run on each of their units: no instrument on those units can
+        be waited for until the next trigger there.
+
+        Args:
+            instrument_ids: Instruments to initialize.
+            parallel: Initialize the units at the same time, the default; when
+                False, one unit after another. Either way every unit is
+                initialized, also after one fails, and the instruments of one
+                unit are always initialized in one call.
+
+        Raises:
+            UnitBusyError: Immediately, if a trigger, initialize or abort_runs of this
+                session is already running on one of the units.
+            InitializeFailedError: If some units failed, once every unit has
+                finished, with the error of each unit that failed.
+        """
+        unit_to_ids = create_unit_to_ids_map(instrument_ids)
+        with self._claiming(unit_to_ids):
+            self._forget_runs_on(unit_to_ids)
+            if parallel:
+                # wait for every unit, so that none is still initializing once
+                # the units are let go
+                outcomes = await asyncio.gather(
+                    *(
+                        self._initialize_unit(unit_label, ids)
+                        for unit_label, ids in unit_to_ids.items()
+                    )
+                )
+            else:
+                outcomes = [
+                    await self._initialize_unit(unit_label, ids)
+                    for unit_label, ids in unit_to_ids.items()
+                ]
+            failures = {
+                unit_label: outcome
+                for unit_label, outcome in zip(unit_to_ids, outcomes, strict=True)
+                if outcome is not None
+            }
+            if failures:
+                raise InitializeFailedError(failures, len(unit_to_ids))
+
+    async def _initialize_unit(
+        self, unit_label: UnitLabel, instrument_ids: list[ResourceId]
+    ) -> Exception | None:
+        """Initialize the instruments of a unit, and return its error, if any."""
+        try:
+            await self._agent.instrument(unit_label).initialize(
+                self.token, instrument_ids
+            )
+        except Exception as e:
+            return e
+        return None
+
+    async def abort_runs(self) -> None:
+        """Stop the session's runs, on every unit.
+
+        The run on a unit is the session's last trigger there, and it stops as
+        a whole: its instruments share the unit's waveform generators and
+        captures, so one of them cannot stop without the others. Every
+        instrument of the runs is aborted, and waiting for one raises the
+        server's abort error. A unit stops its run before the trigger time
+        comes, or part way through, and leaves a run that has already finished
+        as it is. The instruments keep their configuration, so the same runs
+        can be triggered again.
+
+        Raises:
+            UnitBusyError: Immediately, if a trigger, initialize or abort_runs of this
+                session is running on any unit, since the run it makes is not
+                known yet.
+            AbortFailedError: If some units failed, once every unit has been
+                asked, with the error of each unit that failed.
+        """
+        runs = {
+            unit_label: sorted(ids)
+            for unit_label, ids in create_unit_to_ids_map(self._triggered).items()
+        }
+        with self._claiming(set(runs) | self._busy_units):
+            outcomes = await asyncio.gather(
+                *(
+                    self._agent.instrument(unit_label).abort(self.token, ids)
+                    for unit_label, ids in runs.items()
+                ),
+                return_exceptions=True,
+            )
+        failures = {
+            unit_label: outcome
+            for unit_label, outcome in zip(runs, outcomes, strict=True)
+            if isinstance(outcome, BaseException)
+        }
+        if failures:
+            raise AbortFailedError(failures, len(runs))
+
+    async def fetch_result(self, instrument_id: ResourceId) -> ResultContainer:
+        """Fetch the result of one instrument, with a single request.
+
+        Unlike `wait_for_result()`, this does not retry when the request times
+        out.
+
+        Raises:
+            NotTriggeredError: Immediately, if the instrument was not in the last
+                trigger on its unit.
+        """
+        self._ensure_triggered([instrument_id])
+        agent = self._agent.instrument(extract_unit_label(instrument_id))
+        return await agent.fetch_result(self.token, instrument_id)
+
+    async def wait_for_result(
+        self, instrument_id: ResourceId, timeout_sec: float | None = None
+    ) -> ResultContainer:
+        """Wait for the result of one instrument.
+
+        Unlike `wait_for_results()`, this raises the instrument's own error if
+        it failed.
+
+        Args:
+            instrument_id: Instrument to wait for.
+            timeout_sec: Maximum time to wait; ``None`` waits without limit.
+
+        Raises:
+            NotTriggeredError: Immediately, if the instrument was not in the last
+                trigger on its unit.
+        """
+        self._ensure_triggered([instrument_id])
+        agent = self._agent.instrument(extract_unit_label(instrument_id))
+        return await agent.wait_for_result(self.token, instrument_id, timeout_sec)
+
+    @contextmanager
+    def _claiming(self, unit_labels: Collection[UnitLabel]) -> Iterator[None]:
+        """Mark the units as busy during a trigger, initialize or abort_runs.
+
+        Two of them at the same time on one unit would make the record of
+        triggered instruments wrong.
+        """
+        units = set(unit_labels)
+        if busy := sorted(units & self._busy_units):
+            raise UnitBusyError().with_unit_labels(busy)
+        self._busy_units |= units
+        try:
+            yield
+        finally:
+            self._busy_units -= units
+
+    def _forget_runs_on(self, unit_labels: Collection[UnitLabel]) -> None:
+        """Forget the triggered instruments on the units."""
+        units = set(unit_labels)
+        self._triggered = {
+            rid for rid in self._triggered if extract_unit_label(rid) not in units
+        }
+
+    def _ensure_triggered(self, instrument_ids: Collection[ResourceId]) -> None:
+        """Raise if an instrument was not in the last trigger on its unit.
+
+        Raises:
+            NotTriggeredError: With the ids of those instruments.
+        """
+        missing = sorted(set(instrument_ids) - self._triggered)
+        if missing:
+            raise NotTriggeredError().with_resource_ids(missing)
+
     async def _client_side_trigger_fallback(
         self,
         unit_to_ids: dict[UnitLabel, list[ResourceId]],

{quelware_client-0.7.2 → quelware_client-0.7.4}/src/quelware_client/core/exceptions/__init__.py

@@ -101,3 +101,54 @@ class RunFailedError(QuelwareClientError):
             f"{len(self.failures)} of {len(self.failures) + len(self.results)} "
             f"instruments failed: {detail}"
         )
+
+
+class InitializeFailedError(QuelwareClientError):
+    """Raised when the initialize of some units failed.
+
+    ``failures`` holds the error of each unit that failed, by its label. The
+    other units were initialized.
+    """
+
+    def __init__(self, failures: Mapping[UnitLabel, BaseException], units: int):
+        self.failures = dict(failures)
+        detail = "; ".join(f"{u}: {e}" for u, e in sorted(self.failures.items()))
+        super().__init__(
+            f"initialize failed on {len(self.failures)} of {units} units: {detail}"
+        )
+
+
+class AbortFailedError(QuelwareClientError):
+    """Raised when abort_runs failed on some units.
+
+    ``failures`` holds the error of each unit that failed, by its label. The
+    other units were aborted.
+    """
+
+    def __init__(self, failures: Mapping[UnitLabel, BaseException], units: int):
+        self.failures = dict(failures)
+        detail = "; ".join(f"{u}: {e}" for u, e in sorted(self.failures.items()))
+        super().__init__(
+            f"abort_runs failed on {len(self.failures)} of {units} units: {detail}"
+        )
+
+
+class NotTriggeredError(_ErrorWithResourceIdsMixin, QuelwareClientError):
+    """Raised when waiting for an instrument that was not triggered.
+
+    Within a session, each unit has at most one run. A new trigger on the unit
+    replaces it, and initializing an instrument on the unit clears it. So only
+    the instruments in the last trigger on each unit can be waited for.
+    """
+
+    DEFAULT_MESSAGE = "The instruments were not in the last trigger on their unit."
+
+
+class UnitBusyError(_ErrorWithUnitLabelsMixin, QuelwareClientError):
+    """Raised when a trigger, initialize or abort_runs of the same session is already
+    running on the unit."""
+
+    DEFAULT_MESSAGE = (
+        "A trigger, initialize or abort_runs of this session is already running "
+        "on the unit."
+    )