ophyd-async 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

ophyd_async/panda/_panda_controller.py

@@ -0,0 +1,37 @@
+import asyncio
+from typing import Optional
+
+from ophyd_async.core import (
+    AsyncStatus,
+    DetectorControl,
+    DetectorTrigger,
+    wait_for_value,
+)
+from ophyd_async.panda import PcapBlock
+
+
+class PandaPcapController(DetectorControl):
+    def __init__(self, pcap: PcapBlock) -> None:
+        self.pcap = pcap
+
+    def get_deadtime(self, exposure: float) -> float:
+        return 0.000000008
+
+    async def arm(
+        self,
+        num: int,
+        trigger: DetectorTrigger = DetectorTrigger.constant_gate,
+        exposure: Optional[float] = None,
+    ) -> AsyncStatus:
+        assert trigger in (
+            DetectorTrigger.constant_gate,
+            trigger == DetectorTrigger.variable_gate,
+        ), "Only constant_gate and variable_gate triggering is supported on the PandA"
+        await asyncio.gather(self.pcap.arm.set(True))
+        await wait_for_value(self.pcap.active, True, timeout=1)
+        return AsyncStatus(wait_for_value(self.pcap.active, False, timeout=None))
+
+    async def disarm(self) -> AsyncStatus:
+        await asyncio.gather(self.pcap.arm.set(False))
+        await wait_for_value(self.pcap.active, False, timeout=1)
+        return AsyncStatus(wait_for_value(self.pcap.active, False, timeout=None))

ophyd_async/panda/_trigger.py

@@ -0,0 +1,39 @@
+import asyncio
+from dataclasses import dataclass
+
+from ophyd_async.core import TriggerLogic, wait_for_value
+from ophyd_async.panda import SeqBlock, SeqTable, TimeUnits
+
+
+@dataclass
+class SeqTableInfo:
+    sequence_table: SeqTable
+    repeats: int
+    prescale_as_us: float = 1  # microseconds
+
+
+class StaticSeqTableTriggerLogic(TriggerLogic[SeqTableInfo]):
+    def __init__(self, seq: SeqBlock) -> None:
+        self.seq = seq
+
+    async def prepare(self, value: SeqTableInfo):
+        await asyncio.gather(
+            self.seq.prescale_units.set(TimeUnits.us),
+            self.seq.enable.set("ZERO"),
+        )
+        await asyncio.gather(
+            self.seq.prescale.set(value.prescale_as_us),
+            self.seq.repeats.set(value.repeats),
+            self.seq.table.set(value.sequence_table),
+        )
+
+    async def kickoff(self) -> None:
+        await self.seq.enable.set("ONE")
+        await wait_for_value(self.seq.active, True, timeout=1)
+
+    async def complete(self) -> None:
+        await wait_for_value(self.seq.active, False, timeout=None)
+
+    async def stop(self):
+        await self.seq.enable.set("ZERO")
+        await wait_for_value(self.seq.active, False, timeout=1)

ophyd_async/panda/_utils.py

@@ -0,0 +1,15 @@
+from typing import Any, Dict, Sequence
+
+
+def phase_sorter(panda_signal_values: Dict[str, Any]) -> Sequence[Dict[str, Any]]:
+    # Panda has two load phases. If the signal name ends in the string "UNITS",
+    # it needs to be loaded first so put in first phase
+    phase_1, phase_2 = {}, {}
+
+    for key, value in panda_signal_values.items():
+        if key.endswith("units"):
+            phase_1[key] = value
+        else:
+            phase_2[key] = value
+
+    return [phase_1, phase_2]

ophyd_async/panda/writers/__init__.py

@@ -0,0 +1,3 @@
+from ._hdf_writer import PandaHDFWriter
+
+__all__ = ["PandaHDFWriter"]

ophyd_async/panda/writers/_hdf_writer.py

@@ -0,0 +1,220 @@
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from typing import Any, AsyncGenerator, AsyncIterator, Dict, List, Optional
+
+from bluesky.protocols import DataKey, StreamAsset
+from p4p.client.thread import Context
+
+from ophyd_async.core import (
+    DEFAULT_TIMEOUT,
+    DetectorWriter,
+    Device,
+    DirectoryProvider,
+    NameProvider,
+    SignalR,
+    wait_for_value,
+)
+from ophyd_async.core.signal import observe_value
+from ophyd_async.panda import CommonPandaBlocks
+
+from ._panda_hdf_file import _HDFDataset, _HDFFile
+
+
+class Capture(str, Enum):
+    # Capture signals for the HDF Panda
+    No = "No"
+    Value = "Value"
+    Diff = "Diff"
+    Sum = "Sum"
+    Mean = "Mean"
+    Min = "Min"
+    Max = "Max"
+    MinMax = "Min Max"
+    MinMaxMean = "Min Max Mean"
+
+
+def get_capture_signals(
+    block: Device, path_prefix: Optional[str] = ""
+) -> Dict[str, SignalR]:
+    """Get dict mapping a capture signal's name to the signal itself"""
+    if not path_prefix:
+        path_prefix = ""
+    signals: Dict[str, SignalR[Any]] = {}
+    for attr_name, attr in block.children():
+        # Capture signals end in _capture, but num_capture is a red herring
+        if attr_name == "num_capture":
+            continue
+        dot_path = f"{path_prefix}{attr_name}"
+        if isinstance(attr, SignalR) and attr_name.endswith("_capture"):
+            signals[dot_path] = attr
+        attr_signals = get_capture_signals(attr, path_prefix=dot_path + ".")
+        signals.update(attr_signals)
+    return signals
+
+
+@dataclass
+class CaptureSignalWrapper:
+    signal: SignalR
+    capture_type: Capture
+
+
+# This should return a dictionary which contains a dict, containing the Capture
+# signal object, and the value of that signal
+async def get_signals_marked_for_capture(
+    capture_signals: Dict[str, SignalR],
+) -> Dict[str, CaptureSignalWrapper]:
+    # Read signals to see if they should be captured
+    do_read = [signal.get_value() for signal in capture_signals.values()]
+
+    signal_values = await asyncio.gather(*do_read)
+
+    assert len(signal_values) == len(
+        capture_signals
+    ), "Length of read signals are different to length of signals"
+
+    signals_to_capture: Dict[str, CaptureSignalWrapper] = {}
+    for signal_path, signal_object, signal_value in zip(
+        capture_signals.keys(), capture_signals.values(), signal_values
+    ):
+        signal_path = signal_path.replace("_capture", "")
+        if (signal_value in iter(Capture)) and (signal_value != Capture.No):
+            signals_to_capture[signal_path] = CaptureSignalWrapper(
+                signal_object,
+                signal_value,
+            )
+
+    return signals_to_capture
+
+
+class PandaHDFWriter(DetectorWriter):
+    _ctxt: Optional[Context] = None
+
+    def __init__(
+        self,
+        prefix: str,
+        directory_provider: DirectoryProvider,
+        name_provider: NameProvider,
+        panda_device: CommonPandaBlocks,
+    ) -> None:
+        self.panda_device = panda_device
+        self._prefix = prefix
+        self._directory_provider = directory_provider
+        self._name_provider = name_provider
+        self._datasets: List[_HDFDataset] = []
+        self._file: Optional[_HDFFile] = None
+        self._multiplier = 1
+
+    # Triggered on PCAP arm
+    async def open(self, multiplier: int = 1) -> Dict[str, DataKey]:
+        """Retrieve and get descriptor of all PandA signals marked for capture"""
+
+        # Get capture PVs by looking at panda. Gives mapping of dotted attribute path
+        # to Signal object
+        self.capture_signals = get_capture_signals(self.panda_device)
+
+        # Ensure flushes are immediate
+        await self.panda_device.data.flush_period.set(0)
+
+        to_capture = await get_signals_marked_for_capture(self.capture_signals)
+        self._file = None
+        info = self._directory_provider()
+        # Set the initial values
+        await asyncio.gather(
+            self.panda_device.data.hdf_directory.set(
+                str(info.root / info.resource_dir)
+            ),
+            self.panda_device.data.hdf_file_name.set(
+                f"{info.prefix}{self.panda_device.name}{info.suffix}.h5",
+            ),
+            self.panda_device.data.num_capture.set(0),
+        )
+
+        # Wait for it to start, stashing the status that tells us when it finishes
+        await self.panda_device.data.capture.set(True)
+        name = self._name_provider()
+        if multiplier > 1:
+            raise ValueError(
+                "All PandA datasets should be scalar, multiplier should be 1"
+            )
+        self._datasets = []
+        for attribute_path, capture_signal in to_capture.items():
+            split_path = attribute_path.split(".")
+            signal_name = split_path[-1]
+            # Get block names from numbered blocks, eg INENC[1]
+            block_name = (
+                f"{split_path[-3]}{split_path[-2]}"
+                if split_path[-2].isnumeric()
+                else split_path[-2]
+            )
+
+            for suffix in capture_signal.capture_type.split(" "):
+                self._datasets.append(
+                    _HDFDataset(
+                        name,
+                        block_name,
+                        f"{name}-{block_name}-{signal_name}-{suffix}",
+                        f"{block_name}-{signal_name}".upper() + f"-{suffix}",
+                        [1],
+                        multiplier=1,
+                    )
+                )
+
+        describe = {
+            ds.name: DataKey(
+                source=self.panda_device.data.hdf_directory.source,
+                shape=ds.shape,
+                dtype="array" if ds.shape != [1] else "number",
+                external="STREAM:",
+            )
+            for ds in self._datasets
+        }
+        return describe
+
+    # Next few functions are exactly the same as AD writer. Could move as default
+    # StandardDetector behavior
+    async def wait_for_index(
+        self, index: int, timeout: Optional[float] = DEFAULT_TIMEOUT
+    ):
+        def matcher(value: int) -> bool:
+            return value >= index
+
+        matcher.__name__ = f"index_at_least_{index}"
+        await wait_for_value(
+            self.panda_device.data.num_captured, matcher, timeout=timeout
+        )
+
+    async def get_indices_written(self) -> int:
+        return await self.panda_device.data.num_captured.get_value()
+
+    async def observe_indices_written(
+        self, timeout=DEFAULT_TIMEOUT
+    ) -> AsyncGenerator[int, None]:
+        """Wait until a specific index is ready to be collected"""
+        async for num_captured in observe_value(
+            self.panda_device.data.num_captured, timeout
+        ):
+            yield num_captured // self._multiplier
+
+    async def collect_stream_docs(
+        self, indices_written: int
+    ) -> AsyncIterator[StreamAsset]:
+        # TODO: fail if we get dropped frames
+        if indices_written:
+            if not self._file:
+                self._file = _HDFFile(
+                    self._directory_provider(),
+                    Path(await self.panda_device.data.hdf_file_name.get_value()),
+                    self._datasets,
+                )
+                for doc in self._file.stream_resources():
+                    yield "stream_resource", doc
+            for doc in self._file.stream_data(indices_written):
+                yield "stream_datum", doc
+
+    # Could put this function as default for StandardDetector
+    async def close(self):
+        await self.panda_device.data.capture.set(
+            False, wait=True, timeout=DEFAULT_TIMEOUT
+        )

ophyd_async/panda/writers/_panda_hdf_file.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, List
+
+from event_model import StreamDatum, StreamResource, compose_stream_resource
+
+from ophyd_async.core import DirectoryInfo
+
+
+@dataclass
+class _HDFDataset:
+    device_name: str
+    block: str
+    name: str
+    path: str
+    shape: List[int]
+    multiplier: int
+
+
+class _HDFFile:
+    def __init__(
+        self,
+        directory_info: DirectoryInfo,
+        full_file_name: Path,
+        datasets: List[_HDFDataset],
+    ) -> None:
+        self._last_emitted = 0
+        self._bundles = [
+            compose_stream_resource(
+                spec="AD_HDF5_SWMR_SLICE",
+                root=str(directory_info.root),
+                data_key=ds.name,
+                resource_path=(f"{str(directory_info.root)}/{full_file_name}"),
+                resource_kwargs={
+                    "name": ds.name,
+                    "block": ds.block,
+                    "path": ds.path,
+                    "multiplier": ds.multiplier,
+                    "timestamps": "/entry/instrument/NDAttributes/NDArrayTimeStamp",
+                },
+            )
+            for ds in datasets
+        ]
+
+    def stream_resources(self) -> Iterator[StreamResource]:
+        for bundle in self._bundles:
+            yield bundle.stream_resource_doc
+
+    def stream_data(self, indices_written: int) -> Iterator[StreamDatum]:
+        # Indices are relative to resource
+        if indices_written > self._last_emitted:
+            indices = {
+                "start": self._last_emitted,
+                "stop": indices_written,
+            }
+            self._last_emitted = indices_written
+            for bundle in self._bundles:
+                yield bundle.compose_stream_datum(indices)

ophyd_async/plan_stubs/__init__.py

@@ -0,0 +1,13 @@
+from .ensure_connected import ensure_connected
+from .fly import (
+    fly_and_collect,
+    prepare_static_seq_table_flyer_and_detectors_with_same_trigger,
+    time_resolved_fly_and_collect_with_static_seq_table,
+)
+
+__all__ = [
+    "fly_and_collect",
+    "prepare_static_seq_table_flyer_and_detectors_with_same_trigger",
+    "time_resolved_fly_and_collect_with_static_seq_table",
+    "ensure_connected",
+]

ophyd_async/plan_stubs/ensure_connected.py

@@ -0,0 +1,22 @@
+import bluesky.plan_stubs as bps
+
+from ophyd_async.core.device import Device
+from ophyd_async.core.utils import DEFAULT_TIMEOUT, wait_for_connection
+
+
+def ensure_connected(
+    *devices: Device,
+    mock: bool = False,
+    timeout: float = DEFAULT_TIMEOUT,
+    force_reconnect=False,
+):
+    yield from bps.wait_for(
+        [
+            lambda: wait_for_connection(
+                **{
+                    device.name: device.connect(mock, timeout, force_reconnect)
+                    for device in devices
+                }
+            )
+        ]
+    )

ophyd_async/plan_stubs/fly.py

@@ -0,0 +1,149 @@
+from typing import List
+
+import bluesky.plan_stubs as bps
+from bluesky.utils import short_uid
+
+from ophyd_async.core.detector import DetectorTrigger, StandardDetector, TriggerInfo
+from ophyd_async.core.flyer import HardwareTriggeredFlyable
+from ophyd_async.core.utils import in_micros
+from ophyd_async.panda._table import SeqTable, SeqTableRow, seq_table_from_rows
+from ophyd_async.panda._trigger import SeqTableInfo
+
+
+def prepare_static_seq_table_flyer_and_detectors_with_same_trigger(
+    flyer: HardwareTriggeredFlyable[SeqTableInfo],
+    detectors: List[StandardDetector],
+    number_of_frames: int,
+    exposure: float,
+    shutter_time: float,
+    repeats: int = 1,
+    period: float = 0.0,
+):
+    """Prepare a hardware triggered flyable and one or more detectors.
+
+    Prepare a hardware triggered flyable and one or more detectors with the
+    same trigger. This method constructs TriggerInfo and a static sequence
+    table from required parameters. The table is required to prepare the flyer,
+    and the TriggerInfo is required to prepare the detector(s).
+
+    This prepares all supplied detectors with the same trigger.
+
+    """
+    if not detectors:
+        raise ValueError("No detectors provided. There must be at least one.")
+
+    deadtime = max(det.controller.get_deadtime(exposure) for det in detectors)
+
+    trigger_info = TriggerInfo(
+        num=number_of_frames * repeats,
+        trigger=DetectorTrigger.constant_gate,
+        deadtime=deadtime,
+        livetime=exposure,
+    )
+    trigger_time = number_of_frames * (exposure + deadtime)
+    pre_delay = max(period - 2 * shutter_time - trigger_time, 0)
+
+    table: SeqTable = seq_table_from_rows(
+        # Wait for pre-delay then open shutter
+        SeqTableRow(
+            time1=in_micros(pre_delay),
+            time2=in_micros(shutter_time),
+            outa2=True,
+        ),
+        # Keeping shutter open, do N triggers
+        SeqTableRow(
+            repeats=number_of_frames,
+            time1=in_micros(exposure),
+            outa1=True,
+            outb1=True,
+            time2=in_micros(deadtime),
+            outa2=True,
+        ),
+        # Add the shutter close
+        SeqTableRow(time2=in_micros(shutter_time)),
+    )
+
+    table_info = SeqTableInfo(table, repeats)
+
+    for det in detectors:
+        yield from bps.prepare(det, trigger_info, wait=False, group="prep")
+    yield from bps.prepare(flyer, table_info, wait=False, group="prep")
+    yield from bps.wait(group="prep")
+
+
+def fly_and_collect(
+    stream_name: str,
+    flyer: HardwareTriggeredFlyable[SeqTableInfo],
+    detectors: List[StandardDetector],
+):
+    """Kickoff, complete and collect with a flyer and multiple detectors.
+
+    This stub takes a flyer and one or more detectors that have been prepared. It
+    declares a stream for the detectors, then kicks off the detectors and the flyer.
+    The detectors are collected until the flyer and detectors have completed.
+
+    """
+    yield from bps.declare_stream(*detectors, name=stream_name, collect=True)
+    yield from bps.kickoff(flyer, wait=True)
+    for detector in detectors:
+        yield from bps.kickoff(detector)
+
+    # collect_while_completing
+    group = short_uid(label="complete")
+
+    yield from bps.complete(flyer, wait=False, group=group)
+    for detector in detectors:
+        yield from bps.complete(detector, wait=False, group=group)
+
+    done = False
+    while not done:
+        try:
+            yield from bps.wait(group=group, timeout=0.5)
+        except TimeoutError:
+            pass
+        else:
+            done = True
+        yield from bps.collect(
+            *detectors,
+            return_payload=False,
+            name=stream_name,
+        )
+    yield from bps.wait(group=group)
+
+
+def time_resolved_fly_and_collect_with_static_seq_table(
+    stream_name: str,
+    flyer: HardwareTriggeredFlyable[SeqTableInfo],
+    detectors: List[StandardDetector],
+    number_of_frames: int,
+    exposure: float,
+    shutter_time: float,
+    repeats: int = 1,
+    period: float = 0.0,
+):
+    """Run a scan wth a flyer and multiple detectors.
+
+    The stub demonstrates the standard basic flow for a flyscan:
+
+    - Prepare the flyer and detectors with a trigger
+    - Fly and collect:
+       - Declare the stream and kickoff the scan
+       - Collect while completing
+
+    This needs to be used in a plan that instantates detectors and a flyer,
+    stages/unstages the devices, and opens and closes the run.
+
+    """
+
+    # Set up scan and prepare trigger
+    yield from prepare_static_seq_table_flyer_and_detectors_with_same_trigger(
+        flyer,
+        detectors,
+        number_of_frames=number_of_frames,
+        exposure=exposure,
+        shutter_time=shutter_time,
+        repeats=repeats,
+        period=period,
+    )
+    # Run the fly scan
+    yield from fly_and_collect(stream_name, flyer, detectors)

ophyd_async/protocols.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Generic,
+    Protocol,
+    TypeVar,
+    runtime_checkable,
+)
+
+from bluesky.protocols import DataKey, HasName, Reading
+
+if TYPE_CHECKING:
+    from ophyd_async.core.async_status import AsyncStatus
+
+
+@runtime_checkable
+class AsyncReadable(HasName, Protocol):
+    @abstractmethod
+    async def read(self) -> Dict[str, Reading]:
+        """Return an OrderedDict mapping string field name(s) to dictionaries
+        of values and timestamps and optional per-point metadata.
+
+        Example return value:
+
+        .. code-block:: python
+
+            OrderedDict(('channel1',
+                         {'value': 5, 'timestamp': 1472493713.271991}),
+                         ('channel2',
+                         {'value': 16, 'timestamp': 1472493713.539238}))
+        """
+        ...
+
+    @abstractmethod
+    async def describe(self) -> Dict[str, DataKey]:
+        """Return an OrderedDict with exactly the same keys as the ``read``
+        method, here mapped to per-scan metadata about each field.
+
+        Example return value:
+
+        .. code-block:: python
+
+            OrderedDict(('channel1',
+                         {'source': 'XF23-ID:SOME_PV_NAME',
+                          'dtype': 'number',
+                          'shape': []}),
+                        ('channel2',
+                         {'source': 'XF23-ID:SOME_PV_NAME',
+                          'dtype': 'number',
+                          'shape': []}))
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncConfigurable(Protocol):
+    @abstractmethod
+    async def read_configuration(self) -> Dict[str, Reading]:
+        """Same API as ``read`` but for slow-changing fields related to configuration.
+        e.g., exposure time. These will typically be read only once per run.
+        """
+        ...
+
+    @abstractmethod
+    async def describe_configuration(self) -> Dict[str, DataKey]:
+        """Same API as ``describe``, but corresponding to the keys in
+        ``read_configuration``.
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncPausable(Protocol):
+    @abstractmethod
+    async def pause(self) -> None:
+        """Perform device-specific work when the RunEngine pauses."""
+        ...
+
+    @abstractmethod
+    async def resume(self) -> None:
+        """Perform device-specific work when the RunEngine resumes after a pause."""
+        ...
+
+
+@runtime_checkable
+class AsyncStageable(Protocol):
+    @abstractmethod
+    def stage(self) -> AsyncStatus:
+        """An optional hook for "setting up" the device for acquisition.
+
+        It should return a ``Status`` that is marked done when the device is
+        done staging.
+        """
+        ...
+
+    @abstractmethod
+    def unstage(self) -> AsyncStatus:
+        """A hook for "cleaning up" the device after acquisition.
+
+        It should return a ``Status`` that is marked done when the device is finished
+        unstaging.
+        """
+        ...
+
+
+C = TypeVar("C", contravariant=True)
+
+
+class Watcher(Protocol, Generic[C]):
+    @staticmethod
+    def __call__(
+        *,
+        current: C,
+        initial: C,
+        target: C,
+        name: str | None,
+        unit: str | None,
+        precision: float | None,
+        fraction: float | None,
+        time_elapsed: float | None,
+        time_remaining: float | None,
+    ) -> Any: ...