STARBackend can_reach_position and ensure_can_reach_position (#739)

Author: rickwierenga

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

@@ -48,6 +48,7 @@
   MultiHeadDispensePlate,
   Pickup,
   PickupTipRack,
+  PipettingOp,
   ResourceDrop,
   ResourceMove,
   ResourcePickup,
@@ -1180,6 +1181,8 @@ def __init__(
 
     self._iswap_version: Optional[str] = None  # loaded lazily
 
+    self._setup_done = False
+
   @property
   def unsafe(self) -> "UnSafe":
     """Actions that have a higher risk of damaging the robot. Use with care!"""
@@ -1452,8 +1455,51 @@ async def set_up_arm_modules():
     # the core grippers.
     self._core_parked = True
 
+    self._setup_done = True
+
+  async def stop(self):
+    await super().stop()
+    self._setup_done = False
+
+  @property
+  def setup_done(self) -> bool:
+    return self._setup_done
+
   # ============== LiquidHandlerBackend methods ==============
 
+  def can_reach_position(self, channel_idx: int, position: Coordinate) -> bool:
+    """Check if a position is reachable by a channel (center-based)."""
+    if not (0 <= channel_idx < self.num_channels):
+      raise ValueError(f"Channel {channel_idx} is out of range for this robot.")
+
+    # frontmost channel can go to y=6, every channel after that is about 8.9 mm further back
+    min_y_pos = 6 + 8.9 * (self.num_channels - channel_idx - 1)
+    if position.y < min_y_pos:
+      return False
+
+    # backmost channel can go to y=601.6, every channel before that is about 8.9 mm further forward
+    max_y_pos = 601.6 - 8.9 * channel_idx
+    if position.y > max_y_pos:
+      return False
+
+    return True
+
+  def ensure_can_reach_position(
+    self, use_channels: List[int], ops: Sequence[PipettingOp], op_name: str
+  ):
+    locs = [(op.resource.get_location_wrt(self.deck, y="c") + op.offset) for op in ops]
+    cant_reach = [
+      channel_idx
+      for channel_idx, loc in zip(use_channels, locs)
+      if not self.can_reach_position(channel_idx, loc)
+    ]
+    if len(cant_reach) > 0:
+      raise ValueError(
+        f"Channels {cant_reach} cannot reach their target positions in '{op_name}' operation.\n"
+        "Robots with more than 8 channels have limited Y-axis reach per channel; they don't have random access to the full deck area.\n"
+        "Try the operation with different channels or a different target position (i.e. different labware placement)."
+      )
+
   async def pick_up_tips(
     self,
     ops: List[Pickup],
@@ -1465,6 +1511,8 @@ async def pick_up_tips(
   ):
     """Pick up tips from a resource."""
 
+    self.ensure_can_reach_position(use_channels, ops, "pick_up_tips")
+
     x_positions, y_positions, channels_involved = self._ops_to_fw_positions(ops, use_channels)
 
     tip_spots = [op.resource for op in ops]
@@ -1538,6 +1586,8 @@ async def drop_tips(
         default if *all* tips are being dropped to a tip spot.
     """
 
+    self.ensure_can_reach_position(use_channels, ops, "drop_tips")
+
     if drop_method is None:
       if any(not isinstance(op.resource, TipSpot) for op in ops):
         drop_method = TipDropMethod.PLACE_SHIFT
@@ -1812,6 +1862,8 @@ async def aspirate(
       )
     # # # delete # # #
 
+    self.ensure_can_reach_position(use_channels, ops, "aspirate")
+
     x_positions, y_positions, channels_involved = self._ops_to_fw_positions(ops, use_channels)
 
     n = len(ops)
@@ -2169,6 +2221,8 @@ async def dispense(
       auto_surface_following_distance: automatically compute the surface following distance based on the container height<->volume functions. Requires liquid height to be specified or `probe_liquid_height=True`.
     """
 
+    self.ensure_can_reach_position(use_channels, ops, "dispense")
+
     n = len(ops)
 
     if jet is None: