dls-dodal 1.31.1__tar.gz → 1.33.0__tar.gz

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dls-dodal
-Version: 1.31.1
+Version: 1.33.0
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async>=0.5.2
+Requires-Dist: ophyd-async<0.7,>=0.6
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json
@@ -232,6 +232,7 @@ Requires-Dist: numpy<2.0
 Requires-Dist: aiofiles
 Requires-Dist: aiohttp
 Requires-Dist: redis
+Requires-Dist: deepdiff
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: diff-cover; extra == "dev"

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/docs/reference/device-standards.rst

@@ -21,6 +21,17 @@ should think about where to place them in the following order:
 
 This is in an effort to avoid duplication across facilities/beamlines. 
 
+Device Best Practices
+----------------------------
+
+Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
+should a given device implement. In addition to this the following guidelines are strongly recommended:
+
+#. Devices should contain only the PV suffixes that are generic for any instance of the device. See `PV Suffixes`_
+#. Anything in a device that is expected to be set externally should be a signal. See `Use of signals`_
+#. Devices should not hold state, when they are read they should read the hardware. See `Holding State`_
+
+
 PV Suffixes
 -----------
 
@@ -86,16 +97,78 @@ Instead you should make a soft signal:
     
     class MyDevice(Device):
         def __init__(self):
-             self.param = create_soft_signal(str, "", self.name)
+             self.param = soft_signal_rw(str)
     
     my_device = MyDevice()
     def my_plan():
         yield from bps.mv(my_device.param, "new_value")
 
-Ophyd Devices best practices
-----------------------------
 
-Ophyd-async directory contains a flowchart_ for a simplified decision tree about what interfaces
-should a given device implement.
+Holding State
+-------------
+
+Devices should avoid holding state as much as possible. Ophyd devices are mostly trying to reflect the state of hardware and so when the device is read that hardware should be read.
+
+If the device holds the state itself it is likely to not reflect the real hardware if:
+* The device has just been initialised
+* The hardware has changed independently e.g. via EPICS directly
+* The hardware has failed to do what the device expected
+
+For example, if I have a device that I would like to treat as moving in/out based on an underlying axis then it would be incorrect to implement it like this:
+
+.. code-block:: python
+
+    class InOut(Enum):
+        IN = 0
+        OUT = 0
+
+    class MyDevice(Device):
+        def __init__(self):
+            self.underlying_motor = Motor("MOTOR")
+            with self.add_children_as_readables():
+                self.in_out, self._in_out_setter = soft_signal_r_and_setter(InOut)
+                
+
+        @AsyncStatus.wrap
+        async def set(self, value: InOut):
+            if value == InOut.IN:
+                await self.underlying_motor.set(100)
+            else:
+                await self.underlying_motor.set(0)
+            self._in_out_setter(value)
+
+While this may appear to work fine during normal operation the state of in_out is only ever updated if the ophyd device is set. It is incorrect to assume that underlying_motor only changes
+based on this and so this has the issues listed above. Instead you should make sure to update in_out whenever the device is read e.g.
+
+.. code-block:: python
+
+    class InOut(Enum):
+        IN = 0
+        OUT = 0
+
+    class MyDevice(Device):
+        def __init__(self):
+            self.underlying_motor = Motor("MOTOR")
+            with self.add_children_as_readables():
+                self.in_out = create_hardware_backed_soft_signal(InOut, self._get_in_out_from_hardware)
+                
+        async def _get_in_out_from_hardware(self):
+            current_position = await self.underlying_motor.get_value()
+            if isclose(current_position, 0):
+                return InOut.IN
+            elif isclose(current_position, 100):
+                return InOut.OUT
+            else:
+                raise ValueError()
+
+
+        @AsyncStatus.wrap
+        async def set(self, value: InOut):
+            if value == InOut.IN:
+                await self.underlying_motor.set(100)
+            else:
+                await self.underlying_motor.set(0)
+
+This will be simplified by https://github.com/bluesky/ophyd-async/issues/525
 
 .. _flowchart: https://blueskyproject.io/ophyd-async/main/how-to/choose-interfaces-for-devices.html

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/pull_request_template.md

@@ -6,6 +6,6 @@ Fixes #ISSUE
 
 ### Checks for reviewer
 - [ ] Would the PR title make sense to a scientist on a set of release notes
-- [ ] If a new device has been added does it follow the [standards](https://github.com/DiamondLightSource/dodal/wiki/Device-Standards)
+- [ ] If a new device has been added does it follow the [standards](https://diamondlightsource.github.io/dodal/main/reference/device-standards.html)
 - [ ] If changing the API for a pre-existing device, ensure that any beamlines using this device have updated their Bluesky plans accordingly
 - [ ] Have the connection tests for the relevant beamline(s) been run via `dodal connect ${BEAMLINE}`

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/pyproject.toml

@@ -15,7 +15,7 @@ description = "Ophyd devices and other utils that could be used across DLS beaml
 dependencies = [
     "click",
     "ophyd",
-    "ophyd-async>=0.5.2",
+    "ophyd-async>=0.6,<0.7",
     "bluesky",
     "pyepics",
     "dataclasses-json",
@@ -31,6 +31,7 @@ dependencies = [
     "aiofiles",
     "aiohttp",
     "redis",
+    "deepdiff",
 ]
 
 dynamic = ["version"]

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dls_dodal.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dls-dodal
-Version: 1.31.1
+Version: 1.33.0
 Summary: Ophyd devices and other utils that could be used across DLS beamlines
 Author-email: Dominic Oram <dominic.oram@diamond.ac.uk>
 License:                                  Apache License
@@ -216,7 +216,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click
 Requires-Dist: ophyd
-Requires-Dist: ophyd-async>=0.5.2
+Requires-Dist: ophyd-async<0.7,>=0.6
 Requires-Dist: bluesky
 Requires-Dist: pyepics
 Requires-Dist: dataclasses-json
@@ -232,6 +232,7 @@ Requires-Dist: numpy<2.0
 Requires-Dist: aiofiles
 Requires-Dist: aiohttp
 Requires-Dist: redis
+Requires-Dist: deepdiff
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: diff-cover; extra == "dev"

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dls_dodal.egg-info/SOURCES.txt

@@ -82,6 +82,7 @@ src/dodal/beamline_specific_utils/__init__.py
 src/dodal/beamline_specific_utils/i03.py
 src/dodal/beamlines/README.md
 src/dodal/beamlines/__init__.py
+src/dodal/beamlines/b01_1.py
 src/dodal/beamlines/i03.py
 src/dodal/beamlines/i04.py
 src/dodal/beamlines/i04_1.py
@@ -97,6 +98,7 @@ src/dodal/beamlines/training_rig.py
 src/dodal/common/__init__.py
 src/dodal/common/coordination.py
 src/dodal/common/maths.py
+src/dodal/common/signal_utils.py
 src/dodal/common/types.py
 src/dodal/common/udc_directory_provider.py
 src/dodal/common/visit.py
@@ -321,6 +323,8 @@ tests/test_data/test_beamline_parameters.txt
 tests/test_data/test_det_dist_converter.txt
 tests/test_data/topup_long_delay.txt
 tests/test_data/topup_short_params.txt
+tests/test_data/test_images/oav_snapshot_expected.png
+tests/test_data/test_images/oav_snapshot_test.png
 tests/unit_tests/__init__.py
 tests/unit_tests/test_cli.py
 tests/unit_tests/test_log.py

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dls_dodal.egg-info/requires.txt

@@ -1,6 +1,6 @@
 click
 ophyd
-ophyd-async>=0.5.2
+ophyd-async<0.7,>=0.6
 bluesky
 pyepics
 dataclasses-json
@@ -16,6 +16,7 @@ numpy<2.0
 aiofiles
 aiohttp
 redis
+deepdiff
 
 [dev]
 black

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '1.31.1'
-__version_tuple__ = version_tuple = (1, 31, 1)
+__version__ = version = '1.33.0'
+__version_tuple__ = version_tuple = (1, 33, 0)

dls_dodal-1.33.0/src/dodal/beamlines/b01_1.py

@@ -0,0 +1,77 @@
+from pathlib import Path
+
+from ophyd_async.epics.adaravis import AravisDetector
+from ophyd_async.fastcs.panda import HDFPanda
+
+from dodal.common.beamlines.beamline_utils import (
+    device_instantiation,
+    get_path_provider,
+    set_path_provider,
+)
+from dodal.common.beamlines.beamline_utils import set_beamline as set_utils_beamline
+from dodal.common.visit import LocalDirectoryServiceClient, StaticVisitPathProvider
+from dodal.devices.synchrotron import Synchrotron
+from dodal.log import set_beamline as set_log_beamline
+
+BL = "c01"
+set_log_beamline(BL)
+set_utils_beamline(BL)
+
+set_path_provider(
+    StaticVisitPathProvider(
+        BL,
+        Path("/dls/b01-1/data/"),
+        client=LocalDirectoryServiceClient(),
+    )
+)
+
+"""
+NOTE: Due to ArgoCD and the k8s cluster configuration those PVs are not available remotely.
+You need to be on the beamline-local network to access them.
+The simplest way to do this is to `ssh b01-1-ws001` and run `dodal connect b01_1` from there.
+remember about the underscore in the beamline name.
+
+See the IOC status here:
+https://argocd.diamond.ac.uk/applications?showFavorites=false&proj=&sync=&autoSync=&health=&namespace=&cluster=&labels=
+"""
+
+
+def panda(
+    wait_for_connection: bool = True, fake_with_ophyd_sim: bool = False
+) -> HDFPanda:
+    return device_instantiation(
+        device_factory=HDFPanda,
+        name="panda",
+        prefix="-EA-PANDA-01:",
+        wait=wait_for_connection,
+        fake=fake_with_ophyd_sim,
+        path_provider=get_path_provider(),
+    )
+
+
+def synchrotron(
+    wait_for_connection: bool = True, fake_with_ophyd_sim: bool = False
+) -> Synchrotron:
+    return device_instantiation(
+        Synchrotron,
+        "synchrotron",
+        "",
+        wait_for_connection,
+        fake_with_ophyd_sim,
+        bl_prefix=False,
+    )
+
+
+def manta(
+    wait_for_connection: bool = True, fake_with_ophyd_sim: bool = False
+) -> AravisDetector:
+    return device_instantiation(
+        AravisDetector,
+        "manta",
+        "-DI-DCAM-02:",
+        wait_for_connection,
+        fake_with_ophyd_sim,
+        path_provider=get_path_provider(),
+        drv_suffix="CAM:",
+        hdf_suffix="HDF5:",
+    )

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/beamlines/i04.py

@@ -308,6 +308,7 @@ def undulator(
         wait_for_connection,
         fake_with_ophyd_sim,
         bl_prefix=False,
+        id_gap_lookup_table_path="/dls_sw/i04/software/gda/config/lookupTables/BeamLine_Undulator_toGap.txt",
     )
 
 

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/beamlines/i22.py

@@ -199,6 +199,7 @@ def undulator(
         bl_prefix=False,
         poles=80,
         length=2.0,
+        id_gap_lookup_table_path="/dls_sw/i22/software/daq_configuration/lookup/BeamLine_Undulator_toGap.txt",
     )
 
 

dls_dodal-1.33.0/src/dodal/common/signal_utils.py

@@ -0,0 +1,53 @@
+from collections.abc import Callable, Coroutine
+from typing import Any, TypeVar
+
+from bluesky.protocols import Reading
+from ophyd_async.core import SignalR, SoftSignalBackend
+from ophyd_async.core._soft_signal_backend import SignalMetadata
+
+T = TypeVar("T")
+
+
+class HarwareBackedSoftSignalBackend(SoftSignalBackend[T]):
+    def __init__(
+        self,
+        get_from_hardware_func: Callable[[], Coroutine[Any, Any, T]],
+        *args,
+        **kwargs,
+    ) -> None:
+        self.get_from_hardware_func = get_from_hardware_func
+        super().__init__(*args, **kwargs)
+
+    async def _update_value(self):
+        new_value = await self.get_from_hardware_func()
+        await self.put(new_value)
+
+    async def get_reading(self) -> Reading:
+        await self._update_value()
+        return await super().get_reading()
+
+    async def get_value(self) -> T:
+        await self._update_value()
+        return await super().get_value()
+
+
+def create_hardware_backed_soft_signal(
+    datatype: type[T],
+    get_from_hardware_func: Callable[[], Coroutine[Any, Any, T]],
+    units: str | None = None,
+    precision: int | None = None,
+):
+    """Creates a soft signal that, when read will call the function passed into
+    `get_from_hardware_func` and return this.
+
+    This will allow you to make soft signals derived from arbitrary hardware signals.
+    However, calling subscribe on this signal does not give you a sensible value and
+    the signal is currently read only. See https://github.com/bluesky/ophyd-async/issues/525
+    for a more full solution.
+    """
+    metadata = SignalMetadata(units=units, precision=precision)
+    return SignalR(
+        backend=HarwareBackedSoftSignalBackend(
+            get_from_hardware_func, datatype, metadata=metadata
+        )
+    )

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/devices/aperturescatterguard.py

@@ -8,11 +8,11 @@ from ophyd_async.core import (
     AsyncStatus,
     HintedSignal,
     StandardReadable,
-    soft_signal_rw,
 )
 from pydantic import BaseModel, Field
 
 from dodal.common.beamlines.beamline_parameters import GDABeamlineParameters
+from dodal.common.signal_utils import create_hardware_backed_soft_signal
 from dodal.devices.aperture import Aperture
 from dodal.devices.scatterguard import Scatterguard
 
@@ -105,7 +105,9 @@ class ApertureScatterguard(StandardReadable, Movable):
     ) -> None:
         self.aperture = Aperture(prefix + "-MO-MAPT-01:")
         self.scatterguard = Scatterguard(prefix + "-MO-SCAT-01:")
-        self.radius = soft_signal_rw(float, units="µm")
+        self.radius = create_hardware_backed_soft_signal(
+            float, self._get_current_radius, units="µm"
+        )
         self._loaded_positions = loaded_positions
         self._tolerances = tolerances
         self.add_readables(
@@ -119,7 +121,9 @@ class ApertureScatterguard(StandardReadable, Movable):
             ],
         )
         with self.add_children_as_readables(HintedSignal):
-            self.selected_aperture = soft_signal_rw(ApertureValue)
+            self.selected_aperture = create_hardware_backed_soft_signal(
+                ApertureValue, self._get_current_aperture_position
+            )
 
         super().__init__(name)
 
@@ -136,9 +140,6 @@ class ApertureScatterguard(StandardReadable, Movable):
     @AsyncStatus.wrap
     async def _set_raw_unsafe(self, position: AperturePosition):
         """Accept the risks and move in an unsafe way. Collisions possible."""
-        if position.radius is not None:
-            await self.radius.set(position.radius)
-
         aperture_x, aperture_y, aperture_z, scatterguard_x, scatterguard_y = (
             position.values
         )
@@ -150,13 +151,8 @@ class ApertureScatterguard(StandardReadable, Movable):
             self.scatterguard.x.set(scatterguard_x),
             self.scatterguard.y.set(scatterguard_y),
         )
-        try:
-            value = await self.get_current_aperture_position()
-            self.selected_aperture.set(value)
-        except InvalidApertureMove:
-            self.selected_aperture.set(None)  # type: ignore
 
-    async def get_current_aperture_position(self) -> ApertureValue:
+    async def _get_current_aperture_position(self) -> ApertureValue:
         """
         Returns the current aperture position using readback values
         for SMALL, MEDIUM, LARGE. ROBOT_LOAD position defined when
@@ -176,6 +172,10 @@ class ApertureScatterguard(StandardReadable, Movable):
 
         raise InvalidApertureMove("Current aperture/scatterguard state unrecognised")
 
+    async def _get_current_radius(self) -> float | None:
+        current_value = await self._get_current_aperture_position()
+        return self._loaded_positions[current_value].radius
+
     async def _safe_move_within_datacollection_range(
         self, position: AperturePosition, value: ApertureValue
     ):
@@ -203,8 +203,6 @@ class ApertureScatterguard(StandardReadable, Movable):
             )
 
         current_ap_y = await self.aperture.y.user_readback.get_value()
-        if position.radius is not None:
-            await self.radius.set(position.radius)
 
         aperture_x, aperture_y, aperture_z, scatterguard_x, scatterguard_y = (
             position.values
@@ -220,15 +218,14 @@ class ApertureScatterguard(StandardReadable, Movable):
                 self.aperture.y.set(aperture_y),
                 self.aperture.z.set(aperture_z),
             )
-            return
-        await asyncio.gather(
-            self.aperture.x.set(aperture_x),
-            self.aperture.y.set(aperture_y),
-            self.aperture.z.set(aperture_z),
-        )
+        else:
+            await asyncio.gather(
+                self.aperture.x.set(aperture_x),
+                self.aperture.y.set(aperture_y),
+                self.aperture.z.set(aperture_z),
+            )
 
-        await asyncio.gather(
-            self.scatterguard.x.set(scatterguard_x),
-            self.scatterguard.y.set(scatterguard_y),
-        )
-        await self.selected_aperture.set(value)
+            await asyncio.gather(
+                self.scatterguard.x.set(scatterguard_x),
+                self.scatterguard.y.set(scatterguard_y),
+            )

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/devices/areadetector/plugins/MJPG.py

@@ -87,11 +87,12 @@ class MJPG(Device, ABC):
 
 
 class SnapshotWithBeamCentre(MJPG):
-    """A child of MJPG which, when triggered, draws a crosshair at the beam centre in the
-    image and saves the image to disk."""
+    """A child of MJPG which, when triggered, draws an outlined crosshair at the beam
+    centre in the image and saves the image to disk."""
 
     CROSSHAIR_LENGTH_PX = 20
-    CROSSHAIR_COLOUR = "Blue"
+    CROSSHAIR_OUTLINE_COLOUR = "Black"
+    CROSSHAIR_FILL_COLOUR = "White"
 
     def post_processing(self, image: Image.Image):
         assert (
@@ -100,15 +101,38 @@ class SnapshotWithBeamCentre(MJPG):
         beam_x = self.oav_params.beam_centre_i
         beam_y = self.oav_params.beam_centre_j
 
+        SnapshotWithBeamCentre.draw_crosshair(image, beam_x, beam_y)
+
+        self._save_image(image)
+
+    @classmethod
+    def draw_crosshair(cls, image: Image.Image, beam_x: int, beam_y: int):
         draw = ImageDraw.Draw(image)
-        HALF_LEN = self.CROSSHAIR_LENGTH_PX / 2
+        OUTLINE_WIDTH = 1
+        HALF_LEN = cls.CROSSHAIR_LENGTH_PX / 2
+        draw.rectangle(
+            [
+                beam_x - OUTLINE_WIDTH,
+                beam_y - HALF_LEN - OUTLINE_WIDTH,
+                beam_x + OUTLINE_WIDTH,
+                beam_y + HALF_LEN + OUTLINE_WIDTH,
+            ],
+            fill=cls.CROSSHAIR_OUTLINE_COLOUR,
+        )
+        draw.rectangle(
+            [
+                beam_x - HALF_LEN - OUTLINE_WIDTH,
+                beam_y - OUTLINE_WIDTH,
+                beam_x + HALF_LEN + OUTLINE_WIDTH,
+                beam_y + OUTLINE_WIDTH,
+            ],
+            fill=cls.CROSSHAIR_OUTLINE_COLOUR,
+        )
         draw.line(
             ((beam_x, beam_y - HALF_LEN), (beam_x, beam_y + HALF_LEN)),
-            fill=self.CROSSHAIR_COLOUR,
+            fill=cls.CROSSHAIR_FILL_COLOUR,
         )
         draw.line(
             ((beam_x - HALF_LEN, beam_y), (beam_x + HALF_LEN, beam_y)),
-            fill=self.CROSSHAIR_COLOUR,
+            fill=cls.CROSSHAIR_FILL_COLOUR,
         )
-
-        self._save_image(image)

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/devices/fast_grid_scan.py

@@ -3,6 +3,7 @@ from typing import Generic, TypeVar
 
 import numpy as np
 from bluesky.plan_stubs import mv
+from bluesky.protocols import Flyable
 from numpy import ndarray
 from ophyd_async.core import (
     AsyncStatus,
@@ -193,7 +194,7 @@ class ExpectedImages(SignalR[int]):
         return first_grid + second_grid
 
 
-class FastGridScanCommon(StandardReadable, ABC, Generic[ParamType]):
+class FastGridScanCommon(StandardReadable, Flyable, ABC, Generic[ParamType]):
     """Device for a general fast grid scan
 
     When the motion program is started, the goniometer will move in a snake-like grid trajectory,

{dls_dodal-1.31.1 → dls_dodal-1.33.0}/src/dodal/devices/focusing_mirror.py

@@ -76,7 +76,7 @@ class MirrorVoltageDevice(Device):
             LOGGER.debug(f"{setpoint_v.name} already at {value} - skipping set")
             return
 
-        LOGGER.debug(f"setting {setpoint_v.name} to {value}")
+        LOGGER.debug(f"Setting {setpoint_v.name} to {value}")
 
         # Register an observer up front to ensure we don't miss events after we
         # perform the set
@@ -85,16 +85,14 @@ class MirrorVoltageDevice(Device):
         )
         # discard the current value (OK) so we can await a subsequent change
         await anext(demand_accepted_iterator)
-        await setpoint_v.set(value)
+        set_status = setpoint_v.set(value, wait=False)
 
         # The set should always change to SLEW regardless of whether we are
         # already at the set point, then change back to OK/FAIL depending on
         # success
         accepted_value = await anext(demand_accepted_iterator)
         assert accepted_value == MirrorVoltageDemand.SLEW
-        LOGGER.debug(
-            f"Demand not accepted for {setpoint_v.name}, waiting for acceptance..."
-        )
+        LOGGER.debug(f"Waiting for {setpoint_v.name} to set")
         while MirrorVoltageDemand.SLEW == (
             accepted_value := await anext(demand_accepted_iterator)
         ):
@@ -104,6 +102,7 @@ class MirrorVoltageDevice(Device):
             raise AssertionError(
                 f"Voltage slew failed for {setpoint_v.name}, new state={accepted_value}"
             )
+        await set_status
 
 
 class VFMMirrorVoltages(StandardReadable):