opentrons 8.6.0a1__py3-none-any.whl

opentrons/motion_planning/__init__.py

@@ -0,0 +1,32 @@
+"""Motion planning module."""
+
+from .waypoints import (
+    DEFAULT_GENERAL_ARC_Z_MARGIN,
+    DEFAULT_IN_LABWARE_ARC_Z_MARGIN,
+    MINIMUM_Z_MARGIN,
+    get_waypoints,
+    get_gripper_labware_movement_waypoints,
+    get_gripper_labware_placement_waypoints,
+)
+
+from .types import Waypoint, MoveType
+
+from .errors import (
+    MotionPlanningError,
+    DestinationOutOfBoundsError,
+    ArcOutOfBoundsError,
+)
+
+__all__ = [
+    "DEFAULT_GENERAL_ARC_Z_MARGIN",
+    "DEFAULT_IN_LABWARE_ARC_Z_MARGIN",
+    "MINIMUM_Z_MARGIN",
+    "Waypoint",
+    "MoveType",
+    "MotionPlanningError",
+    "DestinationOutOfBoundsError",
+    "ArcOutOfBoundsError",
+    "get_waypoints",
+    "get_gripper_labware_movement_waypoints",
+    "get_gripper_labware_placement_waypoints",
+]

opentrons/motion_planning/adjacent_slots_getters.py

@@ -0,0 +1,168 @@
+"""Getters for specific adjacent slots."""
+from dataclasses import dataclass
+from typing import Optional, List, Dict, Union
+
+from opentrons_shared_data.robot.types import RobotType
+
+from opentrons.types import DeckSlotName, StagingSlotName
+
+
+def get_north_slot(slot: int) -> Optional[int]:
+    """Get slot north of the given slot."""
+    if slot in [10, 11, 12]:
+        return None
+    else:
+        return slot + 3
+
+
+def get_south_slot(slot: int) -> Optional[int]:
+    """Get slot south of the given slot."""
+    if slot in [1, 2, 3]:
+        return None
+    else:
+        return slot - 3
+
+
+def get_east_slot(slot: int) -> Optional[int]:
+    """Get slot east of the given slot."""
+    if slot in [3, 6, 9, 12]:
+        return None
+    else:
+        return slot + 1
+
+
+def get_west_slot(slot: int) -> Optional[int]:
+    """Get slot west of the given slot."""
+    if slot in [1, 4, 7, 10]:
+        return None
+    else:
+        return slot - 1
+
+
+def get_north_west_slot(slot: int) -> Optional[int]:
+    """Get the slot that's north-west of the given slot."""
+    if slot in [1, 4, 7, 10, 11, 12]:
+        return None
+    else:
+        north_slot = get_north_slot(slot)
+        return north_slot - 1 if north_slot else None
+
+
+def get_north_east_slot(slot: int) -> Optional[int]:
+    """Get the slot that's north-east of the given slot."""
+    if slot in [3, 6, 9, 10, 11, 12]:
+        return None
+    else:
+        north_slot = get_north_slot(slot)
+        return north_slot + 1 if north_slot else None
+
+
+def get_south_west_slot(slot: int) -> Optional[int]:
+    """Get the slot that's south-west of the given slot."""
+    if slot in [1, 2, 3, 4, 7, 10]:
+        return None
+    else:
+        south_slot = get_south_slot(slot)
+        return south_slot - 1 if south_slot else None
+
+
+def get_south_east_slot(slot: int) -> Optional[int]:
+    """Get the slot that's south-east of the given slot."""
+    if slot in [1, 2, 3, 6, 9, 12]:
+        return None
+    else:
+        south_slot = get_south_slot(slot)
+        return south_slot + 1 if south_slot else None
+
+
+@dataclass
+class _MixedTypeSlots:
+    regular_slots: List[DeckSlotName]
+    staging_slots: List[StagingSlotName]
+
+
+def get_surrounding_slots(slot: int, robot_type: RobotType) -> _MixedTypeSlots:
+    """Get all the surrounding slots, i.e., adjacent slots as well as corner slots."""
+    corner_slots: List[Union[int, None]] = [
+        get_north_east_slot(slot),
+        get_north_west_slot(slot),
+        get_south_east_slot(slot),
+        get_south_west_slot(slot),
+    ]
+
+    surrounding_regular_slots_int = get_adjacent_slots(slot) + [
+        maybe_slot for maybe_slot in corner_slots if maybe_slot is not None
+    ]
+    surrounding_regular_slots = [
+        DeckSlotName.from_primitive(slot_int).to_equivalent_for_robot_type(robot_type)
+        for slot_int in surrounding_regular_slots_int
+    ]
+    surrounding_staging_slots = _SURROUNDING_STAGING_SLOTS_MAP.get(
+        DeckSlotName.from_primitive(slot).to_equivalent_for_robot_type(robot_type), []
+    )
+    return _MixedTypeSlots(
+        regular_slots=surrounding_regular_slots, staging_slots=surrounding_staging_slots
+    )
+
+
+_WEST_OF_STAGING_SLOT_MAP: Dict[StagingSlotName, DeckSlotName] = {
+    StagingSlotName.SLOT_A4: DeckSlotName.SLOT_A3,
+    StagingSlotName.SLOT_B4: DeckSlotName.SLOT_B3,
+    StagingSlotName.SLOT_C4: DeckSlotName.SLOT_C3,
+    StagingSlotName.SLOT_D4: DeckSlotName.SLOT_D3,
+}
+
+_EAST_OF_FLEX_COLUMN_3_MAP: Dict[DeckSlotName, StagingSlotName] = {
+    deck_slot: staging_slot
+    for staging_slot, deck_slot in _WEST_OF_STAGING_SLOT_MAP.items()
+}
+
+
+_SURROUNDING_STAGING_SLOTS_MAP: Dict[DeckSlotName, List[StagingSlotName]] = {
+    DeckSlotName.SLOT_D3: [StagingSlotName.SLOT_C4, StagingSlotName.SLOT_D4],
+    DeckSlotName.SLOT_C3: [
+        StagingSlotName.SLOT_B4,
+        StagingSlotName.SLOT_C4,
+        StagingSlotName.SLOT_D4,
+    ],
+    DeckSlotName.SLOT_B3: [
+        StagingSlotName.SLOT_A4,
+        StagingSlotName.SLOT_B4,
+        StagingSlotName.SLOT_C4,
+    ],
+    DeckSlotName.SLOT_A3: [StagingSlotName.SLOT_A4, StagingSlotName.SLOT_B4],
+}
+
+
+def get_west_of_staging_slot(staging_slot: StagingSlotName) -> DeckSlotName:
+    """Get slot west of a staging slot."""
+    return _WEST_OF_STAGING_SLOT_MAP[staging_slot]
+
+
+def get_adjacent_staging_slot(deck_slot: DeckSlotName) -> Optional[StagingSlotName]:
+    """Get the adjacent staging slot if the deck slot is in the third column."""
+    return _EAST_OF_FLEX_COLUMN_3_MAP.get(deck_slot)
+
+
+def get_surrounding_staging_slots(deck_slot: DeckSlotName) -> List[StagingSlotName]:
+    """Get the staging slots surrounding the given deck slot."""
+    return _SURROUNDING_STAGING_SLOTS_MAP.get(deck_slot, [])
+
+
+def get_east_west_slots(slot: int) -> List[int]:
+    """Get slots east & west of the given slot."""
+    east = get_east_slot(slot)
+    west = get_west_slot(slot)
+    return [maybe_slot for maybe_slot in [east, west] if maybe_slot is not None]
+
+
+def get_north_south_slots(slot: int) -> List[int]:
+    """Get slots north & south of the given slot."""
+    north = get_north_slot(slot)
+    south = get_south_slot(slot)
+    return [maybe_slot for maybe_slot in [north, south] if maybe_slot is not None]
+
+
+def get_adjacent_slots(slot: int) -> List[int]:
+    """Get slots on the east, west, north and south of the given slot."""
+    return get_east_west_slots(slot) + get_north_south_slots(slot)

opentrons/motion_planning/deck_conflict.py

@@ -0,0 +1,396 @@
+"""Check a deck layout for conflicts."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Mapping, NamedTuple, Optional, Set, Union
+from typing_extensions import Final
+
+from opentrons_shared_data.labware.types import LabwareUri
+from opentrons_shared_data.robot.types import RobotType
+from opentrons.motion_planning.adjacent_slots_getters import (
+    get_east_west_slots,
+    get_south_slot,
+    get_adjacent_slots,
+    get_adjacent_staging_slot,
+)
+
+from opentrons.types import DeckSlotName, StagingSlotName
+
+_FIXED_TRASH_SLOT: Final[Set[DeckSlotName]] = {
+    DeckSlotName.FIXED_TRASH,
+    DeckSlotName.SLOT_A3,
+}
+
+
+# The maximum height allowed for items adjacent to a Heater-Shaker in the x-direction.
+# This value selected to avoid interference with the Heater-Shaker's labware latch.
+# For background, see: https://github.com/Opentrons/opentrons/issues/10316
+#
+# TODO(mc, 2022-06-16): move this constant to the module definition
+HS_MAX_X_ADJACENT_ITEM_HEIGHT = 53.0
+
+
+# URIs of labware that are allowed to exceed HS_MAX_X_ADJACENT_ITEM_HEIGHT.
+# These labware do not take up the full width of the slot
+# in the area that would interfere with the labware latch.
+# For background, see: https://github.com/Opentrons/opentrons/issues/10316
+#
+# TODO(mc, 2022-06-16): move this constant to the module definition
+HS_ALLOWED_ADJACENT_TALL_LABWARE = [
+    LabwareUri("opentrons/opentrons_96_filtertiprack_10ul/1"),
+    LabwareUri("opentrons/opentrons_96_filtertiprack_200ul/1"),
+    LabwareUri("opentrons/opentrons_96_filtertiprack_20ul/1"),
+    LabwareUri("opentrons/opentrons_96_tiprack_10ul/1"),
+    LabwareUri("opentrons/opentrons_96_tiprack_20ul/1"),
+    LabwareUri("opentrons/opentrons_96_tiprack_300ul/1"),
+]
+
+
+@dataclass
+class Labware:
+    """A normal labware that directly occupies a slot.
+
+    Do not use this to represent a labware that's loaded atop a module.
+    Use one of the module types, instead.
+    """
+
+    name_for_errors: str
+    highest_z: float
+    uri: LabwareUri
+    is_fixed_trash: bool
+
+
+@dataclass
+class TrashBin:
+    """A non-labware trash bin (loaded via api level 2.16 and above)."""
+
+    name_for_errors: str
+    highest_z: float
+
+
+@dataclass
+class _Module:
+    name_for_errors: str
+    highest_z_including_labware: float
+
+
+@dataclass
+class HeaterShakerModule(_Module):
+    """A Heater-Shaker module."""
+
+
+@dataclass
+class MagneticBlockModule(_Module):
+    """A Magnetic Block module."""
+
+
+@dataclass
+class ThermocyclerModule(_Module):
+    """A Thermocycler module."""
+
+    is_semi_configuration: bool
+    """Whether this Thermocycler is loaded in its "semi" configuration.
+
+    In this configuration, it's offset to the left, so it takes up fewer deck slots.
+    """
+
+
+@dataclass
+class OtherModule(_Module):
+    """A module that's not a Heater-Shaker or Thermocycler."""
+
+
+DeckItem = Union[
+    Labware,
+    HeaterShakerModule,
+    MagneticBlockModule,
+    ThermocyclerModule,
+    OtherModule,
+    TrashBin,
+]
+
+
+class _NothingAllowed(NamedTuple):
+    """Nothing is allowed in this slot."""
+
+    location: Union[DeckSlotName, StagingSlotName]
+    source_item: DeckItem
+    source_location: Union[DeckSlotName, StagingSlotName]
+
+    def is_allowed(self, item: DeckItem) -> bool:
+        return False
+
+
+class _MaxHeight(NamedTuple):
+    """Nothing over a certain height is allowed in this slot."""
+
+    location: DeckSlotName
+    source_item: DeckItem
+    source_location: DeckSlotName
+    max_height: float
+    allowed_labware: List[LabwareUri]
+
+    def is_allowed(self, item: DeckItem) -> bool:
+        if isinstance(item, Labware):
+            if item.uri in self.allowed_labware:
+                return True
+            else:
+                return item.highest_z < self.max_height
+        elif isinstance(item, _Module):
+            return item.highest_z_including_labware < self.max_height
+        elif isinstance(item, TrashBin):
+            return item.highest_z < self.max_height
+
+
+class _NoModule(NamedTuple):
+    """No module of any kind is allowed in this slot."""
+
+    location: DeckSlotName
+    source_item: DeckItem
+    source_location: DeckSlotName
+
+    def is_allowed(self, item: DeckItem) -> bool:
+        return not isinstance(item, _Module)
+
+
+class _NoHeaterShakerModule(NamedTuple):
+    """No Heater-Shaker module is allowed in this slot."""
+
+    location: DeckSlotName
+    source_item: DeckItem
+    source_location: DeckSlotName
+
+    def is_allowed(self, item: DeckItem) -> bool:
+        return not isinstance(item, HeaterShakerModule)
+
+
+_DeckRestriction = Union[
+    _NothingAllowed,
+    _MaxHeight,
+    _NoModule,
+    _NoHeaterShakerModule,
+]
+"""A restriction on what is allowed in a given slot."""
+
+
+class DeckConflictError(ValueError):
+    """Adding an item to the deck would cause a conflict."""
+
+
+# TODO(mm, 2023-02-16): Taking a single int as the deck location doesn't make sense for
+# things that don't fit into a single deck slot, like the Thermocycler.
+# Refactor this interface to take a more symbolic location.
+def check(
+    existing_items: Mapping[Union[DeckSlotName, StagingSlotName], DeckItem],
+    new_item: DeckItem,
+    new_location: Union[DeckSlotName, StagingSlotName],
+    robot_type: RobotType,
+) -> None:
+    """Check a deck layout for conflicts.
+
+    Args:
+        existing_items: Existing items on the deck, assumed to be valid.
+        new_item: New item to add to the deck.
+        new_location: Location where the new item will be added.
+        robot_type: The type of the robot to choose the restriction rules.
+
+    Raises:
+        DeckConflictError: Adding this item should not be allowed.
+    """
+    restrictions: List[_DeckRestriction] = []
+    # build restrictions driven by existing items
+    for location, item in existing_items.items():
+        restrictions += _create_restrictions(
+            item=item, location=location, robot_type=robot_type
+        )
+
+    # check new item against existing restrictions
+    for r in restrictions:
+        if r.location == new_location and not r.is_allowed(new_item):
+            raise DeckConflictError(
+                _create_deck_conflict_error_message(restriction=r, new_item=new_item)
+            )
+
+    # check new restrictions required by new item
+    # do not interfere with existing items
+    new_restrictions = _create_restrictions(
+        item=new_item, location=new_location, robot_type=robot_type
+    )
+
+    for r in new_restrictions:
+        existing_item = existing_items.get(r.location)
+        if existing_item is not None and not r.is_allowed(existing_item):
+            raise DeckConflictError(
+                _create_deck_conflict_error_message(
+                    restriction=r,
+                    existing_item=existing_item,
+                )
+            )
+
+
+def _create_ot2_restrictions(  # noqa: C901
+    item: DeckItem, location: Union[DeckSlotName, StagingSlotName]
+) -> List[_DeckRestriction]:
+    restrictions: List[_DeckRestriction] = []
+    if isinstance(location, StagingSlotName):
+        raise DeckConflictError(f"OT-2 does not support staging slots ({location.id}).")
+
+    if location not in _FIXED_TRASH_SLOT:
+        # Disallow a different item from overlapping this item in this deck slot.
+        restrictions.append(
+            _NothingAllowed(
+                location=location,
+                source_item=item,
+                source_location=location,
+            )
+        )
+
+    if _is_ot2_fixed_trash(item):
+        # A Heater-Shaker can't safely be placed just south of the fixed trash,
+        # because the fixed trash blocks access to the screw that locks the
+        # Heater-Shaker onto the deck.
+        location_south_of_fixed_trash = get_south_slot(location.as_int())
+        if location_south_of_fixed_trash is not None:
+            restrictions.append(
+                _NoHeaterShakerModule(
+                    location=DeckSlotName.from_primitive(location_south_of_fixed_trash),
+                    source_item=item,
+                    source_location=location,
+                )
+            )
+
+    if isinstance(item, ThermocyclerModule):
+        for covered_location in _ot2_slots_covered_by_thermocycler(item):
+            restrictions.append(
+                _NothingAllowed(
+                    location=covered_location,
+                    source_item=item,
+                    source_location=location,
+                )
+            )
+
+    if isinstance(item, HeaterShakerModule):
+        for hs_covered_location in get_adjacent_slots(location.as_int()):
+            restrictions.append(
+                _NoModule(
+                    location=DeckSlotName.from_primitive(hs_covered_location),
+                    source_item=item,
+                    source_location=location,
+                )
+            )
+
+        for hs_covered_location in get_east_west_slots(location.as_int()):
+            restrictions.append(
+                _MaxHeight(
+                    location=DeckSlotName.from_primitive(hs_covered_location),
+                    source_item=item,
+                    source_location=location,
+                    max_height=HS_MAX_X_ADJACENT_ITEM_HEIGHT,
+                    allowed_labware=HS_ALLOWED_ADJACENT_TALL_LABWARE,
+                )
+            )
+
+    return restrictions
+
+
+def _create_flex_restrictions(
+    item: DeckItem, location: Union[DeckSlotName, StagingSlotName]
+) -> List[_DeckRestriction]:
+    restrictions: List[_DeckRestriction] = [
+        _NothingAllowed(
+            location=location,
+            source_item=item,
+            source_location=location,
+        )
+    ]
+
+    if isinstance(item, (HeaterShakerModule, OtherModule)):
+        if isinstance(location, StagingSlotName):
+            raise DeckConflictError(
+                "Cannot have a module loaded on a staging area slot."
+            )
+        adjacent_staging_slot = get_adjacent_staging_slot(location)
+        if adjacent_staging_slot is not None:
+            # You can't have anything on a staging area slot next to a heater-shaker or
+            # temperature module because the module caddy physically blocks you from having
+            # that staging area slot installed in the first place.
+            restrictions.append(
+                _NothingAllowed(
+                    location=adjacent_staging_slot,
+                    source_item=item,
+                    source_location=location,
+                )
+            )
+
+    elif isinstance(item, ThermocyclerModule):
+        for covered_location in _flex_slots_covered_by_thermocycler():
+            restrictions.append(
+                _NothingAllowed(
+                    location=covered_location,
+                    source_item=item,
+                    source_location=location,
+                )
+            )
+
+    return restrictions
+
+
+def _create_restrictions(
+    item: DeckItem, location: Union[DeckSlotName, StagingSlotName], robot_type: str
+) -> List[_DeckRestriction]:
+
+    if robot_type == "OT-2 Standard":
+        return _create_ot2_restrictions(item, location)
+    else:
+        return _create_flex_restrictions(item, location)
+
+
+def _create_deck_conflict_error_message(
+    restriction: _DeckRestriction,
+    new_item: Optional[DeckItem] = None,
+    existing_item: Optional[DeckItem] = None,
+) -> str:
+    assert (
+        new_item is not None or existing_item is not None
+    ), "Conflict error expects either new_item or existing_item"
+
+    if new_item is not None:
+        message = (
+            f"{restriction.source_item.name_for_errors}"
+            f" in slot {restriction.source_location}"
+            f" prevents {new_item.name_for_errors}"
+            f" from using slot {restriction.location}."
+        )
+
+    elif existing_item is not None:
+        message = (
+            f"{existing_item.name_for_errors} in slot {restriction.location}"
+            f" prevents {restriction.source_item.name_for_errors}"
+            f" from using slot {restriction.source_location}."
+        )
+
+    return message
+
+
+def _ot2_slots_covered_by_thermocycler(
+    thermocycler: ThermocyclerModule,
+) -> Set[DeckSlotName]:
+    if thermocycler.is_semi_configuration:
+        return {DeckSlotName.SLOT_7, DeckSlotName.SLOT_10}
+    else:
+        return {
+            DeckSlotName.SLOT_7,
+            DeckSlotName.SLOT_10,
+            DeckSlotName.SLOT_8,
+            DeckSlotName.SLOT_11,
+        }
+
+
+def _flex_slots_covered_by_thermocycler() -> Set[DeckSlotName]:
+    return {DeckSlotName.SLOT_B1, DeckSlotName.SLOT_A1}
+
+
+def _is_ot2_fixed_trash(item: DeckItem) -> bool:
+    return (isinstance(item, Labware) and item.is_fixed_trash) or isinstance(
+        item, TrashBin
+    )

opentrons/motion_planning/errors.py

@@ -0,0 +1,35 @@
+"""Movement planning errors."""
+from opentrons.types import Point
+
+
+class MotionPlanningError(Exception):
+    """Sub-class for errors from the movement_planning module."""
+
+    def __init__(
+        self,
+        origin: Point,
+        dest: Point,
+        clearance: float,
+        min_travel_z: float,
+        max_travel_z: float,
+        message: str,
+    ) -> None:
+        """Initialize an error with properties of the planned motion."""
+        super().__init__(message)
+        self.origin = origin
+        self.dest = dest
+        self.clearance = clearance
+        self.min_travel_z = min_travel_z
+        self.max_travel_z = max_travel_z
+
+
+class DestinationOutOfBoundsError(MotionPlanningError, ValueError):
+    """An error raised when a requested destination is out of bounds."""
+
+    pass
+
+
+class ArcOutOfBoundsError(MotionPlanningError, ValueError):
+    """An error raised when a calculated movement arc is out of bounds."""
+
+    pass

opentrons/motion_planning/types.py

@@ -0,0 +1,42 @@
+"""Motion planning base interfaces."""
+from dataclasses import dataclass
+from enum import Enum, auto as auto_enum_value
+from typing import Optional
+from typing_extensions import final
+
+from opentrons.types import Point
+from opentrons.hardware_control.types import CriticalPoint
+
+
+@dataclass(frozen=True)
+@final
+class Waypoint:
+    """Motion waypoint with position and optional pipette critical point."""
+
+    position: Point
+    critical_point: Optional[CriticalPoint] = None
+
+
+@final
+class MoveType(Enum):
+    """Arc or direct movement type.
+
+    - GENERAL_ARC: an arc movement between two unrelated locations
+    - IN_LABWARE_ARC: an arc movement between two locations in the same labware
+    - DIRECT: a direct movement between two locations
+    """
+
+    GENERAL_ARC = auto_enum_value()
+    IN_LABWARE_ARC = auto_enum_value()
+    DIRECT = auto_enum_value()
+
+
+@dataclass(frozen=True)
+@final
+class GripperMovementWaypointsWithJawStatus:
+    """Gripper motion waypoint with expected jaw status while moving to the waypoint."""
+
+    position: Point
+    jaw_open: bool
+    dropping: bool
+    """This flag should only be set to True if this waypoint involves dropping a piece of labware."""