dls-dodal 1.65.0__py3-none-any.whl → 1.66.0__py3-none-any.whl

dodal/devices/undulator.py

@@ -1,4 +1,5 @@
 import os
+from abc import ABC, abstractmethod
 
 import numpy as np
 from bluesky.protocols import Locatable, Location, Movable
@@ -39,111 +40,177 @@ def _get_gap_for_energy(
     )
 
 
-class Undulator(StandardReadable, Movable[float]):
+class BaseUndulator(StandardReadable, Movable[float], ABC):
     """
-    An Undulator-type insertion device, used to control photon emission at a given
-    beam energy.
+    Base class for undulator devices providing gap control and access management.
+    This class expects target gap value [mm] passed in set method.
     """
 
     def __init__(
         self,
         prefix: str,
-        id_gap_lookup_table_path: str = os.devnull,
-        name: str = "",
         poles: int | None = None,
         length: float | None = None,
+        undulator_period: int | None = None,
         baton: Baton | None = None,
+        name: str = "",
     ) -> None:
-        """Constructor
-
+        """
         Args:
             prefix: PV prefix
-            poles (int): Number of magnetic poles built into the undulator
-            length (float): Length of the undulator in meters
+            poles (int, optional): Number of magnetic poles built into the undulator
+            length (float, optional): Length of the undulator in meters
+            undulator_period(int, optional): Undulator period
+            baton (optional): Baton object if provided.
             name (str, optional): Name for device. Defaults to "".
         """
-
         self.baton_ref = Reference(baton) if baton else None
-        self.id_gap_lookup_table_path = id_gap_lookup_table_path
+
         with self.add_children_as_readables():
+            self.gap_access = epics_signal_r(EnabledDisabledUpper, prefix + "IDBLENA")
             self.gap_motor = Motor(prefix + "BLGAPMTR")
             self.current_gap = epics_signal_r(float, prefix + "CURRGAPD")
-            self.gap_access = epics_signal_r(EnabledDisabledUpper, prefix + "IDBLENA")
 
         with self.add_children_as_readables(StandardReadableFormat.CONFIG_SIGNAL):
             self.gap_discrepancy_tolerance_mm, _ = soft_signal_r_and_setter(
                 float,
                 initial_value=UNDULATOR_DISCREPANCY_THRESHOLD_MM,
             )
-            if poles is not None:
-                self.poles, _ = soft_signal_r_and_setter(
-                    int,
-                    initial_value=poles,
-                )
-            else:
-                self.poles = None
-
-            if length is not None:
-                self.length, _ = soft_signal_r_and_setter(
-                    float,
-                    initial_value=length,
-                )
-            else:
-                self.length = None
-
-        super().__init__(name)
+            self.poles = self._make_signal_if_not_none(poles, int)
+            self.length = self._make_signal_if_not_none(length, float)
+            self.undulator_period = self._make_signal_if_not_none(undulator_period, int)
 
+        super().__init__(name=name)
+
+    def _make_signal_if_not_none(self, initial_value, type):
+        if initial_value is None:
+            return None
+        signal, _ = soft_signal_r_and_setter(type, initial_value=initial_value)
+        return signal
+
+    @abstractmethod
     @AsyncStatus.wrap
-    async def set(self, value: float):
+    async def set(self, value: float) -> None:
         """
-        Set the undulator gap to a given energy in keV
+        Move undulator to a given position.
+        Abstract method - must be implemented by subclasses.
 
         Args:
-            value: energy in keV
+            value: target position - units depend on implementation
         """
-        await self._set_undulator_gap(value)
+        ...
 
-    async def raise_if_not_enabled(self):
-        access_level = await self.gap_access.get_value()
-        commissioning_mode = await self._is_commissioning_mode_enabled()
-        if access_level is EnabledDisabledUpper.DISABLED and not commissioning_mode:
-            raise AccessError("Undulator gap access is disabled. Contact Control Room")
+    async def _set_gap(self, value: float) -> None:
+        """
+        Set the undulator gap to a given value in mm.
+
+        Args:
+            value: gap in mm
+        """
+        await self.raise_if_not_enabled()  # Check access
+        if await self._check_gap_within_threshold(value):
+            LOGGER.debug(
+                "Gap is already in the correct place, no need to ask it to move"
+            )
+            return
 
-    async def _set_undulator_gap(self, energy_kev: float) -> None:
-        await self.raise_if_not_enabled()
-        target_gap = await self._get_gap_to_match_energy(energy_kev)
         LOGGER.info(
-            f"Setting undulator gap to {target_gap:.3f}mm based on {energy_kev:.2f}kev"
+            f"Undulator gap mismatch. Moving gap to nominal value, {value:.3f}mm"
         )
+        commissioning_mode = await self._is_commissioning_mode_enabled()
+        if not commissioning_mode:
+            # Only move if the gap is sufficiently different to the value from the
+            # DCM lookup table AND we're not in commissioning mode
+            await self.gap_motor.set(
+                value,
+                timeout=STATUS_TIMEOUT_S,
+            )
+        else:
+            LOGGER.warning("In test mode, not moving ID gap")
 
-        # Check if undulator gap is close enough to the value from the DCM
+    async def _check_gap_within_threshold(self, target_gap: float) -> bool:
+        """
+        Check if the undulator gap is within the acceptable threshold of the target gap.
+
+        Args:
+            target_gap: target gap in mm
+        Returns:
+            True if the gap is within the threshold, False otherwise
+        """
         current_gap = await self.current_gap.get_value()
         tolerance = await self.gap_discrepancy_tolerance_mm.get_value()
-        difference = abs(target_gap - current_gap)
-        if difference > tolerance:
-            LOGGER.info(
-                f"Undulator gap mismatch. {difference:.3f}mm is outside tolerance.\
-                Moving gap to nominal value, {target_gap:.3f}mm"
-            )
-            commissioning_mode = await self._is_commissioning_mode_enabled()
-            if not commissioning_mode:
-                # Only move if the gap is sufficiently different to the value from the
-                # DCM lookup table AND we're not in commissioning mode
-                await self.gap_motor.set(
-                    target_gap,
-                    timeout=STATUS_TIMEOUT_S,
-                )
-            else:
-                LOGGER.warning("In test mode, not moving ID gap")
-        else:
-            LOGGER.debug(
-                "Gap is already in the correct place for the new energy value "
-                f"{energy_kev}, no need to ask it to move"
-            )
+        return abs(target_gap - current_gap) <= tolerance
 
-    async def _is_commissioning_mode_enabled(self):
+    async def _is_commissioning_mode_enabled(self) -> bool | None:
+        """
+        Asynchronously checks if commissioning mode is enabled via the baton reference.
+        """
         return self.baton_ref and await self.baton_ref().commissioning.get_value()
 
+    async def raise_if_not_enabled(self) -> AccessError | None:
+        """
+        Asynchronously raises AccessError if gap access is disabled and not in commissioning mode.
+        """
+        access_level = await self.gap_access.get_value()
+        commissioning_mode = await self._is_commissioning_mode_enabled()
+        if access_level is EnabledDisabledUpper.DISABLED and not commissioning_mode:
+            raise AccessError("Undulator gap access is disabled. Contact Control Room")
+
+
+class UndulatorInKeV(BaseUndulator):
+    """
+    An Undulator-type insertion device, used to control photon emission at a given beam energy.
+    This class expects energy [keV] passed in set method and does conversion to gap
+    internally, for which it requires path to lookup table file in constructor.
+    """
+
+    def __init__(
+        self,
+        prefix: str,
+        id_gap_lookup_table_path: str = os.devnull,
+        poles: int | None = None,
+        length: float | None = None,
+        undulator_period: int | None = None,
+        baton: Baton | None = None,
+        name: str = "",
+    ) -> None:
+        """Constructor
+
+        Args:
+            prefix: PV prefix
+            id_gap_lookup_table_path (str): Path to a lookup table file
+            poles (int, optional): Number of magnetic poles built into the undulator
+            length (float, optional): Length of the undulator in meters
+            undulator_period(int, optional): Undulator period
+            baton (optional): Baton object if provided.
+            name (str, optional): Name for device. Defaults to "".
+        """
+
+        self.id_gap_lookup_table_path = id_gap_lookup_table_path
+        super().__init__(
+            prefix=prefix,
+            poles=poles,
+            length=length,
+            undulator_period=undulator_period,
+            baton=baton,
+            name=name,
+        )
+
+    @AsyncStatus.wrap
+    async def set(self, value: float):
+        """
+        Check conditions and Set undulator gap to a given energy in keV
+
+        Args:
+            value: energy in keV
+        """
+        # Convert energy in keV to gap in mm first
+        target_gap = await self._get_gap_to_match_energy(value)
+        LOGGER.info(
+            f"Setting undulator gap to {target_gap:.3f}mm based on {value:.2f}kev"
+        )
+        await self._set_gap(target_gap)
+
     async def _get_gap_to_match_energy(self, energy_kev: float) -> float:
         """
         get a 2d np.array from lookup table that
@@ -160,6 +227,23 @@ class Undulator(StandardReadable, Movable[float]):
         )
 
 
+class UndulatorInMm(BaseUndulator):
+    """
+    An Undulator-type insertion device, used to control photon emission.
+    This class expects gap [mm] passed in set method.
+    """
+
+    @AsyncStatus.wrap
+    async def set(self, value: float):
+        """
+        Check conditions and Set undulator gap to a given value in mm
+
+        Args:
+            value: value in mm
+        """
+        await self._set_gap(value)
+
+
 class UndulatorOrder(StandardReadable, Locatable[int]):
     """
     Represents the order of an undulator device. Allows setting and locating the order.
@@ -171,17 +255,17 @@ class UndulatorOrder(StandardReadable, Locatable[int]):
             name: Name for device. Defaults to ""
         """
         with self.add_children_as_readables():
-            self._value = soft_signal_rw(int, initial_value=3)
+            self.value = soft_signal_rw(int, initial_value=3)
         super().__init__(name=name)
 
     @AsyncStatus.wrap
     async def set(self, value: int) -> None:
         if (value >= 0) and isinstance(value, int):
-            await self._value.set(value)
+            await self.value.set(value)
         else:
             raise ValueError(
                 f"Undulator order must be a positive integer. Requested value: {value}"
             )
 
     async def locate(self) -> Location[int]:
-        return await self._value.locate()
+        return await self.value.locate()

dodal/devices/util/lookup_tables_apple2.py

@@ -0,0 +1,390 @@
+"""Apple2 lookup table utilities and CSV converter.
+
+This module provides helpers to read, validate and convert Apple2 insertion-device
+lookup tables (energy -> gap/phase polynomials) from CSV sources into an
+in-memory dictionary format used by the Apple2 controllers.
+
+Data format produced
+The lookup-table dictionary created by convert_csv_to_lookup() follows this
+structure:
+
+{
+  "POL_MODE": {
+    "energies": {
+      "<min_energy>": {
+        "low": <float>,
+        "high": <float>,
+        "poly": <numpy.poly1d>
+      },
+      ...
+    },
+    "limit": {
+      "minimum": <float>,
+      "maximum": <float>
+    }
+  },
+}
+
+"""
+
+import csv
+import io
+from collections.abc import Generator
+from pathlib import Path
+
+import numpy as np
+from daq_config_server.client import ConfigServer
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    RootModel,
+    field_serializer,
+    field_validator,
+)
+
+from dodal.devices.apple2_undulator import Pol
+from dodal.log import LOGGER
+
+DEFAULT_GAP_FILE = "IDEnergy2GapCalibrations.csv"
+DEFAULT_PHASE_FILE = "IDEnergy2PhaseCalibrations.csv"
+
+
+DEFAULT_POLY_DEG = [
+    "7th-order",
+    "6th-order",
+    "5th-order",
+    "4th-order",
+    "3rd-order",
+    "2nd-order",
+    "1st-order",
+    "b",
+]
+
+MODE_NAME_CONVERT = {"CR": "pc", "CL": "nc"}
+
+
+class LookupTableConfig(BaseModel):
+    source: tuple[str, str] | None = None
+    mode: str = "Mode"
+    min_energy: str = "MinEnergy"
+    max_energy: str = "MaxEnergy"
+    poly_deg: list[str] = Field(default_factory=lambda: DEFAULT_POLY_DEG)
+    mode_name_convert: dict[str, str] = Field(default_factory=lambda: MODE_NAME_CONVERT)
+
+
+class EnergyMinMax(BaseModel):
+    minimum: float
+    maximum: float
+
+
+class EnergyCoverageEntry(BaseModel):
+    model_config = ConfigDict(arbitrary_types_allowed=True)  # So np.poly1d can be used.
+    low: float
+    high: float
+    poly: np.poly1d
+
+    @field_validator("poly", mode="before")
+    @classmethod
+    def validate_and_convert_poly(cls, value):
+        """If reading from serialized data, it will be using a list. Convert to np.poly1d"""
+        if isinstance(value, list):
+            return np.poly1d(value)
+        return value
+
+    @field_serializer("poly", mode="plain")
+    def serialize_poly(self, value: np.poly1d) -> list:
+        """Allow np.poly1d to work when serializing."""
+        return value.coefficients.tolist()
+
+
+class EnergyCoverage(RootModel[dict[float, EnergyCoverageEntry]]):
+    pass
+
+
+class LookupTableEntries(BaseModel):
+    energies: EnergyCoverage
+    limit: EnergyMinMax
+
+
+class LookupTable(RootModel[dict[Pol, LookupTableEntries]]):
+    # Allow to auto specify a dict if one not provided
+    def __init__(self, root: dict[Pol, LookupTableEntries] | None = None):
+        super().__init__(root=root or {})
+
+
+class GapPhaseLookupTables(BaseModel):
+    gap: LookupTable = Field(default_factory=lambda: LookupTable())
+    phase: LookupTable = Field(default_factory=lambda: LookupTable())
+
+
+def convert_csv_to_lookup(
+    file_contents: str,
+    lut_config: LookupTableConfig,
+    skip_line_start_with: str = "#",
+) -> LookupTable:
+    """
+    Convert CSV content into the Apple2 lookup-table dictionary.
+
+    Parameters:
+    -----------
+    file_contents:
+        The CSV file contents as string.
+    lut_config:
+        The configuration that how to process the file_contents into a LookupTable.
+    skip_line_start_with
+        Lines beginning with this prefix are skipped (default "#").
+
+    Returns:
+    -----------
+    LookupTable
+    """
+
+    def process_row(row: dict, lut: LookupTable):
+        """Process a single row from the CSV file and update the lookup table."""
+        mode_value = str(row[lut_config.mode]).lower()
+        if mode_value in lut_config.mode_name_convert:
+            mode_value = lut_config.mode_name_convert[f"{mode_value}"]
+        mode_value = Pol(mode_value)
+
+        # Create polynomial object for energy-to-gap/phase conversion
+        coefficients = [float(row[coef]) for coef in lut_config.poly_deg]
+        if mode_value not in lut.root:
+            lut.root[mode_value] = generate_lookup_table_entry(
+                min_energy=float(row[lut_config.min_energy]),
+                max_energy=float(row[lut_config.max_energy]),
+                poly1d_param=coefficients,
+            )
+
+        else:
+            lut.root[mode_value].energies.root[float(row[lut_config.min_energy])] = (
+                EnergyCoverageEntry(
+                    low=float(row[lut_config.min_energy]),
+                    high=float(row[lut_config.max_energy]),
+                    poly=np.poly1d(coefficients),
+                )
+            )
+
+        # Update energy limits
+        lut.root[mode_value].limit.minimum = min(
+            lut.root[mode_value].limit.minimum,
+            float(row[lut_config.min_energy]),
+        )
+        lut.root[mode_value].limit.maximum = max(
+            lut.root[mode_value].limit.maximum,
+            float(row[lut_config.max_energy]),
+        )
+        return lut
+
+    reader = csv.DictReader(read_file_and_skip(file_contents, skip_line_start_with))
+    lut = LookupTable()
+
+    for row in reader:
+        # If there are multiple source only convert requested.
+        if lut_config.source is not None:
+            if row[lut_config.source[0]] == lut_config.source[1]:
+                process_row(row=row, lut=lut)
+        else:
+            process_row(row=row, lut=lut)
+
+    # Check if our LookupTable is empty after processing, raise error if it is.
+    if not lut.root:
+        raise RuntimeError(
+            "LookupTable content is empty, failed to convert the file contents to "
+            "a LookupTable!"
+        )
+    return lut
+
+
+def read_file_and_skip(file: str, skip_line_start_with: str = "#") -> Generator[str]:
+    """Yield non-comment lines from the CSV content string."""
+    for line in io.StringIO(file):
+        if line.startswith(skip_line_start_with):
+            continue
+        else:
+            yield line
+
+
+def get_poly(
+    energy: float,
+    pol: Pol,
+    lookup_table: LookupTable,
+) -> np.poly1d:
+    """
+    Return the numpy.poly1d polynomial applicable for the given energy and polarisation.
+
+    Parameters:
+    -----------
+    energy:
+        Energy value in the same units used to create the lookup table (eV).
+    pol:
+        Polarisation mode (Pol enum).
+    lookup_table:
+        The converted lookup table dictionary for either 'gap' or 'phase'.
+    """
+    if (
+        energy < lookup_table.root[pol].limit.minimum
+        or energy > lookup_table.root[pol].limit.maximum
+    ):
+        raise ValueError(
+            "Demanding energy must lie between"
+            + f" {lookup_table.root[pol].limit.minimum}"
+            + f" and {lookup_table.root[pol].limit.maximum} eV!"
+        )
+    else:
+        for energy_range in lookup_table.root[pol].energies.root.values():
+            if energy >= energy_range.low and energy < energy_range.high:
+                return energy_range.poly
+
+    raise ValueError(
+        "Cannot find polynomial coefficients for your requested energy."
+        + " There might be gap in the calibration lookup table."
+    )
+
+
+def generate_lookup_table_entry(
+    min_energy: float, max_energy: float, poly1d_param: list[float]
+) -> LookupTableEntries:
+    return LookupTableEntries(
+        energies=EnergyCoverage(
+            {
+                min_energy: EnergyCoverageEntry(
+                    low=min_energy,
+                    high=max_energy,
+                    poly=np.poly1d(poly1d_param),
+                )
+            }
+        ),
+        limit=EnergyMinMax(
+            minimum=float(min_energy),
+            maximum=float(max_energy),
+        ),
+    )
+
+
+def generate_lookup_table(
+    pol: Pol, min_energy: float, max_energy: float, poly1d_param: list[float]
+) -> LookupTable:
+    return LookupTable(
+        {pol: generate_lookup_table_entry(min_energy, max_energy, poly1d_param)}
+    )
+
+
+def make_phase_tables(
+    pols: list[Pol],
+    min_energies: list[float],
+    max_energies: list[float],
+    poly1d_params: list[list[float]],
+) -> LookupTable:
+    """Generate a dictionary containing multiple lookuptable entries
+    for provided polarisations."""
+    lookuptable_phase = LookupTable()
+    for i in range(len(pols)):
+        lookuptable_phase.root[pols[i]] = generate_lookup_table_entry(
+            min_energy=min_energies[i],
+            max_energy=max_energies[i],
+            poly1d_param=poly1d_params[i],
+        )
+
+    return lookuptable_phase
+
+
+class EnergyMotorLookup:
+    """
+    Handles lookup tables for Apple2 ID, converting energy and polarisation to gap
+    and phase. Fetches and parses lookup tables from a config server, supports dynamic
+    updates, and validates input. If custom logic is required for lookup tables, sub
+    classes should override the _update_gap_lut and _update_phase_lut methods.
+
+    After update_lookuptable() has populated the 'gap' and 'phase' tables,
+    `get_motor_from_energy()` can be used to compute (gap, phase) for a requested
+    (energy, pol) pair.
+    """
+
+    def __init__(
+        self,
+        config_client: ConfigServer,
+        lut_config: LookupTableConfig,
+        gap_path: Path,
+        phase_path: Path,
+    ):
+        """Initialise the EnergyMotorLookup class with lookup table headers provided.
+
+        Parameters:
+        -----------
+        config_client:
+            The config server client to fetch the look up table data.
+        lut_config:
+            Configuration that defines how to process file contents into a LookupTable
+        gap_path:
+            File path to the gap lookup table.
+        phase_path:
+            File path to the phase lookup table.
+        """
+        self.lookup_tables = GapPhaseLookupTables()
+        self.config_client = config_client
+        self.lut_config = lut_config
+        self.gap_path = gap_path
+        self.phase_path = phase_path
+        self._available_pol = []
+
+    @property
+    def available_pol(self) -> list[Pol]:
+        return self._available_pol
+
+    @available_pol.setter
+    def available_pol(self, value: list[Pol]) -> None:
+        self._available_pol = value
+
+    def _update_gap_lut(self) -> None:
+        file_contents = self.config_client.get_file_contents(
+            self.gap_path, reset_cached_result=True
+        )
+        self.lookup_tables.gap = convert_csv_to_lookup(
+            file_contents, lut_config=self.lut_config
+        )
+        self.available_pol = list(self.lookup_tables.gap.root.keys())
+
+    def _update_phase_lut(self) -> None:
+        file_contents = self.config_client.get_file_contents(
+            self.phase_path, reset_cached_result=True
+        )
+        self.lookup_tables.phase = convert_csv_to_lookup(
+            file_contents, lut_config=self.lut_config
+        )
+
+    def update_lookuptables(self):
+        """
+        Update lookup tables from files and validate their format.
+        """
+        LOGGER.info("Updating lookup table from file for gap.")
+        self._update_gap_lut()
+        LOGGER.info("Updating lookup table from file for phase.")
+        self._update_phase_lut()
+
+    def get_motor_from_energy(self, energy: float, pol: Pol) -> tuple[float, float]:
+        """
+        Convert energy and polarisation to gap and phase motor positions.
+
+        Parameters:
+        -----------
+        energy : float
+            Desired energy in eV.
+        pol : Pol
+            Polarisation mode.
+
+        Returns:
+        ----------
+        tuple[float, float]
+            (gap, phase) motor positions.
+        """
+        if self.available_pol == []:
+            self.update_lookuptables()
+
+        gap_poly = get_poly(lookup_table=self.lookup_tables.gap, energy=energy, pol=pol)
+        phase_poly = get_poly(
+            lookup_table=self.lookup_tables.phase,
+            energy=energy,
+            pol=pol,
+        )
+        return gap_poly(energy), phase_poly(energy)

dodal/plans/load_panda_yaml.py

@@ -0,0 +1,9 @@
+from ophyd_async.core import YamlSettingsProvider
+from ophyd_async.fastcs.panda import HDFPanda
+from ophyd_async.plan_stubs import apply_panda_settings, retrieve_settings
+
+
+def load_panda_from_yaml(yaml_directory: str, yaml_file_name: str, panda: HDFPanda):
+    provider = YamlSettingsProvider(yaml_directory)
+    settings = yield from retrieve_settings(provider, yaml_file_name, panda)
+    yield from apply_panda_settings(settings)