ophyd-async 0.2.0__py3-none-any.whl → 0.3a2__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 Descriptor, 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,61 +31,48 @@ 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
         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)
+
+    @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, Descriptor]:
         return await merge_gathered_dicts(
@@ -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/signal.py

@@ -2,19 +2,20 @@ from __future__ import annotations
 
 import asyncio
 import functools
-from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Union
+from typing import AsyncGenerator, Callable, Dict, Generic, Optional, Tuple, Type, Union
 
 from bluesky.protocols import (
     Descriptor,
     Locatable,
     Location,
     Movable,
-    Readable,
     Reading,
     Stageable,
     Subscribable,
 )
 
+from ophyd_async.protocols import AsyncReadable
+
 from .async_status import AsyncStatus
 from .device import Device
 from .signal_backend import SignalBackend
@@ -45,34 +46,28 @@ class Signal(Device, Generic[T]):
     """A Device with the concept of a value, with R, RW, W and X flavours"""
 
     def __init__(
-        self, backend: SignalBackend[T], timeout: Optional[float] = DEFAULT_TIMEOUT
+        self,
+        backend: SignalBackend[T],
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        name: str = "",
     ) -> None:
-        self._name = ""
+        super().__init__(name)
         self._timeout = timeout
         self._init_backend = self._backend = backend
 
-    @property
-    def name(self) -> str:
-        return self._name
-
-    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
-            )
+            self._backend = SimSignalBackend(datatype=self._init_backend.datatype)
             _sim_backends[self] = self._backend
         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:
         """Like ca://PV_PREFIX:SIGNAL, or "" if not set"""
-        return self._backend.source
+        return self._backend.source(self.name)
 
     __lt__ = __le__ = __eq__ = __ge__ = __gt__ = __ne__ = _fail
 
@@ -133,7 +128,7 @@ class _SignalCache(Generic[T]):
         return self._staged or bool(self._listeners)
 
 
-class SignalR(Signal[T], Readable, Stageable, Subscribable):
+class SignalR(Signal[T], AsyncReadable, Stageable, Subscribable):
     """Signal that can be read from and monitored"""
 
     _cache: Optional[_SignalCache] = None
@@ -168,7 +163,7 @@ class SignalR(Signal[T], Readable, Stageable, Subscribable):
     @_add_timeout
     async def describe(self) -> Dict[str, Descriptor]:
         """Return a single item dict with the descriptor in it"""
-        return {self.name: await self._backend.get_descriptor()}
+        return {self.name: await self._backend.get_descriptor(self.source)}
 
     @_add_timeout
     async def get_value(self, cached: Optional[bool] = None) -> T:
@@ -253,7 +248,31 @@ 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]:
+def soft_signal_rw(
+    datatype: Optional[Type[T]] = None,
+    initial_value: Optional[T] = None,
+    name: str = "",
+) -> SignalRW[T]:
+    """Creates a read-writable Signal with a SimSignalBackend"""
+    signal = SignalRW(SimSignalBackend(datatype, initial_value), name=name)
+    return signal
+
+
+def soft_signal_r_and_backend(
+    datatype: Optional[Type[T]] = None,
+    initial_value: Optional[T] = None,
+    name: str = "",
+) -> Tuple[SignalR[T], SimSignalBackend]:
+    """Returns a tuple of a read-only Signal and its SimSignalBackend through
+    which the signal can be internally modified within the device. Use
+    soft_signal_rw if you want a device that is externally modifiable
+    """
+    backend = SimSignalBackend(datatype, initial_value)
+    signal = SignalR(backend, name=name)
+    return (signal, backend)
+
+
+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 +289,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]):
@@ -13,10 +13,13 @@ class SignalBackend(Generic[T]):
     datatype: Optional[Type[T]] = None
 
     #: Like ca://PV_PREFIX:SIGNAL
-    source: str = ""
+    @abstractmethod
+    def source(name: str) -> str:
+        """Return source of signal. Signals may pass a name to the backend, which can be
+        used or discarded."""
 
     @abstractmethod
-    async def connect(self):
+    async def connect(self, timeout: float = DEFAULT_TIMEOUT):
         """Connect to underlying hardware"""
 
     @abstractmethod
@@ -24,7 +27,7 @@ class SignalBackend(Generic[T]):
         """Put a value to the PV, if wait then wait for completion for up to timeout"""
 
     @abstractmethod
-    async def get_descriptor(self) -> Descriptor:
+    async def get_descriptor(self, source: str) -> Descriptor:
         """Metadata like source, dtype, shape, precision, units"""
 
     @abstractmethod