dls-dodal 1.36.3__py3-none-any.whl → 1.38.0__py3-none-any.whl

dodal/devices/{zebra.py → zebra/zebra.py}

@@ -14,37 +14,7 @@ from ophyd_async.core import (
 )
 from ophyd_async.epics.core import epics_signal_r, epics_signal_rw
 
-# These constants refer to I03's Zebra. See https://github.com/DiamondLightSource/dodal/issues/772
-# Sources
-DISCONNECT = 0
-IN1_TTL = 1
-IN2_TTL = 4
-IN3_TTL = 7
-IN4_TTL = 10
-PC_ARM = 29
-PC_GATE = 30
-PC_PULSE = 31
-AND3 = 34
-AND4 = 35
-OR1 = 36
-PULSE1 = 52
-PULSE2 = 53
-SOFT_IN1 = 60
-SOFT_IN2 = 61
-SOFT_IN3 = 62
-
-# Instrument specific
-TTL_DETECTOR = 1
-TTL_SHUTTER = 2
-TTL_XSPRESS3 = 3
-TTL_PANDA = 4
-
-# The AND gate that controls the automatic shutter
-AUTO_SHUTTER_GATE = 2
-
-# The first two inputs of the auto shutter gate.
-AUTO_SHUTTER_INPUT_1 = 1
-AUTO_SHUTTER_INPUT_2 = 2
+from dodal.devices.zebra.zebra_constants_mapping import ZebraMapping
 
 
 class ArmSource(StrictEnum):
@@ -81,6 +51,11 @@ class I24Axes:
 
 
 class RotationDirection(StrictEnum):
+    """
+    Defines for a swept angle whether the scan width (sweep) is to be added or subtracted from
+    the initial angle to obtain the final angle.
+    """
+
     POSITIVE = "Positive"
     NEGATIVE = "Negative"
 
@@ -281,7 +256,7 @@ class LogicGateConfiguration:
         for input, (source, invert) in enumerate(
             zip(self.sources, self.invert, strict=False)
         ):
-            input_strings.append(f"INP{input+1}={'!' if invert else ''}{source}")
+            input_strings.append(f"INP{input + 1}={'!' if invert else ''}{source}")
 
         return ", ".join(input_strings)
 
@@ -298,7 +273,8 @@ class SoftInputs(StandardReadable):
 class Zebra(StandardReadable):
     """The Zebra device."""
 
-    def __init__(self, name: str, prefix: str) -> None:
+    def __init__(self, mapping: ZebraMapping, name: str, prefix: str) -> None:
+        self.mapping = mapping
         self.pc = PositionCompare(prefix, name)
         self.output = ZebraOutputPanel(prefix, name)
         self.inputs = SoftInputs(prefix, name)

dodal/devices/zebra/zebra_constants_mapping.py

@@ -0,0 +1,96 @@
+from collections import Counter
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class ZebraMappingValidations(BaseModel):
+    """Raises an exception if field set to -1 is accessed, and validate against
+    multiple fields mapping to the same integer"""
+
+    def __getattribute__(self, name: str):
+        """To protect against mismatch between the Zebra configuration that a plan expects and the Zebra which has
+        been instantiated, raise exception if a field which has been set to -1 is accessed."""
+        value = object.__getattribute__(self, name)
+        if not name.startswith("__"):
+            if value == -1:
+                raise UnmappedZebraException(
+                    f"'{type(self).__name__}.{name}' was accessed but is set to -1. Please check the zebra mappings against the zebra's physical configuration"
+                )
+        return value
+
+    @model_validator(mode="after")
+    def ensure_no_duplicate_connections(self):
+        """Check that TTL outputs and sources are mapped to unique integers"""
+
+        integer_fields = {
+            key: value
+            for key, value in self.model_dump().items()
+            if isinstance(value, int) and value != -1
+        }
+        counted_vals = Counter(integer_fields.values())
+        integer_fields_with_duplicates = {
+            k: v for k, v in integer_fields.items() if counted_vals[v] > 1
+        }
+        if len(integer_fields_with_duplicates):
+            raise ValueError(
+                f"Each field in {type(self)} must be mapped to a unique integer. Duplicate fields: {integer_fields_with_duplicates}"
+            )
+        return self
+
+
+class ZebraTTLOutputs(ZebraMappingValidations):
+    """Maps hardware to the Zebra TTL output (1-4) that they're physically wired to, or
+    None if that hardware is not connected. A value of -1 means this hardware is not connected."""
+
+    TTL_EIGER: int = Field(default=-1, ge=-1, le=4)
+    TTL_PILATUS: int = Field(default=-1, ge=-1, le=4)
+    TTL_FAST_SHUTTER: int = Field(default=-1, ge=-1, le=4)
+    TTL_DETECTOR: int = Field(default=-1, ge=-1, le=4)
+    TTL_SHUTTER: int = Field(default=-1, ge=-1, le=4)
+    TTL_XSPRESS3: int = Field(default=-1, ge=-1, le=4)
+    TTL_PANDA: int = Field(default=-1, ge=-1, le=4)
+
+
+class ZebraSources(ZebraMappingValidations):
+    """Maps internal Zebra signal source to their integer PV value"""
+
+    DISCONNECT: int = Field(default=0, ge=0, le=63)
+    IN1_TTL: int = Field(default=1, ge=0, le=63)
+    IN2_TTL: int = Field(default=63, ge=0, le=63)
+    IN3_TTL: int = Field(default=7, ge=0, le=63)
+    IN4_TTL: int = Field(default=10, ge=0, le=63)
+    PC_ARM: int = Field(default=29, ge=0, le=63)
+    PC_GATE: int = Field(default=30, ge=0, le=63)
+    PC_PULSE: int = Field(default=31, ge=0, le=63)
+    AND3: int = Field(default=34, ge=0, le=63)
+    AND4: int = Field(default=35, ge=0, le=63)
+    OR1: int = Field(default=36, ge=0, le=63)
+    PULSE1: int = Field(default=52, ge=0, le=63)
+    PULSE2: int = Field(default=53, ge=0, le=63)
+    SOFT_IN1: int = Field(default=60, ge=0, le=63)
+    SOFT_IN2: int = Field(default=61, ge=0, le=63)
+    SOFT_IN3: int = Field(default=62, ge=0, le=63)
+
+
+class ZebraMapping(ZebraMappingValidations):
+    """Mappings to locate a Zebra device's Ophyd signals based on a specific
+    Zebra's hardware configuration and wiring.
+    """
+
+    # Zebra ophyd signal for connection can be accessed
+    # with, eg, zebra.output.out_pvs[zebra.mapping.outputs.TTL_DETECTOR]
+    outputs: ZebraTTLOutputs = ZebraTTLOutputs()
+
+    # Zebra ophyd signal sources can be mapped to a zebra output by doing, eg,
+    # bps.abs_set(zebra.output.out_pvs[zebra.mapping.outputs.TTL_DETECTOR],
+    # zebra.mapping.sources.AND3)
+    sources: ZebraSources = ZebraSources()
+
+    # Which of the Zebra's four AND gates is used to control the automatic shutter, if it's being used.
+    # After defining, the correct GateControl device can be accessed with, eg,
+    # zebra.logic_gates.and_gates[zebra.mapping.AND_GATE_FOR_AUTO_SHUTTER]. Set to -1 if not being used.
+    AND_GATE_FOR_AUTO_SHUTTER: int = Field(default=-1, ge=-1, le=4)
+
+
+class UnmappedZebraException(Exception):
+    pass

dodal/devices/zocalo/zocalo_interaction.py

@@ -55,7 +55,8 @@ class ZocaloTrigger:
     intended to be used in bluesky callback classes. To get results from zocalo back
     into a plan, use the ZocaloResults ophyd device.
 
-    see https://github.com/DiamondLightSource/dodal/wiki/How-to-Interact-with-Zocalo"""
+    see https://diamondlightsource.github.io/dodal/main/how-to/zocalo.html for
+    more information about zocalo."""
 
     def __init__(self, environment: str = ZOCALO_ENV):
         self.zocalo_environment: str = environment

dodal/devices/zocalo/zocalo_results.py

@@ -11,7 +11,7 @@ import workflows.recipe
 import workflows.transport
 from bluesky.protocols import Triggerable
 from bluesky.utils import Msg
-from deepdiff import DeepDiff
+from deepdiff.diff import DeepDiff
 from ophyd_async.core import (
     Array1D,
     AsyncStatus,
@@ -53,6 +53,26 @@ ZOCALO_STAGE_GROUP = "clear zocalo queue"
 
 
 class XrcResult(TypedDict):
+    """
+    Information about a diffracting centre.
+
+    NOTE: the coordinate systems of centre_of_mass and max_voxel/bounding_box are not
+        the same; centre_of_mass coordinates are continuous whereas max_voxel and bounding_box
+        coordinates are discrete.
+    Attributes:
+         centre_of_mass: The position of the centre of mass of the crystal, adjusted so that
+         grid box centres lie on integer grid coordinates, such that a 1x1x1 crystal detected in
+         a single grid box at 0, 0, 0, has c.o.m. of 0, 0, 0, not 0.5, 0.5, 0.5
+         max_voxel: Position of the voxel with the maximum count, in integer coordinates
+         max_count: max count achieved in a single voxel for the crystal
+         n_voxels: Number of voxels (aka grid boxes) in the diffracting centre
+         total_count: Total of above-threshold spot counts in the labelled voxels
+         bounding_box: The rectangular prism that bounds the crystal, expressed
+            as the volume of whole boxes as a half-open range i.e such that
+            p1 = (x1, y1, z1) <= p < p2 = (x2, y2, z2) and
+            p2 - p1 gives the dimensions in whole voxels.
+    """
+
     centre_of_mass: list[float]
     max_voxel: list[int]
     max_count: int
@@ -133,7 +153,7 @@ class ZocaloResults(StandardReadable, Triggerable):
         self.use_cpu_and_gpu = use_cpu_and_gpu
 
         self.centre_of_mass, self._com_setter = soft_signal_r_and_setter(
-            Array1D[np.uint64], name="centre_of_mass"
+            Array1D[np.float64], name="centre_of_mass"
         )
         self.bounding_box, self._bounding_box_setter = soft_signal_r_and_setter(
             Array1D[np.uint64], name="bounding_box"

dodal/log.py

@@ -152,7 +152,7 @@ def set_up_graylog_handler(logger: Logger, host: str, port: int):
 def set_up_INFO_file_handler(logger, path: Path, filename: str):
     """Set up a file handler for the logger, at INFO level, which will keep 30 days
     of logs, rotating once per day. Creates the directory if necessary."""
-    print(f"Logging to INFO file handler {path/filename}")
+    print(f"Logging to INFO file handler {path / filename}")
     path.mkdir(parents=True, exist_ok=True)
     file_handler = TimedRotatingFileHandler(
         filename=path / filename, when="MIDNIGHT", backupCount=INFO_LOG_DAYS
@@ -169,7 +169,7 @@ def set_up_DEBUG_memory_handler(
     log file when it sees a message of severity ERROR. Creates the directory if
     necessary"""
     debug_path = path / "debug"
-    print(f"Logging to DEBUG handler {debug_path/filename}")
+    print(f"Logging to DEBUG handler {debug_path / filename}")
     debug_path.mkdir(parents=True, exist_ok=True)
     file_handler = TimedRotatingFileHandler(
         filename=debug_path / filename, when="H", backupCount=DEBUG_LOG_FILES_TO_KEEP

dodal/plans/wrapped.py

@@ -49,9 +49,9 @@ def count(
     Wraps bluesky.plans.count(det, num, delay, md=metadata) exposing only serializable
     parameters and metadata."""
     if isinstance(delay, Sequence):
-        assert (
-            len(delay) == num - 1
-        ), f"Number of delays given must be {num - 1}: was given {len(delay)}"
+        assert len(delay) == num - 1, (
+            f"Number of delays given must be {num - 1}: was given {len(delay)}"
+        )
     metadata = metadata or {}
     metadata["shape"] = (num,)
     yield from bp.count(tuple(detectors), num, delay=delay, md=metadata)