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

ophyd_async/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.0'
-__version_tuple__ = version_tuple = (0, 1, 0)
+__version__ = version = '0.3a1'
+__version_tuple__ = version_tuple = (0, 3)

ophyd_async/core/__init__.py

@@ -1,6 +1,24 @@
-from ._device._backend.signal_backend import SignalBackend
-from ._device._backend.sim_signal_backend import SimSignalBackend
-from ._device._signal.signal import (
+from ._providers import (
+    DirectoryInfo,
+    DirectoryProvider,
+    NameProvider,
+    ShapeProvider,
+    StaticDirectoryProvider,
+)
+from .async_status import AsyncStatus
+from .detector import DetectorControl, DetectorTrigger, DetectorWriter, StandardDetector
+from .device import Device, DeviceCollector, DeviceVector
+from .device_save_loader import (
+    get_signal_values,
+    load_device,
+    load_from_yaml,
+    save_device,
+    save_to_yaml,
+    set_signal_values,
+    walk_rw_signals,
+)
+from .flyer import HardwareTriggeredFlyable, TriggerInfo, TriggerLogic
+from .signal import (
     Signal,
     SignalR,
     SignalRW,
@@ -13,11 +31,9 @@ from ._device._signal.signal import (
     set_sim_value,
     wait_for_value,
 )
-from ._device.device import Device
-from ._device.device_collector import DeviceCollector
-from ._device.device_vector import DeviceVector
-from ._device.standard_readable import StandardReadable
-from .async_status import AsyncStatus
+from .signal_backend import SignalBackend
+from .sim_signal_backend import SimSignalBackend
+from .standard_readable import StandardReadable
 from .utils import (
     DEFAULT_TIMEOUT,
     Callback,
@@ -33,6 +49,13 @@ from .utils import (
 __all__ = [
     "SignalBackend",
     "SimSignalBackend",
+    "DetectorControl",
+    "DetectorTrigger",
+    "DetectorWriter",
+    "StandardDetector",
+    "Device",
+    "DeviceCollector",
+    "DeviceVector",
     "Signal",
     "SignalR",
     "SignalW",
@@ -44,11 +67,16 @@ __all__ = [
     "set_sim_put_proceeds",
     "set_sim_value",
     "wait_for_value",
-    "Device",
-    "DeviceCollector",
-    "DeviceVector",
-    "StandardReadable",
     "AsyncStatus",
+    "DirectoryInfo",
+    "DirectoryProvider",
+    "NameProvider",
+    "ShapeProvider",
+    "StaticDirectoryProvider",
+    "StandardReadable",
+    "TriggerInfo",
+    "TriggerLogic",
+    "HardwareTriggeredFlyable",
     "DEFAULT_TIMEOUT",
     "Callback",
     "NotConnected",
@@ -58,4 +86,11 @@ __all__ = [
     "get_unique",
     "merge_gathered_dicts",
     "wait_for_connection",
+    "get_signal_values",
+    "load_from_yaml",
+    "save_to_yaml",
+    "set_signal_values",
+    "walk_rw_signals",
+    "load_device",
+    "save_device",
 ]

ophyd_async/core/_providers.py

@@ -0,0 +1,66 @@
+from abc import abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional, Protocol, Sequence, Union
+
+
+@dataclass
+class DirectoryInfo:
+    """
+    Information about where and how to write a file.
+
+    The bluesky event model splits the URI for a resource into two segments to aid in
+    different applications mounting filesystems at different mount points.
+    The portion of this path which is relevant only for the writer is the 'root',
+    while the path from an agreed upon mutual mounting is the resource_path.
+    The resource_dir is used with the filename to construct the resource_path.
+
+    :param root: Path of a root directory, relevant only for the file writer
+    :param resource_dir: Directory into which files should be written, relative to root
+    :param prefix: Optional filename prefix to add to all files
+    :param suffix: Optional filename suffix to add to all files
+    """
+
+    root: Path
+    resource_dir: Path
+    prefix: Optional[str] = ""
+    suffix: Optional[str] = ""
+
+
+class DirectoryProvider(Protocol):
+    @abstractmethod
+    def __call__(self) -> DirectoryInfo:
+        """Get the current directory to write files into"""
+
+
+class StaticDirectoryProvider(DirectoryProvider):
+    def __init__(
+        self,
+        directory_path: Union[str, Path],
+        filename_prefix: str = "",
+        filename_suffix: str = "",
+        resource_dir: Path = Path("."),
+    ) -> None:
+        if isinstance(directory_path, str):
+            directory_path = Path(directory_path)
+        self._directory_info = DirectoryInfo(
+            root=directory_path,
+            resource_dir=resource_dir,
+            prefix=filename_prefix,
+            suffix=filename_suffix,
+        )
+
+    def __call__(self) -> DirectoryInfo:
+        return self._directory_info
+
+
+class NameProvider(Protocol):
+    @abstractmethod
+    def __call__(self) -> str:
+        """Get the name to be used as a data_key in the descriptor document"""
+
+
+class ShapeProvider(Protocol):
+    @abstractmethod
+    async def __call__(self) -> Sequence[int]:
+        """Get the shape of the data collection"""

ophyd_async/core/async_status.py

@@ -1,4 +1,4 @@
-"""Equivalent of bluesky.protols.Status for asynchronous tasks."""
+"""Equivalent of bluesky.protocols.Status for asynchronous tasks."""
 
 import asyncio
 import functools
@@ -62,7 +62,9 @@ class AsyncStatus(Status):
     @property
     def success(self) -> bool:
         return (
-            self.task.done() and not self.task.cancelled() and not self.task.exception()
+            self.task.done()
+            and not self.task.cancelled()
+            and self.task.exception() is None
         )
 
     def watch(self, watcher: Callable):
@@ -83,12 +85,12 @@ class AsyncStatus(Status):
 
     def __repr__(self) -> str:
         if self.done:
-            if self.exception() is not None:
-                status = "errored"
+            if e := self.exception():
+                status = f"errored: {repr(e)}"
             else:
                 status = "done"
         else:
             status = "pending"
-        return f"<{type(self).__name__} {status}>"
+        return f"<{type(self).__name__}, task: {self.task.get_coro()}, {status}>"
 
     __str__ = __repr__

ophyd_async/core/detector.py

@@ -0,0 +1,321 @@
+"""Module which defines abstract classes to work with detectors"""
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from typing import (
+    AsyncGenerator,
+    AsyncIterator,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+)
+
+from bluesky.protocols import (
+    Collectable,
+    Configurable,
+    Descriptor,
+    Flyable,
+    Preparable,
+    Readable,
+    Reading,
+    Stageable,
+    StreamAsset,
+    Triggerable,
+    WritesStreamAssets,
+)
+
+from .async_status import AsyncStatus
+from .device import Device
+from .signal import SignalR
+from .utils import DEFAULT_TIMEOUT, merge_gathered_dicts
+
+T = TypeVar("T")
+
+
+class DetectorTrigger(str, Enum):
+    #: Detector generates internal trigger for given rate
+    internal = "internal"
+    #: Expect a series of arbitrary length trigger signals
+    edge_trigger = "edge_trigger"
+    #: Expect a series of constant width external gate signals
+    constant_gate = "constant_gate"
+    #: Expect a series of variable width external gate signals
+    variable_gate = "variable_gate"
+
+
+@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 DetectorControl(ABC):
+    @abstractmethod
+    def get_deadtime(self, exposure: float) -> float:
+        """For a given exposure, how long should the time between exposures be"""
+
+    @abstractmethod
+    async def arm(
+        self,
+        num: int,
+        trigger: DetectorTrigger = DetectorTrigger.internal,
+        exposure: Optional[float] = None,
+    ) -> AsyncStatus:
+        """Arm the detector and return AsyncStatus.
+
+        Awaiting the return value will wait for num frames to be written.
+        """
+
+    @abstractmethod
+    async def disarm(self):
+        """Disarm the detector"""
+
+
+class DetectorWriter(ABC):
+    @abstractmethod
+    async def open(self, multiplier: int = 1) -> Dict[str, Descriptor]:
+        """Open writer and wait for it to be ready for data.
+
+        Args:
+            multiplier: Each StreamDatum index corresponds to this many
+                written exposures
+
+        Returns:
+            Output for ``describe()``
+        """
+
+    @abstractmethod
+    def observe_indices_written(
+        self, timeout=DEFAULT_TIMEOUT
+    ) -> AsyncGenerator[int, None]:
+        """Yield each index as it is written"""
+
+    @abstractmethod
+    async def get_indices_written(self) -> int:
+        """Get the number of indices written"""
+
+    @abstractmethod
+    def collect_stream_docs(self, indices_written: int) -> AsyncIterator[StreamAsset]:
+        """Create Stream docs up to given number written"""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close writer and wait for it to be finished"""
+
+
+class StandardDetector(
+    Device,
+    Stageable,
+    Configurable,
+    Readable,
+    Triggerable,
+    Preparable,
+    Flyable,
+    Collectable,
+    WritesStreamAssets,
+):
+    """Detector with useful step and flyscan behaviour.
+
+    Must be supplied instances of classes that inherit from DetectorControl and
+    DetectorData, to dictate how the detector will be controlled (i.e. arming and
+    disarming) as well as how the detector data will be written (i.e. opening and
+    closing the writer, and handling data writing indices).
+
+    """
+
+    def __init__(
+        self,
+        controller: DetectorControl,
+        writer: DetectorWriter,
+        config_sigs: Sequence[SignalR] = (),
+        name: str = "",
+        writer_timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        control:
+            instance of class which inherits from :class:`DetectorControl`
+        data:
+            instance of class which inherits from :class:`DetectorData`
+        name:
+            detector name
+        """
+        self._controller = controller
+        self._writer = writer
+        self._describe: Dict[str, Descriptor] = {}
+        self._config_sigs = list(config_sigs)
+        self._frame_writing_timeout = writer_timeout
+        # For prepare
+        self._arm_status: Optional[AsyncStatus] = None
+        self._trigger_info: Optional[TriggerInfo] = None
+        # For kickoff
+        self._watchers: List[Callable] = []
+        self._fly_status: Optional[AsyncStatus] = None
+        self._fly_start: float
+
+        self._intial_frame: int
+        self._last_frame: int
+        super().__init__(name)
+
+    @property
+    def controller(self) -> DetectorControl:
+        return self._controller
+
+    @property
+    def writer(self) -> DetectorWriter:
+        return self._writer
+
+    @AsyncStatus.wrap
+    async def stage(self) -> None:
+        """Disarm the detector, stop filewriting, and open file for writing."""
+        await self.check_config_sigs()
+        await asyncio.gather(self.writer.close(), self.controller.disarm())
+        self._describe = await self.writer.open()
+
+    async def check_config_sigs(self):
+        """Checks configuration signals are named and connected."""
+        for signal in self._config_sigs:
+            if signal._name == "":
+                raise Exception(
+                    "config signal must be named before it is passed to the detector"
+                )
+            try:
+                await signal.get_value()
+            except NotImplementedError:
+                raise Exception(
+                    f"config signal {signal._name} must be connected before it is "
+                    + "passed to the detector"
+                )
+
+    @AsyncStatus.wrap
+    async def unstage(self) -> None:
+        """Stop data writing."""
+        await self.writer.close()
+
+    async def read_configuration(self) -> Dict[str, Reading]:
+        return await merge_gathered_dicts(sig.read() for sig in self._config_sigs)
+
+    async def describe_configuration(self) -> Dict[str, Descriptor]:
+        return await merge_gathered_dicts(sig.describe() for sig in self._config_sigs)
+
+    async def read(self) -> Dict[str, Reading]:
+        """Read the detector"""
+        # All data is in StreamResources, not Events, so nothing to output here
+        return {}
+
+    def describe(self) -> Dict[str, Descriptor]:
+        return self._describe
+
+    @AsyncStatus.wrap
+    async def trigger(self) -> None:
+        """Arm the detector and wait for it to finish."""
+        indices_written = await self.writer.get_indices_written()
+        written_status = await self.controller.arm(
+            num=1,
+            trigger=DetectorTrigger.internal,
+        )
+        await written_status
+        end_observation = indices_written + 1
+
+        async for index in self.writer.observe_indices_written(
+            self._frame_writing_timeout
+        ):
+            if index >= end_observation:
+                break
+
+    def prepare(
+        self,
+        value: T,
+    ) -> AsyncStatus:
+        """Arm detector"""
+        return AsyncStatus(self._prepare(value))
+
+    async def _prepare(self, value: T) -> None:
+        """Arm detector.
+
+        Prepare the detector with trigger information. This is determined at and passed
+        in from the plan level.
+
+        This currently only prepares detectors for flyscans and stepscans just use the
+        trigger information determined in trigger.
+
+        To do: Unify prepare to be use for both fly and step scans.
+        """
+        assert type(value) is TriggerInfo
+        self._trigger_info = value
+        self._initial_frame = await self.writer.get_indices_written()
+        self._last_frame = self._initial_frame + self._trigger_info.num
+
+        required = self.controller.get_deadtime(self._trigger_info.livetime)
+        assert required <= self._trigger_info.deadtime, (
+            f"Detector {self.controller} needs at least {required}s deadtime, "
+            f"but trigger logic provides only {self._trigger_info.deadtime}s"
+        )
+
+        self._arm_status = await self.controller.arm(
+            num=self._trigger_info.num,
+            trigger=self._trigger_info.trigger,
+            exposure=self._trigger_info.livetime,
+        )
+
+    @AsyncStatus.wrap
+    async def kickoff(self) -> None:
+        self._fly_status = AsyncStatus(self._fly(), self._watchers)
+        self._fly_start = time.monotonic()
+
+    async def _fly(self) -> None:
+        await self._observe_writer_indicies(self._last_frame)
+
+    async def _observe_writer_indicies(self, end_observation: int):
+        async for index in self.writer.observe_indices_written(
+            self._frame_writing_timeout
+        ):
+            for watcher in self._watchers:
+                watcher(
+                    name=self.name,
+                    current=index,
+                    initial=self._initial_frame,
+                    target=end_observation,
+                    unit="",
+                    precision=0,
+                    time_elapsed=time.monotonic() - self._fly_start,
+                )
+            if index >= end_observation:
+                break
+
+    @AsyncStatus.wrap
+    async def complete(self) -> AsyncStatus:
+        assert self._fly_status, "Kickoff not run"
+        return await self._fly_status
+
+    async def describe_collect(self) -> Dict[str, Descriptor]:
+        return self._describe
+
+    async def collect_asset_docs(
+        self, index: Optional[int] = None
+    ) -> AsyncIterator[StreamAsset]:
+        """Collect stream datum documents for all indices written.
+
+        The index is optional, and provided for flyscans, however this needs to be
+        retrieved for stepscans.
+        """
+        if not index:
+            index = await self.writer.get_indices_written()
+        async for doc in self.writer.collect_stream_docs(index):
+            yield doc
+
+    async def get_index(self) -> int:
+        return await self.writer.get_indices_written()

ophyd_async/core/device.py

@@ -0,0 +1,184 @@
+"""Base device"""
+
+from __future__ import annotations
+
+import sys
+from typing import (
+    Any,
+    Coroutine,
+    Dict,
+    Generator,
+    Iterator,
+    Optional,
+    Set,
+    Tuple,
+    TypeVar,
+)
+
+from bluesky.protocols import HasName
+from bluesky.run_engine import call_in_bluesky_event_loop
+
+from .utils import DEFAULT_TIMEOUT, NotConnected, wait_for_connection
+
+
+class Device(HasName):
+    """Common base class for all Ophyd Async Devices.
+
+    By default, names and connects all Device children.
+    """
+
+    _name: str = ""
+    #: The parent Device if it exists
+    parent: Optional[Device] = None
+
+    def __init__(self, name: str = "") -> None:
+        self.set_name(name)
+
+    @property
+    def name(self) -> str:
+        """Return the name of the Device"""
+        return self._name
+
+    def children(self) -> Iterator[Tuple[str, Device]]:
+        for attr_name, attr in self.__dict__.items():
+            if attr_name != "parent" and isinstance(attr, Device):
+                yield attr_name, attr
+
+    def set_name(self, name: str):
+        """Set ``self.name=name`` and each ``self.child.name=name+"-child"``.
+
+        Parameters
+        ----------
+        name:
+            New name to set
+        """
+        self._name = name
+        for attr_name, child in self.children():
+            child_name = f"{name}-{attr_name.rstrip('_')}" if name else ""
+            child.set_name(child_name)
+            child.parent = self
+
+    async def connect(self, sim: bool = False, timeout: float = DEFAULT_TIMEOUT):
+        """Connect self and all child Devices.
+
+        Contains a timeout that gets propagated to child.connect methods.
+
+        Parameters
+        ----------
+        sim:
+            If True then connect in simulation mode.
+        timeout:
+            Time to wait before failing with a TimeoutError.
+        """
+        coros = {
+            name: child_device.connect(sim, timeout=timeout)
+            for name, child_device in self.children()
+        }
+        if coros:
+            await wait_for_connection(**coros)
+
+
+VT = TypeVar("VT", bound=Device)
+
+
+class DeviceVector(Dict[int, VT], Device):
+    def children(self) -> Generator[Tuple[str, Device], None, None]:
+        for attr_name, attr in self.items():
+            if isinstance(attr, Device):
+                yield str(attr_name), attr
+
+
+class DeviceCollector:
+    """Collector of top level Device instances to be used as a context manager
+
+    Parameters
+    ----------
+    set_name:
+        If True, call ``device.set_name(variable_name)`` on all collected
+        Devices
+    connect:
+        If True, call ``device.connect(sim)`` in parallel on all
+        collected Devices
+    sim:
+        If True, connect Signals in simulation mode
+    timeout:
+        How long to wait for connect before logging an exception
+
+    Notes
+    -----
+    Example usage::
+
+        [async] with DeviceCollector():
+            t1x = motor.Motor("BLxxI-MO-TABLE-01:X")
+            t1y = motor.Motor("pva://BLxxI-MO-TABLE-01:Y")
+            # Names and connects devices here
+        assert t1x.comm.velocity.source
+        assert t1x.name == "t1x"
+
+    """
+
+    def __init__(
+        self,
+        set_name=True,
+        connect=True,
+        sim=False,
+        timeout: float = 10.0,
+    ):
+        self._set_name = set_name
+        self._connect = connect
+        self._sim = sim
+        self._timeout = timeout
+        self._names_on_enter: Set[str] = set()
+        self._objects_on_exit: Dict[str, Any] = {}
+
+    def _caller_locals(self):
+        """Walk up until we find a stack frame that doesn't have us as self"""
+        try:
+            raise ValueError
+        except ValueError:
+            _, _, tb = sys.exc_info()
+            assert tb, "Can't get traceback, this shouldn't happen"
+            caller_frame = tb.tb_frame
+            while caller_frame.f_locals.get("self", None) is self:
+                caller_frame = caller_frame.f_back
+            return caller_frame.f_locals
+
+    def __enter__(self) -> "DeviceCollector":
+        # Stash the names that were defined before we were called
+        self._names_on_enter = set(self._caller_locals())
+        return self
+
+    async def __aenter__(self) -> "DeviceCollector":
+        return self.__enter__()
+
+    async def _on_exit(self) -> None:
+        # Name and kick off connect for devices
+        connect_coroutines: Dict[str, Coroutine] = {}
+        for name, obj in self._objects_on_exit.items():
+            if name not in self._names_on_enter and isinstance(obj, Device):
+                if self._set_name and not obj.name:
+                    obj.set_name(name)
+                if self._connect:
+                    connect_coroutines[name] = obj.connect(
+                        self._sim, timeout=self._timeout
+                    )
+
+        # Connect to all the devices
+        if connect_coroutines:
+            await wait_for_connection(**connect_coroutines)
+
+    async def __aexit__(self, type, value, traceback):
+        self._objects_on_exit = self._caller_locals()
+        await self._on_exit()
+
+    def __exit__(self, type_, value, traceback):
+        self._objects_on_exit = self._caller_locals()
+        try:
+            fut = call_in_bluesky_event_loop(self._on_exit())
+        except RuntimeError:
+            raise NotConnected(
+                "Could not connect devices. Is the bluesky event loop running? See "
+                "https://blueskyproject.io/ophyd-async/main/"
+                "user/explanations/event-loop-choice.html for more info."
+            )
+        return fut