Add container no-go zones with spread-aware channel distribution

docs/user_guide/00_liquid-handling/_liquid-handling.rst

@@ -24,3 +24,4 @@ Examples:
    moving-channels-around
    tutorial_tip_inventory_consolidation
    mixing
+   container_no_go_zones

pylabrobot/liquid_handling/backends/backend.py

@@ -3,6 +3,7 @@
 from abc import ABCMeta, abstractmethod
 from typing import Dict, List, Optional, Union
 
+from pylabrobot.liquid_handling.channel_positioning import GENERIC_LH_MIN_SPACING_BETWEEN_CHANNELS
 from pylabrobot.liquid_handling.standard import (
   Drop,
   DropTipRack,
@@ -158,6 +159,27 @@ async def request_tip_presence(self) -> List[Optional[bool]]:
 
     raise NotImplementedError()
 
+  def get_channel_spacings(self, use_channels: List[int]) -> List[float]:
+    """Get the per-channel occupancy diameter for each channel being used.
+
+    Each value is the channel's occupancy diameter - the physical space it takes up.
+    The required center-to-center distance between two adjacent channels is the sum of
+    their radii: ``spacing[i]/2 + spacing[j]/2``.
+
+    Args:
+      use_channels: The channels being used, in order.
+
+    Returns:
+      List of per-channel occupancy diameters (mm), length = ``len(use_channels)``.
+      Defaults to ``GENERIC_LH_MIN_SPACING_BETWEEN_CHANNELS`` (9mm) for all channels.
+      Backends with variable channel spacing should override this.
+
+    Note: This assumes channels spread along Y. Backends where channels are fixed in Y
+    (e.g. OT2 with 2 channels at fixed X spacing) should either override this or
+    signal that Y-spread is not supported via a ``supports_y_spread`` property.
+    """
+    return [GENERIC_LH_MIN_SPACING_BETWEEN_CHANNELS] * len(use_channels)
+
   @abstractmethod
   def can_pick_up_tip(self, channel_idx: int, tip: Tip) -> bool:
     """Check if the tip can be picked up by the specified channel. Does not consider

pylabrobot/liquid_handling/backends/hamilton/STAR_backend.py

@@ -3,7 +3,6 @@
 import enum
 import functools
 import logging
-import math
 import re
 import sys
 import warnings
@@ -40,6 +39,11 @@
 )
 from pylabrobot.liquid_handling.backends.hamilton.common import fill_in_defaults
 from pylabrobot.liquid_handling.backends.hamilton.planning import group_by_x_batch_by_xy
+from pylabrobot.liquid_handling.channel_positioning import (
+  MIN_SPACING_EDGE,
+  get_tight_single_resource_liquid_op_offsets,
+  get_wide_single_resource_liquid_op_offsets,
+)
 from pylabrobot.liquid_handling.errors import ChannelizedError
 from pylabrobot.liquid_handling.liquid_classes.hamilton import (
   HamiltonLiquidClass,
@@ -62,11 +66,6 @@
   SingleChannelAspiration,
   SingleChannelDispense,
 )
-from pylabrobot.liquid_handling.utils import (
-  MIN_SPACING_EDGE,
-  get_tight_single_resource_liquid_op_offsets,
-  get_wide_single_resource_liquid_op_offsets,
-)
 from pylabrobot.resources import (
   Carrier,
   Container,
@@ -1358,15 +1357,16 @@ def __init__(
     self._setup_done = False
 
   def _min_spacing_between(self, i: int, j: int) -> float:
-    """Return the conservative minimum Y spacing required between channels *i* and *j*.
-
-    For adjacent channels, the constraint is the larger of the two channels' individual minimum
-    spacings, ceiling'd to 1 decimal place for safe movement.
+    """Return the firmware-safe minimum Y spacing between channels *i* and *j*.
 
-    For non-adjacent channels, the spacing is the sum of all intermediate adjacent-pair spacings.
+    Uses max() of both channels' spacings for firmware safety (conservative).
+    For adjacent channels, ceiling-rounded to 0.1mm.
+    For non-adjacent channels, the sum of all intermediate adjacent-pair spacings.
     """
     lo, hi = min(i, j), max(i, j)
     if hi - lo == 1:
+      import math
+
       spacing = max(self._channels_minimum_y_spacing[lo], self._channels_minimum_y_spacing[hi])
       return math.ceil(spacing * 10) / 10
     return sum(self._min_spacing_between(k, k + 1) for k in range(lo, hi))
@@ -2214,10 +2214,6 @@ def _compute_channels_in_resource_locations(
           )
           min_ch = min(use_channels)
           offsets = [all_offsets[ch - min_ch] for ch in use_channels]
-
-          if num_channels_in_span % 2 != 0:
-            y_offset = 5.5
-            offsets = [offset + Coordinate(0, y_offset, 0) for offset in offsets]
         # else: container too small to fit all channels — fall back to center offsets.
         # Y sub-batching will serialize channels that can't coexist.
 
@@ -2328,8 +2324,8 @@ async def probe_liquid_heights(
     Notes:
       - All specified channels must have tips attached
       - Containers at different X positions are probed in sequential groups (single X carriage)
-      - For single containers with odd channel counts, Y-offsets are applied to avoid
-        center dividers (Hamilton 1000 uL spacing: 9mm, offset: 5.5mm)
+      - For single containers with no-go zones, Y-offsets are computed to avoid
+        obstructed regions (e.g. center dividers in troughs)
     """
 
     if move_to_z_safety_after is not None:
@@ -4548,9 +4544,9 @@ async def move_channel_z(self, channel: int, z: float):
     stop disk Z position used with :meth:`move_channel_stop_disk_z` for the same
     physical height above the deck.
     """
-    # TODO: remove after 2026-09
+    # TODO: remove in v1
     warnings.warn(
-      "move_channel_z is deprecated and will be removed after 2026-09 in legacy PLR. "
+      "move_channel_z is deprecated and will be removed in v1. "
       "Use move_channel_stop_disk_z() for moves without a tip attached "
       "or move_channel_tool_z() when a tip/tool is attached.",
       DeprecationWarning,
@@ -4677,6 +4673,9 @@ async def move_channel_z_relative(self, channel: int, distance: float):
     current_z = await self.request_z_pos_channel_n(channel)
     await self.move_channel_z(channel, current_z + distance)
 
+  def get_channel_spacings(self, use_channels: List[int]) -> List[float]:
+    return [self._channels_minimum_y_spacing[ch] for ch in sorted(use_channels)]
+
   def can_pick_up_tip(self, channel_idx: int, tip: Tip) -> bool:
     if not isinstance(tip, HamiltonTip):
       return False

pylabrobot/liquid_handling/backends/hamilton/planning.py

@@ -1,6 +1,6 @@
 from typing import Callable, Dict, List
 
-from pylabrobot.liquid_handling.utils import MIN_SPACING_BETWEEN_CHANNELS
+from pylabrobot.liquid_handling.channel_positioning import MIN_SPACING_BETWEEN_CHANNELS
 from pylabrobot.resources import Coordinate