dls-dodal 1.69.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

dodal/devices/focusing_mirror.py

@@ -27,7 +27,7 @@ DEFAULT_SETTLE_TIME_S = 60
 
 
 class MirrorType(StrictEnum):
-    """See https://manual.nexusformat.org/classes/base_classes/NXmirror.html"""
+    """See https://manual.nexusformat.org/classes/base_classes/NXmirror.html."""
 
     SINGLE = "single"
     MULTI = "multi"
@@ -53,8 +53,9 @@ class MirrorVoltageDemand(StrictEnum):
 
 
 class SingleMirrorVoltage(Device):
-    """Abstract the bimorph mirror voltage PVs into a single device that can be set asynchronously and returns when
-    the demanded voltage setpoint is accepted, without blocking the caller as this process can take significant time.
+    """Abstract the bimorph mirror voltage PVs into a single device that can be set
+    asynchronously and returns when the demanded voltage setpoint is accepted, without
+    blocking the caller as this process can take significant time.
     """
 
     def __init__(self, prefix: str, name: str = ""):
@@ -66,11 +67,14 @@ class SingleMirrorVoltage(Device):
     @AsyncStatus.wrap
     async def set(self, value, *args, **kwargs):
         """Combine the following operations into a single set:
-        1. apply the value to the setpoint PV
-        3. Wait until demand is accepted
-        4. When either demand is accepted or DEFAULT_SETTLE_TIME expires, signal the result on the Status
-        """
 
+        1. apply the value to the setpoint PV.
+
+        3. Wait until demand is accepted.
+
+        4. When either demand is accepted or DEFAULT_SETTLE_TIME expires, signal the
+           result on the Status.
+        """  # noqa D415
         setpoint_v = self._setpoint_v
         demand_accepted = self._demand_accepted
 
@@ -136,7 +140,7 @@ class MirrorVoltages(StandardReadable):
 
 
 class SimpleMirror(XYPitchStage):
-    """Simple Focusing Mirror"""
+    """Simple Focusing Mirror."""
 
     def __init__(
         self,
@@ -165,7 +169,7 @@ class SimpleMirror(XYPitchStage):
 
 
 class FocusingMirror(StandardReadable):
-    """Focusing Mirror"""
+    """Focusing Mirror."""
 
     def __init__(
         self,
@@ -202,7 +206,8 @@ class FocusingMirror(StandardReadable):
 
 class FocusingMirrorWithStripes(FocusingMirror):
     """A focusing mirror where the stripe material can be changed. This is usually done
-    based on the energy of the beamline."""
+    based on the energy of the beamline.
+    """
 
     def __init__(self, prefix: str, name: str = "", *args, **kwargs):
         self.stripe = epics_signal_rw(MirrorStripe, prefix + "STRP:DVAL")
@@ -212,9 +217,22 @@ class FocusingMirrorWithStripes(FocusingMirror):
         super().__init__(prefix, name, *args, **kwargs)
 
     def energy_to_stripe(self, energy_kev) -> MirrorStripeConfiguration:
-        """Return the stripe, yaw angle and lateral position for the specified energy"""
+        """Return the stripe, yaw angle and lateral position for the specified energy."""
         # In future, this should be configurable per-mirror
         if energy_kev < 7:
             return {"stripe": MirrorStripe.BARE, "yaw_mrad": 6.2, "lat_mm": 0.0}
         else:
             return {"stripe": MirrorStripe.RHODIUM, "yaw_mrad": 0.0, "lat_mm": 10.0}
+
+
+class FocusingMirrorWithPiezo(FocusingMirror):
+    """A focusing mirror which also has a piezoelectric actuator.
+    A voltage can be applied to the piezo to steer the beam by making the material
+    shrink or expand.
+    """
+
+    def __init__(self, prefix: str, name: str = "", *args, **kwargs):
+        with self.add_children_as_readables():
+            self.piezo = epics_signal_rw(float, f"{prefix}AOFPITCH")
+            self.piezo_rbv = epics_signal_r(float, f"{prefix}AOFPITCH:RBV")
+        super().__init__(prefix, name, *args, **kwargs)

dodal/devices/hutch_shutter.py

@@ -58,14 +58,14 @@ class HutchInterlock(StandardReadable):
 class HutchShutter(StandardReadable, Movable[ShutterDemand]):
     """Device to operate the hutch shutter.
 
-    When a demand is sent, the device should first check the hutch status \
-    and raise an error if it's not interlocked (searched and locked), meaning it's not \
+    When a demand is sent, the device should first check the hutch status
+    and raise an error if it's not interlocked (searched and locked), meaning it's not
     safe to operate the shutter.
 
-    If the requested shutter position is "Open", the shutter control PV should first \
-    go to "Reset" and then move to "Open". This is because before opening the hutch \
-    shutter, the interlock status PV (`-PS-SHTR-01:ILKSTA`) will show as `failed` until \
-    the hutch shutter is reset. This will set the interlock status to `OK`, allowing \
+    If the requested shutter position is "Open", the shutter control PV should first
+    go to "Reset" and then move to "Open". This is because before opening the hutch
+    shutter, the interlock status PV (`-PS-SHTR-01:ILKSTA`) will show as `failed` until
+    the hutch shutter is reset. This will set the interlock status to `OK`, allowing
     for shutter operations. Until this step is done, the hutch shutter can't be opened.
     The reset is not needed for closing the shutter.
     """

dodal/devices/insertion_device/__init__.py

@@ -2,6 +2,7 @@ from .apple2_controller import (
     MAXIMUM_MOVE_TIME,
     Apple2Controller,
     Apple2EnforceLHMoveController,
+    Apple2Type,
     EnergyMotorConvertor,
 )
 from .apple2_undulator import (
@@ -17,6 +18,10 @@ from .apple2_undulator import (
     UndulatorPhaseAxes,
     UnstoppableMotor,
 )
+from .apple_knot_controller import (
+    AppleKnotController,
+    AppleKnotPathFinder,
+)
 from .energy import BeamEnergy, InsertionDeviceEnergy, InsertionDeviceEnergyBase
 from .energy_motor_lookup import (
     ConfigServerEnergyMotorLookup,
@@ -33,8 +38,11 @@ from .polarisation import InsertionDevicePolarisation
 
 __all__ = [
     "Apple2",
+    "Apple2Type",
     "Apple2Controller",
     "Apple2EnforceLHMoveController",
+    "AppleKnotController",
+    "AppleKnotPathFinder",
     "UndulatorGap",
     "UndulatorPhaseAxes",
     "UndulatorJawPhase",

dodal/devices/insertion_device/apple2_controller.py

@@ -33,7 +33,7 @@ MAXIMUM_GAP_MOTOR_POSITION = 100
 
 class EnergyMotorConvertor(Protocol):
     def __call__(self, energy: float, pol: Pol) -> float:
-        """Protocol to provide energy to motor position conversion"""
+        """Protocol to provide energy to motor position conversion."""
         ...
 
 
@@ -41,44 +41,51 @@ Apple2Type = TypeVar("Apple2Type", bound=Apple2)
 
 
 class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
-    """
-
-    Abstract base class for controlling an Apple2 undulator device.
+    """Abstract base class for controlling an Apple2 undulator device.
 
     This class manages the undulator's gap and phase motors, and provides an interface
     for controlling polarisation and energy settings. It exposes derived signals for
     energy and polarisation, and handles conversion between energy/polarisation and
     motor positions via a user-supplied conversion callable.
 
-    Attributes
-    ----------
-    apple2 : Reference[Apple2Type]
-        Reference to the Apple2 device containing gap and phase motors.
-    energy : derived_signal_rw
-        Derived signal for moving and reading back energy.
-    polarisation_setpoint : SignalR
-        Soft signal for the polarisation setpoint.
-    polarisation : derived_signal_rw
-        Hardware-backed signal for polarisation readback and control.
-    gap_energy_to_motor_converter : EnergyMotorConvertor
-        Callable that converts energy and polarisation to gap motor positions.
-    phase_energy_to_motor_converter : EnergyMotorConvertor
-        Callable that converts energy and polarisation to phase motor positions.
-    maximum_gap_motor_position : float
-        Maximum allowed position for the gap motor.
-    maximum_phase_motor_position : float
-        Maximum allowed position for the raw phase motors.
-
-    Abstract Methods
-    ----------------
-    _get_apple2_value(gap: float, phase: float) -> Apple2Val
-        Abstract method to return the Apple2Val used to set the apple2 with.
-    Notes
-    -----
-    - Subclasses must implement `_get_apple2_value` for beamline-specific logic.
-    - LH3 polarisation is indistinguishable from LH in hardware; special handling is provided.
-    - Supports multiple polarisation modes, including linear horizontal (LH), linear vertical (LV),
-      positive circular (PC), negative circular (NC), and linear arbitrary (LA).
+    Attributes:
+        apple2 (Reference[Apple2Type]): Reference to the Apple2 device containing gap
+            and phase motors.
+        energy (derived_signal_rw): Derived signal for moving and reading back energy.
+        polarisation_setpoint (SignalR): Soft signal for the polarisation setpoint.
+        polarisation (derived_signal_rw): Hardware-backed signal for polarisation
+            readback and control.
+        gap_energy_to_motor_converter (EnergyMotorConvertor): Callable that converts
+            energy and polarisation to gap motor positions.
+        phase_energy_to_motor_converter (EnergyMotorConvertor): Callable that converts
+            energy and polarisation to phase motor positions.
+        maximum_gap_motor_position (float): Maximum allowed position for the gap motor.
+        maximum_phase_motor_position (float): Maximum allowed position for the raw phase
+            motors.
+
+    Args:
+        apple2 (Apple2): An Apple2 device.
+        gap_energy_motor_converter (EnergyMotorConvertor): The callable that handles
+            the gap look up table logic for the insertion device.
+        phase_energy_motor_converter (EnergyMotorConvertor): The callable that
+            handles the phase look up table logic for the insertion device.
+        maximum_gap_motor_position (float): Maximum allowed position for the gap motor.
+        maximum_phase_motor_position (float): Maximum allowed position for the raw phase
+            motors.
+        units (str): the units of this device. Defaults to eV.
+        name (str): Name of the device.
+
+    Abstract Methods:
+        _get_apple2_value(gap: float, phase: float) -> Apple2Val
+            Abstract method to return the Apple2Val used to set the apple2 with.
+
+    Notes:
+        - Subclasses must implement `_get_apple2_value` for beamline-specific logic.
+        - LH3 polarisation is indistinguishable from LH in hardware; special handling is
+          provided.
+        - Supports multiple polarisation modes, including linear horizontal (LH), linear
+          vertical (LV), positive circular (PC), negative circular (NC), and linear
+          arbitrary (LA).
 
     """
 
@@ -92,21 +99,6 @@ class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
         units: str = "eV",
         name: str = "",
     ) -> None:
-        """
-
-        Parameters
-        ----------
-        apple2: Apple2
-            An Apple2 device.
-        gap_energy_motor_converter: EnergyMotorConvertor
-            The callable that handles the gap look up table logic for the insertion device.
-        phase_energy_motor_converter: EnergyMotorConvertor
-            The callable that handles the phase look up table logic for the insertion device.
-        units: str
-            the units of this device. Defaults to eV.
-        name: str
-            Name of the device.
-        """
         self.apple2 = Reference(apple2)
         self.gap_energy_motor_converter = gap_energy_motor_converter
         self.phase_energy_motor_converter = phase_energy_motor_converter
@@ -156,8 +148,7 @@ class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
 
     @abc.abstractmethod
     def _get_apple2_value(self, gap: float, phase: float, pol: Pol) -> Apple2Val:
-        """
-        This method should be implemented by the beamline specific ID class as the
+        """This method should be implemented by the beamline specific ID class as the
         motor positions will be different for each beamline depending on the
         undulator design.
         """
@@ -182,8 +173,7 @@ class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
         return energy
 
     async def _check_and_get_pol_setpoint(self) -> Pol:
-        """
-        Check the polarisation setpoint and if it is NONE try to read it from
+        """Check the polarisation setpoint and if it is NONE try to read it from
         hardware.
         """
         pol = await self.polarisation_setpoint.get_value()
@@ -246,11 +236,11 @@ class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
         btm_outer: float,
         gap: float,
     ) -> tuple[Pol, float]:
-        """
-        Determine polarisation and phase value using motor position patterns.
+        """Determine polarisation and phase value using motor position patterns.
         However there is no way to return lh3 polarisation or higher harmonic setting.
-        (May be for future one can use the inverse poly to work out the energy and try to match it with the current energy
-        to workout the polarisation but during my test the inverse poly is too unstable for general use.)
+        (May be for future one can use the inverse poly to work out the energy and try
+        to match it with the current energy to workout the polarisation but during my
+        test the inverse poly is too unstable for general use).
         """
         if gap > self.maximum_gap_motor_position:
             raise RuntimeError(
@@ -266,16 +256,16 @@ class Apple2Controller(abc.ABC, StandardReadable, Generic[Apple2Type]):
         if (
             isclose(
                 top_outer,
-                self.maximum_phase_motor_position,
+                btm_inner,
                 abs_tol=ROW_PHASE_MOTOR_TOLERANCE,
             )
             and isclose(top_inner, 0.0, abs_tol=ROW_PHASE_MOTOR_TOLERANCE)
+            and isclose(btm_outer, 0.0, abs_tol=ROW_PHASE_MOTOR_TOLERANCE)
             and isclose(
-                btm_inner,
+                abs(btm_inner),
                 self.maximum_phase_motor_position,
                 abs_tol=ROW_PHASE_MOTOR_TOLERANCE,
             )
-            and isclose(btm_outer, 0.0, abs_tol=ROW_PHASE_MOTOR_TOLERANCE)
         ):
             LOGGER.info("Determined polarisation: LV (Linear Vertical).")
             return Pol.LV, self.maximum_phase_motor_position
@@ -321,7 +311,8 @@ class Apple2EnforceLHMoveController(
     However, because of the high forces involved in polarization changes,
     all movements must be performed using the Linear Horizontal (LH) mode.
     A look-up table must also be used to determine the highest energy that can
-    be reached in LH mode."""
+    be reached in LH mode.
+    """
 
     def __init__(
         self,

dodal/devices/insertion_device/apple2_undulator.py

@@ -170,19 +170,14 @@ class GapSafeMotorNoStop(UnstoppableMotor, UndulatorBase[float]):
 
 
 class UndulatorGap(GapSafeMotorNoStop):
-    """Apple 2 undulator gap motor device. With PV corrections."""
+    """Apple 2 undulator gap motor device. With PV corrections.
 
-    def __init__(self, prefix: str, name: str = ""):
-        """
-
-        Parameters
-        ----------
-            prefix : str
-                Beamline specific part of the PV
-            name : str
-                Name of the Id device
+    Args:
+        prefix (str): Beamline specific part of the PV
+        name (str): Name of the Id device
+    """
 
-        """
+    def __init__(self, prefix: str, name: str = ""):
         self.set_move = epics_signal_rw(int, prefix + "BLGSETP")
         # Nothing move until this is set to 1 and it will return to 0 when done.
         super().__init__(self.set_move, prefix, name)
@@ -201,8 +196,7 @@ class UndulatorGap(GapSafeMotorNoStop):
 
     @AsyncStatus.wrap
     async def prepare(self, value: FlyMotorInfo) -> None:
-        """
-        Prepare for a fly scan by moving to the run-up position at max velocity.
+        """Prepare for a fly scan by moving to the run-up position at max velocity.
         Stores fly info for later use in kickoff.
         """
         max_velocity, min_velocity, egu = await asyncio.gather(
@@ -228,18 +222,14 @@ class UndulatorGap(GapSafeMotorNoStop):
 
 
 class UndulatorPhaseMotor(UnstoppableMotor):
-    """Phase motor that will not stop."""
+    """Phase motor that will not stop.
 
-    def __init__(self, prefix: str, name: str = ""):
-        """
-        Parameters
-        ----------
+    Args:
+        prefix (str): The setting prefix PV.
+        name (str, optional): Name of the Id phase device.
+    """
 
-        prefix : str
-            The setting prefix PV.
-        name : str
-            Name of the Id phase device
-        """
+    def __init__(self, prefix: str, name: str = ""):
         motor_pv = f"{prefix}MTR"
         super().__init__(prefix=motor_pv, name=name)
         self.user_setpoint = epics_signal_rw(str, prefix + "SET")
@@ -275,10 +265,9 @@ class UndulatorLockedPhaseAxes(SafeUndulatorMover[Apple2PhaseValType]):
         )
 
     async def get_timeout(self) -> float:
+        """Get all motor speed, current positions and target positions to calculate
+        required timeout.
         """
-        Get all motor speed, current positions and target positions to calculate required timeout.
-        """
-
         timeouts = await asyncio.gather(
             *[
                 estimate_motor_timeout(
@@ -291,20 +280,19 @@ class UndulatorLockedPhaseAxes(SafeUndulatorMover[Apple2PhaseValType]):
         )
         """A 2.0 multiplier is required to prevent premature motor timeouts in phase
         axes as it is a master-slave system, where the slave's movement,
-        being dependent on the master, can take up to twice as long to complete.
-        """
+        being dependent on the master, can take up to twice as long to complete."""
         return np.max(timeouts) * 2.0
 
 
 class UndulatorPhaseAxes(UndulatorLockedPhaseAxes[Apple2PhasesVal]):
-    """
-    A collection of 4 phase Motor to make up the full id phase motion. We are using the diamond pv convention.
-    e.g. top_outer == Q1
-         top_inner == Q2
-         btm_inner == q3
-         btm_outer == q4
+    """A collection of 4 phase Motor to make up the full id phase motion. We are using
+    the diamond PV convention. e.g.::
 
-    """
+        top_outer == Q1
+        top_inner == Q2
+        btm_inner == q3
+        btm_outer == q4
+    """  # noqa D415
 
     def __init__(
         self,
@@ -333,9 +321,8 @@ class UndulatorPhaseAxes(UndulatorLockedPhaseAxes[Apple2PhasesVal]):
 
 
 class UndulatorJawPhase(SafeUndulatorMover[float]):
-    """
-    A JawPhase movable, this is use for moving the jaw phase which is use to control the
-    linear arbitrary polarisation but only on some of the beamline.
+    """A JawPhase movable, this is use for moving the jaw phase which is use to control
+    the linear arbitrary polarisation but only on some of the beamline.
     """
 
     def __init__(
@@ -357,8 +344,8 @@ class UndulatorJawPhase(SafeUndulatorMover[float]):
         await self.jaw_phase.user_setpoint.set(value=str(value))
 
     async def get_timeout(self) -> float:
-        """
-        Get motor speed, current position and target position to calculate required timeout.
+        """Get motor speed, current position and target position to calculate required
+        timeout.
         """
         return await estimate_motor_timeout(
             self.jaw_phase.user_setpoint_readback,
@@ -371,29 +358,20 @@ PhaseAxesType = TypeVar("PhaseAxesType", bound=UndulatorLockedPhaseAxes)
 
 
 class Apple2(StandardReadable, Movable[Apple2Val], Generic[PhaseAxesType]):
-    """
-    Device representing the combined motor controls for an Apple2 undulator.
-
-    Attributes
-    ----------
-    gap : UndulatorGap
-        The undulator gap motor device.
-    phase : UndulatorPhaseAxes
-        The undulator phase axes device, consisting of four phase motors.
+    """Device representing the combined motor controls for an Apple2 undulator.
+
+    Attributes:
+        gap (UndulatorGap): The undulator gap motor device.
+        phase (UndulatorPhaseAxes): The undulator phase axes device, consisting of four
+            phase motors.
+
+    Args:
+        id_gap (UndulatorGap): An UndulatorGap device.
+        id_phase (UndulatorPhaseAxes): An UndulatorPhaseAxes device.
+        name (str, optional): Name of the device.
     """
 
     def __init__(self, id_gap: UndulatorGap, id_phase: PhaseAxesType, name=""):
-        """
-        Parameters
-        ----------
-
-        id_gap: UndulatorGap
-            An UndulatorGap device.
-        id_phase: UndulatorPhaseAxes
-            An UndulatorPhaseAxes device.
-        name: str
-            Name of the device.
-        """
         with self.add_children_as_readables():
             self.gap = Reference(id_gap)
             self.phase = Reference(id_phase)
@@ -401,11 +379,9 @@ class Apple2(StandardReadable, Movable[Apple2Val], Generic[PhaseAxesType]):
 
     @AsyncStatus.wrap
     async def set(self, id_motor_values: Apple2Val) -> None:
+        """Check ID is in a movable state and set all the demand value before moving
+        them all at the same time.
         """
-        Check ID is in a movable state and set all the demand value before moving them
-        all at the same time.
-        """
-
         # Only need to check gap as the phase motors share both status and gate with gap.
         await self.gap().raise_if_cannot_move()