dae

Author: Tom-Willemsen

src/ibex_bluesky_core/devices/block.py

@@ -147,16 +147,23 @@ def __init__(self, prefix: str, name: str = "") -> None:
         with self.add_children_as_readables(StandardReadableFormat.HINTED_SIGNAL):
             # When explicitly reading run control, the most obvious signal that people will be
             # interested in is whether the block is in range or not.
-            self.in_range = epics_signal_r(bool, f"{prefix}INRANGE")
+            self.in_range: SignalR[bool] = epics_signal_r(bool, f"{prefix}INRANGE")
+            """Whether run-control is currently in-range."""
 
-        self.low_limit = epics_signal_rw(float, f"{prefix}LOW")
-        self.high_limit = epics_signal_rw(float, f"{prefix}HIGH")
+        self.low_limit: SignalRW[float] = epics_signal_rw(float, f"{prefix}LOW")
+        """Run-control low limit."""
+        self.high_limit: SignalRW[float] = epics_signal_rw(float, f"{prefix}HIGH")
+        """Run-control high limit."""
 
-        self.suspend_if_invalid = epics_signal_rw(bool, f"{prefix}SOI")
-        self.enabled = epics_signal_rw(bool, f"{prefix}ENABLE")
+        self.suspend_if_invalid: SignalRW[bool] = epics_signal_rw(bool, f"{prefix}SOI")
+        """Whether run-control should suspend data collection on invalid values."""
+        self.enabled: SignalRW[bool] = epics_signal_rw(bool, f"{prefix}ENABLE")
+        """Run-control enabled."""
 
-        self.out_time = epics_signal_r(float, f"{prefix}OUT:TIME")
-        self.in_time = epics_signal_r(float, f"{prefix}IN:TIME")
+        self.out_time: SignalR[float] = epics_signal_r(float, f"{prefix}OUT:TIME")
+        """Run-control time outside limits."""
+        self.in_time: SignalR[float] = epics_signal_r(float, f"{prefix}IN:TIME")
+        """Run-control time inside limits."""
 
         super().__init__(name=name)
 
@@ -176,9 +183,11 @@ def __init__(self, datatype: type[T], prefix: str, block_name: str) -> None:
         """
         with self.add_children_as_readables(StandardReadableFormat.HINTED_SIGNAL):
             self.readback: SignalR[T] = epics_signal_r(datatype, f"{prefix}CS:SB:{block_name}")
+            """Readback value. This is the hinted signal for a block."""
 
         # Run control doesn't need to be read by default
-        self.run_control = RunControl(f"{prefix}CS:SB:{block_name}:RC:")
+        self.run_control: RunControl = RunControl(f"{prefix}CS:SB:{block_name}:RC:")
+        """Run-control settings for this block."""
 
         super().__init__(name=block_name)
         self.readback.set_name(block_name)
@@ -243,6 +252,7 @@ def plan():
         self.setpoint: SignalRW[T] = epics_signal_rw(
             datatype, f"{prefix}CS:SB:{block_name}{sp_suffix}"
         )
+        """The setpoint for this block."""
 
         self._write_config: BlockWriteConfig[T] = write_config or BlockWriteConfig()
 
@@ -360,6 +370,7 @@ def __init__(
             self.setpoint_readback: SignalR[T] = epics_signal_r(
                 datatype, f"{prefix}CS:SB:{block_name}:SP:RBV"
             )
+            """The setpoint-readback for this block."""
 
         super().__init__(
             datatype=datatype, prefix=prefix, block_name=block_name, write_config=write_config
@@ -413,34 +424,37 @@ def __init__(
     ) -> None:
         """Create a new motor-record block.
 
-        The 'BlockMot' object supports motion-specific functionality such as:
+        The ``BlockMot`` object supports motion-specific functionality such as:
 
-        - Stopping if a scan is aborted (supports the bluesky 'Stoppable' protocol)
-        - Limit checking (before a move starts - supports the bluesky 'Checkable' protocol)
+        - Stopping if a scan is aborted (supports the bluesky
+          :py:obj:`~bluesky.protocols.Stoppable` protocol)
+        - Limit checking (before a move starts - supports the bluesky
+          :py:obj:`~bluesky.protocols.Checkable` protocol)
         - Automatic calculation of move timeouts based on motor velocity
         - Fly scanning
 
         However, it generally relies on the underlying motor being "well-behaved". For example, a
         motor which does many retries may exceed the simple default timeout based on velocity (it
         is possible to explicitly specify a timeout on set() to override this).
 
-        Blocks pointing at motors do not take a BlockWriteConfiguration parameter, as these
+        Blocks pointing at motors do not take a
+        :py:obj:`~ibex_bluesky_core.devices.block.BlockWriteConfig` parameter, as these
         parameters duplicate functionality which already exists in the motor record. The mapping is:
 
         use_completion_callback:
             Motors always use completion callbacks to check whether motion has completed. Whether to
             wait on that completion callback can be configured by the 'wait' keyword argument on
             set().
         set_success_func:
-            Use .RDBD and .RTRY to control motor retries if the position has not been reached to
-            within a specified tolerance. Note that motors which retry a lot may exceed the default
-            motion timeout which is calculated based on velocity, distance and acceleration.
+            Use ``.RDBD`` and ``.RTRY`` to control motor retries if the position has not been
+            reached to within a specified tolerance. Note that motors which retry a lot may
+            exceed the default motion timeout which is calculated based on velocity,
+            distance and acceleration.
         set_timeout_s:
             A suitable timeout is calculated automatically based on velocity, distance and
-            acceleration as defined on the motor record. This may be overridden by the 'timeout'
-            keyword-argument on set().
+            acceleration as defined on the motor record.
         settle_time_s:
-            Use .DLY on the motor record to configure this.
+            Use ``.DLY`` on the motor record to configure this.
         use_global_moving_flag:
             This is unnecessary for a single motor block, as a completion callback will always be
             used instead to detect when a single move has finished.

src/ibex_bluesky_core/devices/dae/__init__.py

@@ -83,6 +83,10 @@ class DaeCheckingSignal(StandardReadable, Movable[T], Generic[T]):
     def __init__(self, datatype: type[T], prefix: str) -> None:
         """Device that wraps a signal and checks the result of a set.
 
+        This ensures that the DAE has accepted a configuration change, ensuring that
+        runs are not accidentally started in an unwanted configuration if the DAE does
+        not accept new settings.
+
         Args:
             datatype: The datatype of the signal.
             prefix: The PV address of the signal.
@@ -95,11 +99,14 @@ def __init__(self, datatype: type[T], prefix: str) -> None:
 
     @AsyncStatus.wrap
     async def set(self, value: T) -> None:
-        """Check a signal when it is set. Raises if not set.
+        """Set and check a signal.
 
         Args:
             value: the value to set.
 
+        Raises:
+            OSError: If the signal failed to be set to the specified value.
+
         """
         await self.signal.set(value, wait=True, timeout=None)
         actual_value = await self.signal.get_value()
@@ -113,20 +120,35 @@ class RunstateEnum(StrictEnum):
     """The run state."""
 
     PROCESSING = "PROCESSING"
+    """Processing state."""
     SETUP = "SETUP"
+    """Setup (idle) state."""
     RUNNING = "RUNNING"
+    """Running state."""
     PAUSED = "PAUSED"
+    """Paused state."""
     WAITING = "WAITING"
+    """Waiting state (running blocked by run control)."""
     VETOING = "VETOING"
+    """Vetoing state (running blocked by hardware signal)."""
     ENDING = "ENDING"
+    """Ending state."""
     SAVING = "SAVING"
+    """Saving state."""
     RESUMING = "RESUMING"
+    """Resuming state."""
     PAUSING = "PAUSING"
+    """Pausing state."""
     BEGINNING = "BEGINNING"
+    """Beginning state."""
     ABORTING = "ABORTING"
+    """Aborting state."""
     UPDATING = "UPDATING"
+    """Updating state."""
     STORING = "STORING"
+    """Storing state."""
     CHANGING = "CHANGING"
+    """Changing state."""
 
     def __str__(self) -> str:
         """Return a string representation of the enum value."""
@@ -137,7 +159,16 @@ class Dae(StandardReadable):
     """Device representing the ISIS data acquisition electronics."""
 
     def __init__(self, prefix: str, name: str = "DAE") -> None:
-        """Create a new Dae ophyd-async device."""
+        """Device representing the full interface to the ISIS data acquisition electronics.
+
+        .. warning::
+
+            This class exposes underlying DAE functionality behaviour to bluesky, but has no
+            configured behaviour. A raw ``Dae`` object is therefore unsuitable for use in a scan.
+
+            To use the DAE in a scan, use a subclass such as
+            :py:obj:`~ibex_bluesky_core.devices.simpledae.SimpleDae`.
+        """
         dae_prefix = f"{prefix}DAE:"
         self._prefix = prefix
         self.good_uah: SignalR[float] = epics_signal_r(float, f"{dae_prefix}GOODUAH")
@@ -244,7 +275,6 @@ async def trigger_and_get_specdata(
         settings. The returned array will not include the "junk" time-channel 0.
 
         Args:
-            dae: The SimpleDae instance
             detectors: a numpy array or slice describing detectors to get data from.
                 Default is all detectors.
                 Pass np.array([1]) to select detector 1.

src/ibex_bluesky_core/devices/dae/_controls.py

@@ -11,43 +11,92 @@
 
 
 class DaeControls(StandardReadable):
-    """Subdevice for the DAE run controls."""
+    """DAE run control signals."""
 
     def __init__(self, dae_prefix: str, name: str = "") -> None:
-        """Set up write-only signals for DAE controls."""
+        """DAE run controls, for example to begin and end runs."""
         self.begin_run: SignalX = epics_signal_x(f"{dae_prefix}BEGINRUN")
+        """
+        Begin a run.
+        """
         self.begin_run_ex: BeginRunEx = BeginRunEx(dae_prefix)
+        """
+        Begin a run, with options.
+        """
         self.end_run: SignalX = epics_signal_x(f"{dae_prefix}ENDRUN")
+        """
+        End a run.
+        """
         self.pause_run: SignalX = epics_signal_x(f"{dae_prefix}PAUSERUN")
+        """
+        Pause the current run.
+        """
         self.resume_run: SignalX = epics_signal_x(f"{dae_prefix}RESUMERUN")
+        """
+        Resume the current run.
+        """
         self.abort_run: SignalX = epics_signal_x(f"{dae_prefix}ABORTRUN")
+        """
+        Abort the current run (does not save data files).
+        """
         self.recover_run: SignalX = epics_signal_x(f"{dae_prefix}RECOVERRUN")
+        """
+        Recover a previously-aborted run.
+        """
         self.save_run: SignalX = epics_signal_x(f"{dae_prefix}SAVERUN")
+        """
+        Save a data file for the current run (equivalent to update & store).
+        """
         self.update_run: SignalX = epics_signal_x(f"{dae_prefix}UPDATERUN")
+        """
+        Ensure that data in the DAE has been downloaded to the ICP.
+        """
         self.store_run: SignalX = epics_signal_x(f"{dae_prefix}STORERUN")
+        """
+        Write data currently in-memory in the ICP to a data file.
+        """
 
         super().__init__(name=name)
 
 
 class BeginRunExBits(IntFlag):
-    """Bits for BEGINRUNEX."""
+    """Bit-flags for :py:obj:`BeginRunEx`.
+
+    These flags control behaviour such as beginning in 'paused' mode.
+    """
 
     NONE = 0
+    """
+    Begin a run in the standard way.
+    """
+
     BEGIN_PAUSED = 1
+    """
+    Begin a run in the 'paused' state.
+    """
+
     BEGIN_DELAYED = 2
+    """
+    Allow 'delayed' begin commands.
+    """
 
 
 class BeginRunEx(StandardReadable, Movable[BeginRunExBits]):
-    """Subdevice for the BEGINRUNEX signal to begin a run."""
+    """Subdevice for the ``BEGINRUNEX`` signal to begin a run."""
 
     def __init__(self, dae_prefix: str, name: str = "") -> None:
-        """Set up write-only signal for BEGINRUNEX."""
+        """Set up write-only signal for ``BEGINRUNEX``."""
         self._raw_begin_run_ex: SignalW[int] = epics_signal_w(int, f"{dae_prefix}BEGINRUNEX")
         super().__init__(name=name)
 
     @AsyncStatus.wrap
     async def set(self, value: BeginRunExBits) -> None:
-        """Start a run with the specified bits - See BeginRunExBits."""
+        """Start a run with the specified behaviour flags.
+
+        See Also:
+            :py:obj:`BeginRunExBits` for a description of the behaviour flags.
+
+        """
         logger.info("starting run with options %s", value)
         await self._raw_begin_run_ex.set(value, wait=True, timeout=None)
         logger.info("start run complete")

src/ibex_bluesky_core/devices/dae/_event_mode.py

@@ -8,9 +8,24 @@ class DaeEventMode(StandardReadable):
     """Subdevice for event mode statistics."""
 
     def __init__(self, dae_prefix: str, name: str = "") -> None:
-        """Set up signals for DAE event mode statistics."""
+        """DAE event mode statistics."""
         self.fraction: SignalR[float] = epics_signal_r(float, f"{dae_prefix}EVENTMODEFRACTION")
+        """
+        Event mode fraction.
+
+        1 is full event mode, 0 is full histogram mode. Values between 0 and 1 imply that
+        some spectra are in event mode and others are in histogram mode.
+        """
         self.buf_used: SignalR[float] = epics_signal_r(float, f"{dae_prefix}EVENTMODEBUFUSED")
+        """
+        Event mode buffer used fraction.
+        """
         self.file_size: SignalR[float] = epics_signal_r(float, f"{dae_prefix}EVENTMODEFILEMB")
+        """
+        Event mode file size (MB).
+        """
         self.data_rate: SignalR[float] = epics_signal_r(float, f"{dae_prefix}EVENTMODEDATARATE")
+        """
+        Event mode data rate (MB/s).
+        """
         super().__init__(name=name)

src/ibex_bluesky_core/devices/dae/_monitor.py

@@ -8,10 +8,14 @@ class DaeMonitor(StandardReadable):
     """Subdevice for the current monitor."""
 
     def __init__(self, dae_prefix: str, name: str = "") -> None:
-        """Set up signals for the current DAE monitor."""
-        self.spectrum: SignalR[int] = epics_signal_r(int, f"{dae_prefix}MONITORCOUNTS")
-        self.counts: SignalR[int] = epics_signal_r(int, f"{dae_prefix}MONITORSPECTRUM")
+        """DAE monitor statistics and diagnostics."""
+        self.spectrum: SignalR[int] = epics_signal_r(int, f"{dae_prefix}MONITORSPECTRUM")
+        """Monitor spectrum."""
+        self.counts: SignalR[int] = epics_signal_r(int, f"{dae_prefix}MONITORCOUNTS")
+        """Monitor counts."""
         self.to: SignalR[float] = epics_signal_r(float, f"{dae_prefix}MONITORTO")
+        """Monitor integration upper bound (us)."""
         self.from_: SignalR[float] = epics_signal_r(float, f"{dae_prefix}MONITORFROM")
+        """Monitor integration lower bound (us)."""
 
         super().__init__(name=name)

src/ibex_bluesky_core/devices/dae/_period.py

@@ -8,12 +8,18 @@ class DaePeriod(StandardReadable):
     """Subdevice for the current DAE period."""
 
     def __init__(self, dae_prefix: str, name: str = "") -> None:
-        """Set up signals for the current DAE period."""
+        """DAE statistics and diagnostics for the current DAE period."""
         self.run_duration: SignalR[int] = epics_signal_r(int, f"{dae_prefix}RUNDURATION_PD")
+        """Run duration (seconds) in the current DAE period."""
         self.good_frames: SignalR[int] = epics_signal_r(int, f"{dae_prefix}GOODFRAMES_PD")
+        """DAE good frames in the current DAE period."""
         self.raw_frames: SignalR[int] = epics_signal_r(int, f"{dae_prefix}RAWFRAMES_PD")
+        """DAE raw frames in the current DAE period."""
         self.good_uah: SignalR[float] = epics_signal_r(float, f"{dae_prefix}GOODUAH_PD")
+        """DAE good uAh in the current DAE period."""
         self.type: SignalR[str] = epics_signal_r(str, f"{dae_prefix}PERIODTYPE")
+        """DAE period type."""
         self.sequence: SignalR[int] = epics_signal_r(int, f"{dae_prefix}PERIODSEQ")
+        """DAE period sequence."""
 
         super().__init__(name=name)