ophyd-async 0.2.0__py3-none-any.whl → 0.3a1__py3-none-any.whl

ophyd_async/core/device_save_loader.py

@@ -45,30 +45,29 @@ class OphydDumper(yaml.Dumper):
 def get_signal_values(
     signals: Dict[str, SignalRW[Any]], ignore: Optional[List[str]] = None
 ) -> Generator[Msg, Sequence[Location[Any]], Dict[str, Any]]:
-    """
-    Read the values of SignalRW's, to be used alongside `walk_rw_signals`. Used as part
-    of saving a device.
+    """Get signal values in bulk.
+
+    Used as part of saving the signals of a device to a yaml file.
+
     Parameters
     ----------
-        signals : Dict[str, SignalRW]: A dictionary matching the string attribute path
-        of a SignalRW to the signal itself
+    signals : Dict[str, SignalRW]
+        Dictionary with pv names and matching SignalRW values. Often the direct result
+        of :func:`walk_rw_signals`.
 
-        ignore : List of strings: . A list of string attribute paths to the SignalRW's
-        to be ignored.
+    ignore : Optional[List[str]]
+        Optional list of PVs that should be ignored.
 
     Returns
     -------
-        Dict[str, Any]: A dictionary matching the string attribute path of a SignalRW
-        to the value of that signal. Ignored attributes are set to None.
-
-    Yields:
-        Iterator[Dict[str, Any]]: The Location of a signal
+    Dict[str, Any]
+        A dictionary containing pv names and their associated values. Ignored pvs are
+        set to None.
 
     See Also
     --------
     :func:`ophyd_async.core.walk_rw_signals`
     :func:`ophyd_async.core.save_to_yaml`
-
     """
 
     ignore = ignore or []
@@ -93,9 +92,11 @@ def get_signal_values(
 def walk_rw_signals(
     device: Device, path_prefix: Optional[str] = ""
 ) -> Dict[str, SignalRW[Any]]:
-    """
-    Get all the SignalRWs from a device and store them with their dotted attribute
-    paths in a dictionary. Used as part of saving and loading a device
+    """Retrieve all SignalRWs from a device.
+
+    Stores retrieved signals with their dotted attribute paths in a dictionary. Used as
+    part of saving and loading a device.
+
     Parameters
     ----------
     device : Device
@@ -131,9 +132,7 @@ def walk_rw_signals(
 
 
 def save_to_yaml(phases: Sequence[Dict[str, Any]], save_path: str) -> None:
-    """
-    Serialises and saves a phase or a set of phases of a device's SignalRW's to a
-    yaml file.
+    """Plan which serialises a phase or set of phases of SignalRWs to a yaml file.
 
     Parameters
     ----------
@@ -163,8 +162,7 @@ def save_to_yaml(phases: Sequence[Dict[str, Any]], save_path: str) -> None:
 
 
 def load_from_yaml(save_path: str) -> Sequence[Dict[str, Any]]:
-    """
-    Returns a list of dicts with saved signal values from a yaml file
+    """Plan that returns a list of dicts with saved signal values from a yaml file.
 
     Parameters
     ----------
@@ -183,18 +181,22 @@ def load_from_yaml(save_path: str) -> Sequence[Dict[str, Any]]:
 def set_signal_values(
     signals: Dict[str, SignalRW[Any]], values: Sequence[Dict[str, Any]]
 ) -> Generator[Msg, None, None]:
-    """
-    Loads a phase or a set of phases from a yaml file and puts value to an Ophyd device
+    """Maps signals from a yaml file into device signals.
+
+    ``values`` contains signal values in phases, which are loaded in sequentially
+    into the provided signals, to ensure signals are set in the correct order.
 
     Parameters
     ----------
     signals : Dict[str, SignalRW[Any]]
         Dictionary of named signals to be updated if value found in values argument.
+        Can be the output of :func:`walk_rw_signals()` for a device.
 
     values : Sequence[Dict[str, Any]]
         List of dictionaries of signal name and value pairs, if a signal matches
         the name of one in the signals argument, sets the signal to that value.
         The groups of signals are loaded in their list order.
+        Can be the output of :func:`load_from_yaml()` for a yaml file.
 
     See Also
     --------
@@ -206,8 +208,79 @@ def set_signal_values(
     for phase_number, phase in enumerate(values):
         # Key is signal name
         for key, value in phase.items():
+            # Skip ignored values
+            if value is None:
+                continue
+
             if key in signals:
                 yield from abs_set(
                     signals[key], value, group=f"load-phase{phase_number}"
                 )
+
         yield from wait(f"load-phase{phase_number}")
+
+
+def load_device(device: Device, path: str):
+    """Plan which loads PVs from a yaml file into a device.
+
+    Parameters
+    ----------
+    device: Device
+        The device to load PVs into
+    path: str
+        Path of the yaml file to load
+
+    See Also
+    --------
+    :func:`ophyd_async.core.save_device`
+    """
+    values = load_from_yaml(path)
+    signals_to_set = walk_rw_signals(device)
+    yield from set_signal_values(signals_to_set, values)
+
+
+def all_at_once(values: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+    """Sort all the values into a single phase so they are set all at once"""
+    return [values]
+
+
+def save_device(
+    device: Device,
+    path: str,
+    sorter: Callable[[Dict[str, Any]], Sequence[Dict[str, Any]]] = all_at_once,
+    ignore: Optional[List[str]] = None,
+):
+    """Plan that saves the state of all PV's on a device using a sorter.
+
+    The default sorter assumes all saved PVs can be loaded at once, and therefore
+    can be saved at one time, i.e. all PVs will appear on one list in the
+    resulting yaml file.
+
+    This can be a problem, because when the yaml is ingested with
+    :func:`ophyd_async.core.load_device`, it will set all of those PVs at once.
+    However, some PV's need to be set before others - this is device specific.
+
+    Therefore, users should consider the order of device loading and write their
+    own sorter algorithms accordingly.
+
+    See :func:`ophyd_async.panda.phase_sorter` for a valid implementation of the
+    sorter.
+
+    Parameters
+    ----------
+    device : Device
+        The device whose PVs should be saved.
+
+    path : str
+        The path where the resulting yaml should be saved to
+
+    sorter : Callable[[Dict[str, Any]], Sequence[Dict[str, Any]]]
+
+    ignore : Optional[List[str]]
+
+    See Also
+    --------
+    :func:`ophyd_async.core.load_device`
+    """
+    values = yield from get_signal_values(walk_rw_signals(device), ignore=ignore)
+    save_to_yaml(sorter(values), path)

ophyd_async/core/flyer.py

@@ -1,157 +1,17 @@
-import asyncio
-import time
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import (
-    AsyncIterator,
-    Callable,
-    Dict,
-    Generic,
-    List,
-    Optional,
-    Sequence,
-    TypeVar,
-)
+from typing import Dict, Generic, Optional, Sequence, TypeVar
 
-from bluesky.protocols import (
-    Asset,
-    Collectable,
-    Descriptor,
-    Flyable,
-    HasHints,
-    Hints,
-    Movable,
-    Reading,
-    Stageable,
-    WritesExternalAssets,
-)
+from bluesky.protocols import Descriptor, Flyable, Preparable, Reading, Stageable
 
 from .async_status import AsyncStatus
-from .detector import DetectorControl, DetectorTrigger, DetectorWriter
+from .detector import TriggerInfo
 from .device import Device
 from .signal import SignalR
-from .utils import DEFAULT_TIMEOUT, gather_list, merge_gathered_dicts
+from .utils import merge_gathered_dicts
 
 T = TypeVar("T")
 
 
-@dataclass(frozen=True)
-class TriggerInfo:
-    #: Number of triggers that will be sent
-    num: int
-    #: Sort of triggers that will be sent
-    trigger: DetectorTrigger
-    #: What is the minimum deadtime between triggers
-    deadtime: float
-    #: What is the maximum high time of the triggers
-    livetime: float
-
-
-class DetectorGroupLogic(ABC):
-    # Read multipliers here, exposure is set in the plan
-
-    @abstractmethod
-    async def open(self) -> Dict[str, Descriptor]:
-        """Open all writers, wait for them to be open and return their descriptors"""
-
-    @abstractmethod
-    async def ensure_armed(self, trigger_info: TriggerInfo):
-        """Ensure the detectors are armed, return AsyncStatus that waits for disarm."""
-
-    @abstractmethod
-    def collect_asset_docs(self) -> AsyncIterator[Asset]:
-        """Collect asset docs from all writers"""
-
-    @abstractmethod
-    async def wait_for_index(
-        self, index: int, timeout: Optional[float] = DEFAULT_TIMEOUT
-    ):
-        """Wait until a specific index is ready to be collected"""
-
-    @abstractmethod
-    async def disarm(self):
-        """Disarm detectors"""
-
-    @abstractmethod
-    async def close(self):
-        """Close all writers and wait for them to be closed"""
-
-    @abstractmethod
-    def hints(self) -> Hints:
-        """Produce hints specifying which dataset(s) are most important"""
-
-
-class SameTriggerDetectorGroupLogic(DetectorGroupLogic):
-    def __init__(
-        self,
-        controllers: Sequence[DetectorControl],
-        writers: Sequence[DetectorWriter],
-    ) -> None:
-        self._controllers = controllers
-        self._writers = writers
-        self._arm_statuses: Sequence[AsyncStatus] = ()
-        self._trigger_info: Optional[TriggerInfo] = None
-
-    async def open(self) -> Dict[str, Descriptor]:
-        return await merge_gathered_dicts(writer.open() for writer in self._writers)
-
-    async def ensure_armed(self, trigger_info: TriggerInfo):
-        if (
-            not self._arm_statuses
-            or any(status.done for status in self._arm_statuses)
-            or trigger_info != self._trigger_info
-        ):
-            # We need to re-arm
-            await self.disarm()
-            for controller in self._controllers:
-                required = controller.get_deadtime(trigger_info.livetime)
-                assert required <= trigger_info.deadtime, (
-                    f"Detector {controller} needs at least {required}s deadtime, "
-                    f"but trigger logic provides only {trigger_info.deadtime}s"
-                )
-            self._arm_statuses = await gather_list(
-                controller.arm(
-                    trigger=trigger_info.trigger, exposure=trigger_info.livetime
-                )
-                for controller in self._controllers
-            )
-            self._trigger_info = trigger_info
-
-    async def collect_asset_docs(self) -> AsyncIterator[Asset]:
-        # the below is confusing: gather_list does return an awaitable, but it itself
-        # is a coroutine so we must call await twice...
-        indices_written = min(
-            await gather_list(writer.get_indices_written() for writer in self._writers)
-        )
-        for writer in self._writers:
-            async for doc in writer.collect_stream_docs(indices_written):
-                yield doc
-
-    async def wait_for_index(
-        self, index: int, timeout: Optional[float] = DEFAULT_TIMEOUT
-    ):
-        await gather_list(
-            writer.wait_for_index(index, timeout=timeout) for writer in self._writers
-        )
-
-    async def disarm(self):
-        await gather_list(controller.disarm() for controller in self._controllers)
-        await gather_list(self._arm_statuses)
-
-    async def close(self):
-        await gather_list(writer.close() for writer in self._writers)
-
-    def hints(self) -> Hints:
-        return {
-            "fields": [
-                field
-                for writer in self._writers
-                if hasattr(writer, "hints")
-                for field in writer.hints.get("fields")
-            ]
-        }
-
-
 class TriggerLogic(ABC, Generic[T]):
     @abstractmethod
     def trigger_info(self, value: T) -> TriggerInfo:
@@ -172,128 +32,63 @@ class TriggerLogic(ABC, Generic[T]):
 
 class HardwareTriggeredFlyable(
     Device,
-    Movable,
     Stageable,
+    Preparable,
     Flyable,
-    Collectable,
-    WritesExternalAssets,
-    HasHints,
     Generic[T],
 ):
     def __init__(
         self,
-        detector_group_logic: DetectorGroupLogic,
         trigger_logic: TriggerLogic[T],
         configuration_signals: Sequence[SignalR],
-        trigger_to_frame_timeout: Optional[float] = DEFAULT_TIMEOUT,
         name: str = "",
     ):
-        self._detector_group_logic = detector_group_logic
         self._trigger_logic = trigger_logic
         self._configuration_signals = tuple(configuration_signals)
         self._describe: Dict[str, Descriptor] = {}
-        self._watchers: List[Callable] = []
         self._fly_status: Optional[AsyncStatus] = None
-        self._fly_start = 0.0
-        self._offset = 0  # Add this to index to get frame number
-        self._current_frame = 0  # The current frame we are on
-        self._last_frame = 0  # The last frame that will be emitted
-        self._trigger_to_frame_timeout = trigger_to_frame_timeout
+        self._trigger_info: Optional[TriggerInfo] = None
         super().__init__(name=name)
 
+    @property
+    def trigger_logic(self) -> TriggerLogic[T]:
+        return self._trigger_logic
+
+    @property
+    def trigger_info(self) -> Optional[TriggerInfo]:
+        return self._trigger_info
+
     @AsyncStatus.wrap
     async def stage(self) -> None:
         await self.unstage()
-        self._describe = await self._detector_group_logic.open()
-        self._offset = 0
-        self._current_frame = 0
-
-    def set(self, value: T) -> AsyncStatus:
-        """Arm detectors and setup trajectories"""
-        # index + offset = current_frame, but starting a new scan so want it to be 0
-        # so subtract current_frame from both sides
-        return AsyncStatus(self._set(value))
-
-    async def _set(self, value: T) -> None:
-        self._offset -= self._current_frame
-        self._current_frame = 0
-        await self._prepare(value)
 
-    async def _prepare(self, value: T):
-        trigger_info = self._trigger_logic.trigger_info(value)
-        # Move to start and setup the flyscan, and arm dets in parallel
-        await asyncio.gather(
-            self._detector_group_logic.ensure_armed(trigger_info),
-            self._trigger_logic.prepare(value),
-        )
-        self._last_frame = self._current_frame + trigger_info.num
-
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
-        return await merge_gathered_dicts(
-            [sig.describe() for sig in self._configuration_signals]
-        )
+    @AsyncStatus.wrap
+    async def unstage(self) -> None:
+        await self._trigger_logic.stop()
 
-    async def read_configuration(self) -> Dict[str, Reading]:
-        return await merge_gathered_dicts(
-            [sig.read() for sig in self._configuration_signals]
-        )
+    def prepare(self, value: T) -> AsyncStatus:
+        """Setup trajectories"""
+        return AsyncStatus(self._prepare(value))
 
-    async def describe_collect(self) -> Dict[str, Descriptor]:
-        return self._describe
+    async def _prepare(self, value: T) -> None:
+        self._trigger_info = self._trigger_logic.trigger_info(value)
+        # Move to start and setup the flyscan
+        await self._trigger_logic.prepare(value)
 
     @AsyncStatus.wrap
     async def kickoff(self) -> None:
-        self._watchers = []
-        self._fly_status = AsyncStatus(self._fly(), self._watchers)
-        self._fly_start = time.monotonic()
-
-    async def _fly(self) -> None:
-        await self._trigger_logic.start()
-        # Wait for all detectors to have written up to a particular frame
-        await self._detector_group_logic.wait_for_index(
-            self._last_frame - self._offset, timeout=self._trigger_to_frame_timeout
-        )
-
-    async def collect_asset_docs(self) -> AsyncIterator[Asset]:
-        current_frame = self._current_frame
-        stream_datums: List[Asset] = []
-        async for asset in self._detector_group_logic.collect_asset_docs():
-            name, doc = asset
-            if name == "stream_datum":
-                current_frame = doc["indices"]["stop"] + self._offset
-                # Defer stream_datums until all stream_resources have been produced
-                # In a single collect, all the stream_resources are produced first
-                # followed by their stream_datums
-                stream_datums.append(asset)
-            else:
-                yield asset
-        for asset in stream_datums:
-            yield asset
-        if current_frame != self._current_frame:
-            self._current_frame = current_frame
-            for watcher in self._watchers:
-                watcher(
-                    name=self.name,
-                    current=current_frame,
-                    initial=0,
-                    target=self._last_frame,
-                    unit="",
-                    precision=0,
-                    time_elapsed=time.monotonic() - self._fly_start,
-                )
+        self._fly_status = AsyncStatus(self._trigger_logic.start())
 
     def complete(self) -> AsyncStatus:
         assert self._fly_status, "Kickoff not run"
         return self._fly_status
 
-    @AsyncStatus.wrap
-    async def unstage(self) -> None:
-        await asyncio.gather(
-            self._trigger_logic.stop(),
-            self._detector_group_logic.close(),
-            self._detector_group_logic.disarm(),
+    async def describe_configuration(self) -> Dict[str, Descriptor]:
+        return await merge_gathered_dicts(
+            [sig.describe() for sig in self._configuration_signals]
         )
 
-    @property
-    def hints(self) -> Hints:
-        return self._detector_group_logic.hints()
+    async def read_configuration(self) -> Dict[str, Reading]:
+        return await merge_gathered_dicts(
+            [sig.read() for sig in self._configuration_signals]
+        )

ophyd_async/core/signal.py

@@ -58,7 +58,7 @@ class Signal(Device, Generic[T]):
     def set_name(self, name: str = ""):
         self._name = name
 
-    async def connect(self, sim=False):
+    async def connect(self, sim=False, timeout=DEFAULT_TIMEOUT):
         if sim:
             self._backend = SimSignalBackend(
                 datatype=self._init_backend.datatype, source=self._init_backend.source
@@ -67,7 +67,7 @@ class Signal(Device, Generic[T]):
         else:
             self._backend = self._init_backend
             _sim_backends.pop(self, None)
-        await self._backend.connect()
+        await self._backend.connect(timeout=timeout)
 
     @property
     def source(self) -> str:
@@ -253,7 +253,7 @@ def set_sim_callback(signal: Signal[T], callback: ReadingValueCallback[T]) -> No
     return _sim_backends[signal].set_callback(callback)
 
 
-async def observe_value(signal: SignalR[T]) -> AsyncGenerator[T, None]:
+async def observe_value(signal: SignalR[T], timeout=None) -> AsyncGenerator[T, None]:
     """Subscribe to the value of a signal so it can be iterated from.
 
     Parameters
@@ -270,10 +270,17 @@ async def observe_value(signal: SignalR[T]) -> AsyncGenerator[T, None]:
             do_something_with(value)
     """
     q: asyncio.Queue[T] = asyncio.Queue()
+    if timeout is None:
+        get_value = q.get
+    else:
+
+        async def get_value():
+            return await asyncio.wait_for(q.get(), timeout)
+
     signal.subscribe_value(q.put_nowait)
     try:
         while True:
-            yield await q.get()
+            yield await get_value()
     finally:
         signal.clear_sub(q.put_nowait)
 

ophyd_async/core/signal_backend.py

@@ -3,7 +3,7 @@ from typing import Generic, Optional, Type
 
 from bluesky.protocols import Descriptor, Reading
 
-from .utils import ReadingValueCallback, T
+from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
 
 
 class SignalBackend(Generic[T]):
@@ -16,7 +16,7 @@ class SignalBackend(Generic[T]):
     source: str = ""
 
     @abstractmethod
-    async def connect(self):
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT):
         """Connect to underlying hardware"""
 
     @abstractmethod

ophyd_async/core/sim_signal_backend.py

@@ -12,7 +12,7 @@ from typing import Any, Dict, Generic, Optional, Type, Union, cast, get_origin
 from bluesky.protocols import Descriptor, Dtype, Reading
 
 from .signal_backend import SignalBackend
-from .utils import ReadingValueCallback, T, get_dtype
+from .utils import DEFAULT_TIMEOUT, ReadingValueCallback, T, get_dtype
 
 primitive_dtypes: Dict[type, Dtype] = {
     str: "string",
@@ -123,7 +123,7 @@ class SimSignalBackend(SignalBackend[T]):
         self.put_proceeds.set()
         self.callback: Optional[ReadingValueCallback[T]] = None
 
-    async def connect(self) -> None:
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
         self.converter = make_converter(self.datatype)
         self._initial_value = self.converter.make_initial_value(self.datatype)
         self._severity = 0