opentrons 8.1.0__py2.py3-none-any.whl → 8.2.0__py2.py3-none-any.whl

opentrons/protocol_engine/state/labware.py

@@ -13,11 +13,16 @@ from typing import (
     NamedTuple,
     cast,
     Union,
+    overload,
 )
 
+from opentrons.protocol_engine.state import update_types
 from opentrons_shared_data.deck.types import DeckDefinitionV5
 from opentrons_shared_data.gripper.constants import LABWARE_GRIP_FORCE
-from opentrons_shared_data.labware.labware_definition import LabwareRole
+from opentrons_shared_data.labware.labware_definition import (
+    LabwareRole,
+    InnerWellGeometry,
+)
 from opentrons_shared_data.pipette.types import LabwareUri
 
 from opentrons.types import DeckSlotName, StagingSlotName, MountType
@@ -27,12 +32,6 @@ from opentrons.calibration_storage.helpers import uri_from_details
 
 from .. import errors
 from ..resources import DeckFixedLabware, labware_validation, fixture_validation
-from ..commands import (
-    Command,
-    LoadLabwareResult,
-    MoveLabwareResult,
-    ReloadLabwareResult,
-)
 from ..types import (
     DeckSlotLocation,
     OnLabwareLocation,
@@ -53,12 +52,12 @@ from ..types import (
 )
 from ..actions import (
     Action,
-    SucceedCommandAction,
     AddLabwareOffsetAction,
     AddLabwareDefinitionAction,
+    get_state_updates,
 )
-from .abstract_store import HasState, HandlesActions
-from .move_types import EdgePathType
+from ._abstract_store import HasState, HandlesActions
+from ._move_types import EdgePathType
 
 
 # URIs of labware whose definitions accidentally specify an engage height
@@ -69,8 +68,6 @@ _MAGDECK_HALF_MM_LABWARE = {
     "opentrons/usascientific_96_wellplate_2.4ml_deep/1",
 }
 
-_OT3_INSTRUMENT_ATTACH_SLOT = DeckSlotName.SLOT_D1
-
 _RIGHT_SIDE_SLOTS = {
     # OT-2:
     DeckSlotName.FIXED_TRASH,
@@ -85,6 +82,10 @@ _RIGHT_SIDE_SLOTS = {
 }
 
 
+# The max height of the labware that can fit in a plate reader
+_PLATE_READER_MAX_LABWARE_Z_MM = 16
+
+
 class LabwareLoadParams(NamedTuple):
     """Parameters required to load a labware in Protocol Engine."""
 
@@ -153,10 +154,11 @@ class LabwareStore(HasState[LabwareState], HandlesActions):
 
     def handle_action(self, action: Action) -> None:
         """Modify state in reaction to an action."""
-        if isinstance(action, SucceedCommandAction):
-            self._handle_command(action.command)
+        for state_update in get_state_updates(action):
+            self._add_loaded_labware(state_update)
+            self._set_labware_location(state_update)
 
-        elif isinstance(action, AddLabwareOffsetAction):
+        if isinstance(action, AddLabwareOffsetAction):
             labware_offset = LabwareOffset.construct(
                 id=action.labware_offset_id,
                 createdAt=action.created_at,
@@ -174,66 +176,72 @@ class LabwareStore(HasState[LabwareState], HandlesActions):
             )
             self._state.definitions_by_uri[uri] = action.definition
 
-    def _handle_command(self, command: Command) -> None:
-        """Modify state in reaction to a command."""
-        if isinstance(command.result, LoadLabwareResult):
+    def _add_labware_offset(self, labware_offset: LabwareOffset) -> None:
+        """Add a new labware offset to state.
+
+        `labware_offset.id` must not match any existing labware offset ID.
+        `LoadLabwareCommand`s retain references to their corresponding labware offsets
+        and expect them to be immutable.
+        """
+        assert labware_offset.id not in self._state.labware_offsets_by_id
+
+        self._state.labware_offsets_by_id[labware_offset.id] = labware_offset
+
+    def _add_loaded_labware(self, state_update: update_types.StateUpdate) -> None:
+        loaded_labware_update = state_update.loaded_labware
+        if loaded_labware_update != update_types.NO_CHANGE:
             # If the labware load refers to an offset, that offset must actually exist.
-            if command.result.offsetId is not None:
-                assert command.result.offsetId in self._state.labware_offsets_by_id
+            if loaded_labware_update.offset_id is not None:
+                assert (
+                    loaded_labware_update.offset_id in self._state.labware_offsets_by_id
+                )
 
             definition_uri = uri_from_details(
-                namespace=command.result.definition.namespace,
-                load_name=command.result.definition.parameters.loadName,
-                version=command.result.definition.version,
+                namespace=loaded_labware_update.definition.namespace,
+                load_name=loaded_labware_update.definition.parameters.loadName,
+                version=loaded_labware_update.definition.version,
             )
 
-            self._state.definitions_by_uri[definition_uri] = command.result.definition
-            if isinstance(command.result, LoadLabwareResult):
-                location = command.params.location
-            else:
-                location = self._state.labware_by_id[command.result.labwareId].location
+            self._state.definitions_by_uri[
+                definition_uri
+            ] = loaded_labware_update.definition
+
+            location = loaded_labware_update.new_location
+
+            display_name = loaded_labware_update.display_name
 
             self._state.labware_by_id[
-                command.result.labwareId
+                loaded_labware_update.labware_id
             ] = LoadedLabware.construct(
-                id=command.result.labwareId,
+                id=loaded_labware_update.labware_id,
                 location=location,
-                loadName=command.result.definition.parameters.loadName,
+                loadName=loaded_labware_update.definition.parameters.loadName,
                 definitionUri=definition_uri,
-                offsetId=command.result.offsetId,
-                displayName=command.params.displayName,
+                offsetId=loaded_labware_update.offset_id,
+                displayName=display_name,
             )
 
-        elif isinstance(command.result, ReloadLabwareResult):
-            labware_id = command.params.labwareId
-            new_offset_id = command.result.offsetId
-            self._state.labware_by_id[labware_id].offsetId = new_offset_id
-
-        elif isinstance(command.result, MoveLabwareResult):
-            labware_id = command.params.labwareId
-            new_location = command.params.newLocation
-            new_offset_id = command.result.offsetId
+    def _set_labware_location(self, state_update: update_types.StateUpdate) -> None:
+        labware_location_update = state_update.labware_location
+        if labware_location_update != update_types.NO_CHANGE:
+            labware_id = labware_location_update.labware_id
+            new_offset_id = labware_location_update.offset_id
 
             self._state.labware_by_id[labware_id].offsetId = new_offset_id
-            if isinstance(
-                new_location, AddressableAreaLocation
-            ) and fixture_validation.is_gripper_waste_chute(
-                new_location.addressableAreaName
-            ):
-                # If a labware has been moved into a waste chute it's been chuted away and is now technically off deck
-                new_location = OFF_DECK_LOCATION
-            self._state.labware_by_id[labware_id].location = new_location
 
-    def _add_labware_offset(self, labware_offset: LabwareOffset) -> None:
-        """Add a new labware offset to state.
+            if labware_location_update.new_location:
+                new_location = labware_location_update.new_location
 
-        `labware_offset.id` must not match any existing labware offset ID.
-        `LoadLabwareCommand`s retain references to their corresponding labware offsets
-        and expect them to be immutable.
-        """
-        assert labware_offset.id not in self._state.labware_offsets_by_id
+                if isinstance(new_location, AddressableAreaLocation) and (
+                    fixture_validation.is_gripper_waste_chute(
+                        new_location.addressableAreaName
+                    )
+                    or fixture_validation.is_trash(new_location.addressableAreaName)
+                ):
+                    # If a labware has been moved into a waste chute it's been chuted away and is now technically off deck
+                    new_location = OFF_DECK_LOCATION
 
-        self._state.labware_offsets_by_id[labware_offset.id] = labware_offset
+                self._state.labware_by_id[labware_id].location = new_location
 
 
 class LabwareView(HasState[LabwareState]):
@@ -313,6 +321,22 @@ class LabwareView(HasState[LabwareState]):
 
         return None
 
+    def get_by_addressable_area(
+        self,
+        addressable_area: str,
+    ) -> Optional[LoadedLabware]:
+        """Get the labware located in a given addressable area, if any."""
+        loaded_labware = list(self._state.labware_by_id.values())
+
+        for labware in loaded_labware:
+            if (
+                isinstance(labware.location, AddressableAreaLocation)
+                and labware.location.addressableAreaName == addressable_area
+            ):
+                return labware
+
+        return None
+
     def get_definition(self, labware_id: str) -> LabwareDefinition:
         """Get labware definition by the labware's unique identifier."""
         return self.get_definition_by_uri(
@@ -378,6 +402,16 @@ class LabwareView(HasState[LabwareState]):
             return self.get_parent_location(parent.labwareId)
         return parent
 
+    def get_labware_stack(
+        self, labware_stack: List[LoadedLabware]
+    ) -> List[LoadedLabware]:
+        """Get the a stack of labware starting from a given labware or existing stack."""
+        parent = self.get_location(labware_stack[-1].id)
+        if isinstance(parent, OnLabwareLocation):
+            labware_stack.append(self.get(parent.labwareId))
+            return self.get_labware_stack(labware_stack)
+        return labware_stack
+
     def get_all(self) -> List[LoadedLabware]:
         """Get a list of all labware entries in state."""
         return list(self._state.labware_by_id.values())
@@ -402,6 +436,27 @@ class LabwareView(HasState[LabwareState]):
             and len(self.get_definition(labware_id).wells) < 96
         )
 
+    def get_labware_stacking_maximum(self, labware: LabwareDefinition) -> int:
+        """Returns the maximum number of labware allowed in a stack for a given labware definition.
+
+        If not defined within a labware, defaults to one.
+        """
+        stacking_quirks = {
+            "stackingMaxFive": 5,
+            "stackingMaxFour": 4,
+            "stackingMaxThree": 3,
+            "stackingMaxTwo": 2,
+            "stackingMaxOne": 1,
+            "stackingMaxZero": 0,
+        }
+        for quirk in stacking_quirks.keys():
+            if (
+                labware.parameters.quirks is not None
+                and quirk in labware.parameters.quirks
+            ):
+                return stacking_quirks[quirk]
+        return 1
+
     def get_should_center_pipette_on_target_well(self, labware_id: str) -> bool:
         """True if a pipette moving to a well of this labware should center its body on the target.
 
@@ -435,6 +490,29 @@ class LabwareView(HasState[LabwareState]):
                 f"{well_name} does not exist in {labware_id}."
             ) from e
 
+    def get_well_geometry(
+        self, labware_id: str, well_name: Optional[str] = None
+    ) -> InnerWellGeometry:
+        """Get a well's inner geometry by labware and well name."""
+        labware_def = self.get_definition(labware_id)
+        if labware_def.innerLabwareGeometry is None:
+            raise errors.IncompleteLabwareDefinitionError(
+                message=f"No innerLabwareGeometry found in labware definition for labware_id: {labware_id}."
+            )
+        well_def = self.get_well_definition(labware_id, well_name)
+        well_id = well_def.geometryDefinitionId
+        if well_id is None:
+            raise errors.IncompleteWellDefinitionError(
+                message=f"No geometryDefinitionId found in well definition for well: {well_name} in labware_id: {labware_id}"
+            )
+        else:
+            well_geometry = labware_def.innerLabwareGeometry.get(well_id)
+            if well_geometry is None:
+                raise errors.IncompleteLabwareDefinitionError(
+                    message=f"No innerLabwareGeometry found in labware definition for well_id: {well_id} in labware_id: {labware_id}"
+                )
+            return well_geometry
+
     def get_well_size(
         self, labware_id: str, well_name: str
     ) -> Tuple[float, float, float]:
@@ -553,10 +631,26 @@ class LabwareView(HasState[LabwareState]):
         definition = self.get_definition(labware_id)
         return definition.parameters.loadName
 
-    def get_dimensions(self, labware_id: str) -> Dimensions:
+    @overload
+    def get_dimensions(self, *, labware_definition: LabwareDefinition) -> Dimensions:
+        pass
+
+    @overload
+    def get_dimensions(self, *, labware_id: str) -> Dimensions:
+        pass
+
+    def get_dimensions(
+        self,
+        *,
+        labware_definition: LabwareDefinition | None = None,
+        labware_id: str | None = None,
+    ) -> Dimensions:
         """Get the labware's dimensions."""
-        definition = self.get_definition(labware_id)
-        dims = definition.dimensions
+        if labware_definition is None:
+            assert labware_id is not None  # From our @overloads.
+            labware_definition = self.get_definition(labware_id)
+
+        dims = labware_definition.dimensions
 
         return Dimensions(
             x=dims.xDimension,
@@ -565,22 +659,25 @@ class LabwareView(HasState[LabwareState]):
         )
 
     def get_labware_overlap_offsets(
-        self, labware_id: str, below_labware_name: str
+        self, definition: LabwareDefinition, below_labware_name: str
     ) -> OverlapOffset:
         """Get the labware's overlap with requested labware's load name."""
-        definition = self.get_definition(labware_id)
-        stacking_overlap = definition.stackingOffsetWithLabware.get(
-            below_labware_name, OverlapOffset(x=0, y=0, z=0)
-        )
+        if below_labware_name in definition.stackingOffsetWithLabware.keys():
+            stacking_overlap = definition.stackingOffsetWithLabware.get(
+                below_labware_name, OverlapOffset(x=0, y=0, z=0)
+            )
+        else:
+            stacking_overlap = definition.stackingOffsetWithLabware.get(
+                "default", OverlapOffset(x=0, y=0, z=0)
+            )
         return OverlapOffset(
             x=stacking_overlap.x, y=stacking_overlap.y, z=stacking_overlap.z
         )
 
     def get_module_overlap_offsets(
-        self, labware_id: str, module_model: ModuleModel
+        self, definition: LabwareDefinition, module_model: ModuleModel
     ) -> OverlapOffset:
         """Get the labware's overlap with requested module model."""
-        definition = self.get_definition(labware_id)
         stacking_overlap = definition.stackingOffsetWithModule.get(
             str(module_model.value)
         )
@@ -704,6 +801,12 @@ class LabwareView(HasState[LabwareState]):
         """Check if labware is fixed trash."""
         return self.get_has_quirk(labware_id, "fixedTrash")
 
+    def is_absorbance_reader_lid(self, labware_id: str) -> bool:
+        """Check if labware is an absorbance reader lid."""
+        return labware_validation.is_absorbance_reader_lid(
+            self.get(labware_id).loadName
+        )
+
     def raise_if_labware_inaccessible_by_pipette(self, labware_id: str) -> None:
         """Raise an error if the specified location cannot be reached via a pipette."""
         labware = self.get(labware_id)
@@ -734,7 +837,25 @@ class LabwareView(HasState[LabwareState]):
                     f"Labware {labware.loadName} is already present at {location}."
                 )
 
-    def raise_if_labware_cannot_be_stacked(
+    def raise_if_labware_incompatible_with_plate_reader(
+        self,
+        labware_definition: LabwareDefinition,
+    ) -> None:
+        """Raise an error if the labware is not compatible with the plate reader."""
+        load_name = labware_definition.parameters.loadName
+        number_of_wells = len(labware_definition.wells)
+        if number_of_wells != 96:
+            raise errors.LabwareMovementNotAllowedError(
+                f"Cannot move '{load_name}' into plate reader because the"
+                f" labware contains {number_of_wells} wells where 96 wells is expected."
+            )
+        elif labware_definition.dimensions.zDimension > _PLATE_READER_MAX_LABWARE_Z_MM:
+            raise errors.LabwareMovementNotAllowedError(
+                f"Cannot move '{load_name}' into plate reader because the"
+                f" maximum allowed labware height is {_PLATE_READER_MAX_LABWARE_Z_MM}mm."
+            )
+
+    def raise_if_labware_cannot_be_stacked(  # noqa: C901
         self, top_labware_definition: LabwareDefinition, bottom_labware_id: str
     ) -> None:
         """Raise if the specified labware definition cannot be placed on top of the bottom labware."""
@@ -753,17 +874,37 @@ class LabwareView(HasState[LabwareState]):
             )
         elif isinstance(below_labware.location, ModuleLocation):
             below_definition = self.get_definition(labware_id=below_labware.id)
-            if not labware_validation.validate_definition_is_adapter(below_definition):
+            if not labware_validation.validate_definition_is_adapter(
+                below_definition
+            ) and not labware_validation.validate_definition_is_lid(
+                top_labware_definition
+            ):
                 raise errors.LabwareCannotBeStackedError(
                     f"Labware {top_labware_definition.parameters.loadName} cannot be loaded"
                     f" onto a labware on top of a module"
                 )
         elif isinstance(below_labware.location, OnLabwareLocation):
+            labware_stack = self.get_labware_stack([below_labware])
+            stack_without_adapters = []
+            for lw in labware_stack:
+                if not labware_validation.validate_definition_is_adapter(
+                    self.get_definition(lw.id)
+                ):
+                    stack_without_adapters.append(lw)
+            if len(stack_without_adapters) >= self.get_labware_stacking_maximum(
+                top_labware_definition
+            ):
+                raise errors.LabwareCannotBeStackedError(
+                    f"Labware {top_labware_definition.parameters.loadName} cannot be loaded to stack of more than {self.get_labware_stacking_maximum(top_labware_definition)} labware."
+                )
+
             further_below_definition = self.get_definition(
                 labware_id=below_labware.location.labwareId
             )
             if labware_validation.validate_definition_is_adapter(
                 further_below_definition
+            ) and not labware_validation.validate_definition_is_lid(
+                top_labware_definition
             ):
                 raise errors.LabwareCannotBeStackedError(
                     f"Labware {top_labware_definition.parameters.loadName} cannot be loaded"
@@ -797,22 +938,60 @@ class LabwareView(HasState[LabwareState]):
             else None
         )
 
-    def get_labware_gripper_offsets(
+    def get_absorbance_reader_lid_definition(self) -> LabwareDefinition:
+        """Return the special labware definition for the plate reader lid.
+
+        See todo comments in `create_protocol_engine().
+        """
+        # NOTE: This needs to stay in sync with create_protocol_engine().
+        return self._state.definitions_by_uri[
+            "opentrons/opentrons_flex_lid_absorbance_plate_reader_module/1"
+        ]
+
+    @overload
+    def get_child_gripper_offsets(
         self,
-        labware_id: str,
+        *,
+        labware_definition: LabwareDefinition,
+        slot_name: Optional[DeckSlotName],
+    ) -> Optional[LabwareMovementOffsetData]:
+        pass
+
+    @overload
+    def get_child_gripper_offsets(
+        self, *, labware_id: str, slot_name: Optional[DeckSlotName]
+    ) -> Optional[LabwareMovementOffsetData]:
+        pass
+
+    def get_child_gripper_offsets(
+        self,
+        *,
+        labware_definition: Optional[LabwareDefinition] = None,
+        labware_id: Optional[str] = None,
         slot_name: Optional[DeckSlotName],
     ) -> Optional[LabwareMovementOffsetData]:
-        """Get the labware's gripper offsets of the specified type.
+        """Get the grip offsets that a labware says should be applied to children stacked atop it.
+
+        Params:
+            labware_id: The ID of a parent labware (atop which another labware, the child, will be stacked).
+            slot_name: The ancestor slot that the parent labware is ultimately loaded into,
+                       perhaps after going through a module in the middle.
 
         Returns:
-            If `slot_name` is provided, returns the gripper offsets that the labware definition
+            If `slot_name` is provided, returns the gripper offsets that the parent labware definition
             specifies just for that slot, or `None` if the labware definition doesn't have an
             exact match.
 
-            If `slot_name` is `None`, returns the gripper offsets that the labware
+            If `slot_name` is `None`, returns the gripper offsets that the parent labware
             definition designates as "default," or `None` if it doesn't designate any as such.
         """
-        parsed_offsets = self.get_definition(labware_id).gripperOffsets
+        if labware_id is not None:
+            labware_definition = self.get_definition(labware_id)
+        else:
+            # Should be ensured by our @overloads.
+            assert labware_definition is not None
+
+        parsed_offsets = labware_definition.gripperOffsets
         offset_key = slot_name.id if slot_name else "default"
 
         if parsed_offsets is None or offset_key not in parsed_offsets:
@@ -827,20 +1006,22 @@ class LabwareView(HasState[LabwareState]):
                 ),
             )
 
-    def get_grip_force(self, labware_id: str) -> float:
+    def get_grip_force(self, labware_definition: LabwareDefinition) -> float:
         """Get the recommended grip force for gripping labware using gripper."""
-        recommended_force = self.get_definition(labware_id).gripForce
+        recommended_force = labware_definition.gripForce
         return (
             recommended_force if recommended_force is not None else LABWARE_GRIP_FORCE
         )
 
-    def get_grip_height_from_labware_bottom(self, labware_id: str) -> float:
+    def get_grip_height_from_labware_bottom(
+        self, labware_definition: LabwareDefinition
+    ) -> float:
         """Get the recommended grip height from labware bottom, if present."""
-        recommended_height = self.get_definition(labware_id).gripHeightFromLabwareBottom
+        recommended_height = labware_definition.gripHeightFromLabwareBottom
         return (
             recommended_height
             if recommended_height is not None
-            else self.get_dimensions(labware_id).z / 2
+            else self.get_dimensions(labware_definition=labware_definition).z / 2
         )
 
     @staticmethod
@@ -883,7 +1064,7 @@ class LabwareView(HasState[LabwareState]):
     def _max_z_of_well(well_defn: WellDefinition) -> float:
         return well_defn.z + well_defn.depth
 
-    def get_well_bbox(self, labware_id: str) -> Dimensions:
+    def get_well_bbox(self, labware_definition: LabwareDefinition) -> Dimensions:
         """Get the bounding box implied by the wells.
 
         The bounding box of the labware that is implied by the wells is that required
@@ -894,14 +1075,13 @@ class LabwareView(HasState[LabwareState]):
         This is used for the specific purpose of finding the reasonable uncertainty bounds of
         where and how a gripper will interact with a labware.
         """
-        defn = self.get_definition(labware_id)
         max_x: Optional[float] = None
         min_x: Optional[float] = None
         max_y: Optional[float] = None
         min_y: Optional[float] = None
         max_z: Optional[float] = None
 
-        for well in defn.wells.values():
+        for well in labware_definition.wells.values():
             well_max_x = self._max_x_of_well(well)
             well_min_x = self._min_x_of_well(well)
             well_max_y = self._max_y_of_well(well)

opentrons/protocol_engine/state/liquids.py

@@ -3,7 +3,7 @@ from dataclasses import dataclass
 from typing import Dict, List
 from opentrons.protocol_engine.types import Liquid
 
-from .abstract_store import HasState, HandlesActions
+from ._abstract_store import HasState, HandlesActions
 from ..actions import Action, AddLiquidAction
 from ..errors import LiquidDoesNotExistError
 

opentrons/protocol_engine/state/module_substates/absorbance_reader_substate.py

@@ -1,11 +1,17 @@
 """Heater-Shaker Module sub-state."""
 from dataclasses import dataclass
-from typing import NewType, Optional, List
+from typing import List, NewType, Optional, Dict
 
+from opentrons.protocol_engine.errors import CannotPerformModuleAction
 
 AbsorbanceReaderId = NewType("AbsorbanceReaderId", str)
+AbsorbanceReaderLidId = NewType("AbsorbanceReaderLidId", str)
+AbsorbanceReaderMeasureMode = NewType("AbsorbanceReaderMeasureMode", str)
 
 
+# todo(mm, 2024-11-08): frozen=True is getting pretty painful because ModuleStore has
+# no type-safe way to modify just a single attribute. Consider unfreezing this
+# (taking care to ensure that consumers of ModuleView still only get a read-only view).
 @dataclass(frozen=True)
 class AbsorbanceReaderSubState:
     """Absorbance-Plate-Reader-specific state."""
@@ -13,5 +19,17 @@ class AbsorbanceReaderSubState:
     module_id: AbsorbanceReaderId
     configured: bool
     measured: bool
-    data: Optional[List[float]]
-    configured_wavelength: Optional[int]
+    is_lid_on: bool
+    data: Optional[Dict[int, Dict[str, float]]]
+    configured_wavelengths: Optional[List[int]]
+    measure_mode: Optional[AbsorbanceReaderMeasureMode]
+    reference_wavelength: Optional[int]
+
+    def raise_if_lid_status_not_expected(self, lid_on_expected: bool) -> None:
+        """Raise if the lid status is not correct."""
+        match = self.is_lid_on is lid_on_expected
+        if not match:
+            raise CannotPerformModuleAction(
+                "Cannot perform lid action because the lid is already "
+                f"{'closed' if self.is_lid_on else 'open'}"
+            )