ophyd-async 0.2.0__py3-none-any.whl → 0.3.0__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,170 +1,29 @@
-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, Sequence, TypeVar
 
-from bluesky.protocols import (
-    Asset,
-    Collectable,
-    Descriptor,
-    Flyable,
-    HasHints,
-    Hints,
-    Movable,
-    Reading,
-    Stageable,
-    WritesExternalAssets,
-)
+from bluesky.protocols import DataKey, Flyable, Preparable, Reading, Stageable
 
 from .async_status import AsyncStatus
-from .detector import DetectorControl, DetectorTrigger, DetectorWriter
 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:
-        """Return info about triggers that will be produced for a given value"""
-
     @abstractmethod
     async def prepare(self, value: T):
         """Move to the start of the flyscan"""
 
     @abstractmethod
-    async def start(self):
+    async def kickoff(self):
         """Start the flyscan"""
 
+    @abstractmethod
+    async def complete(self):
+        """Block until the flyscan is done"""
+
     @abstractmethod
     async def stop(self):
         """Stop flying and wait everything to be stopped"""
@@ -172,63 +31,50 @@ 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,
+        configuration_signals: Sequence[SignalR] = (),
         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
         super().__init__(name=name)
 
+    @property
+    def trigger_logic(self) -> TriggerLogic[T]:
+        return self._trigger_logic
+
     @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))
+    @AsyncStatus.wrap
+    async def unstage(self) -> None:
+        await self._trigger_logic.stop()
 
-    async def _set(self, value: T) -> None:
-        self._offset -= self._current_frame
-        self._current_frame = 0
-        await self._prepare(value)
+    def prepare(self, value: T) -> AsyncStatus:
+        """Setup trajectories"""
+        return AsyncStatus(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 _prepare(self, value: T) -> None:
+        # Move to start and setup the flyscan
+        await self._trigger_logic.prepare(value)
 
-    async def describe_configuration(self) -> Dict[str, Descriptor]:
+    @AsyncStatus.wrap
+    async def kickoff(self) -> None:
+        await self._trigger_logic.kickoff()
+
+    @AsyncStatus.wrap
+    async def complete(self) -> None:
+        await self._trigger_logic.complete()
+
+    async def describe_configuration(self) -> Dict[str, DataKey]:
         return await merge_gathered_dicts(
             [sig.describe() for sig in self._configuration_signals]
         )
@@ -237,63 +83,3 @@ class HardwareTriggeredFlyable(
         return await merge_gathered_dicts(
             [sig.read() for sig in self._configuration_signals]
         )
-
-    async def describe_collect(self) -> Dict[str, Descriptor]:
-        return self._describe
-
-    @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,
-                )
-
-    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(),
-        )
-
-    @property
-    def hints(self) -> Hints:
-        return self._detector_group_logic.hints()

ophyd_async/core/mock_signal_backend.py

@@ -0,0 +1,82 @@
+import asyncio
+from functools import cached_property
+from typing import Callable, Optional, Type
+from unittest.mock import Mock
+
+from bluesky.protocols import Descriptor, Reading
+
+from ophyd_async.core.signal_backend import SignalBackend
+from ophyd_async.core.soft_signal_backend import SoftSignalBackend
+from ophyd_async.core.utils import DEFAULT_TIMEOUT, ReadingValueCallback, T
+
+
+class MockSignalBackend(SignalBackend[T]):
+    def __init__(
+        self,
+        datatype: Optional[Type[T]] = None,
+        initial_backend: Optional[SignalBackend[T]] = None,
+    ) -> None:
+        if isinstance(initial_backend, MockSignalBackend):
+            raise ValueError("Cannot make a MockSignalBackend for a MockSignalBackends")
+
+        self.initial_backend = initial_backend
+
+        if datatype is None:
+            assert (
+                self.initial_backend
+            ), "Must supply either initial_backend or datatype"
+            datatype = self.initial_backend.datatype
+
+        self.datatype = datatype
+
+        if not isinstance(self.initial_backend, SoftSignalBackend):
+            # If the backend is a hard signal backend, or not provided,
+            # then we create a soft signal to mimic it
+
+            self.soft_backend = SoftSignalBackend(datatype=datatype)
+        else:
+            self.soft_backend = self.initial_backend
+
+    def source(self, name: str) -> str:
+        if self.initial_backend:
+            return f"mock+{self.initial_backend.source(name)}"
+        return f"mock+{name}"
+
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT) -> None:
+        pass
+
+    @cached_property
+    def put_mock(self) -> Mock:
+        return Mock(name="put", spec=Callable)
+
+    @cached_property
+    def put_proceeds(self) -> asyncio.Event:
+        put_proceeds = asyncio.Event()
+        put_proceeds.set()
+        return put_proceeds
+
+    async def put(self, value: Optional[T], wait=True, timeout=None):
+        self.put_mock(value, wait=wait, timeout=timeout)
+        await self.soft_backend.put(value, wait=wait, timeout=timeout)
+
+        if wait:
+            await asyncio.wait_for(self.put_proceeds.wait(), timeout=timeout)
+
+    def set_value(self, value: T):
+        self.soft_backend.set_value(value)
+
+    async def get_reading(self) -> Reading:
+        return await self.soft_backend.get_reading()
+
+    async def get_value(self) -> T:
+        return await self.soft_backend.get_value()
+
+    async def get_setpoint(self) -> T:
+        """For a soft signal, the setpoint and readback values are the same."""
+        return await self.soft_backend.get_setpoint()
+
+    async def get_datakey(self, source: str) -> Descriptor:
+        return await self.soft_backend.get_datakey(source)
+
+    def set_callback(self, callback: Optional[ReadingValueCallback[T]]) -> None:
+        self.soft_backend.set_callback(callback)