opentrons 8.3.1a1__py2.py3-none-any.whl → 8.4.0a1__py2.py3-none-any.whl

opentrons/protocol_engine/errors/exceptions.py

@@ -459,6 +459,19 @@ class ModuleNotConnectedError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class OffsetLocationInvalidError(ProtocolEngineError):
+    """Raised when encountering an invalid labware offset location sequence."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build an OffsetLocationSequenceDoesNotTerminateAtAnAddressableAreaError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class SlotDoesNotExistError(ProtocolEngineError):
     """Raised when referencing a deck slot that does not exist."""
 
@@ -1114,6 +1127,19 @@ class LiquidHeightUnknownError(ProtocolEngineError):
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
 
 
+class LiquidVolumeUnknownError(ProtocolEngineError):
+    """Raised when attempting to report an unknown liquid volume."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a LiquidVolumeUnknownError."""
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
 class EStopActivatedError(ProtocolEngineError):
     """Represents an E-stop event."""
 
@@ -1231,3 +1257,27 @@ class LiquidClassRedefinitionError(ProtocolEngineError):
         wrapping: Optional[Sequence[EnumeratedError]] = None,
     ) -> None:
         super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class FlexStackerNotLogicallyEmptyError(ProtocolEngineError):
+    """Raised when attempting a stacker operation that requires it to be empty when it is known from the protocol that it is not."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)
+
+
+class FlexStackerLabwarePoolNotYetDefinedError(ProtocolEngineError):
+    """Raised when attempting to modify labware in a stacker whose labware pool is not yet defined."""
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        details: Optional[dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        super().__init__(ErrorCodes.GENERAL_ERROR, message, details, wrapping)

opentrons/protocol_engine/execution/equipment.py

@@ -1,11 +1,12 @@
 """Equipment command side-effect logic."""
+
 from dataclasses import dataclass
-from typing import Optional, overload, Union, List
+from typing import Optional, overload, List
 
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 from opentrons_shared_data.pipette.types import PipetteNameType
 
 from opentrons.calibration_storage.helpers import uri_from_details
-from opentrons.protocols.models import LabwareDefinition
 from opentrons.types import MountType
 from opentrons.hardware_control import HardwareControlAPI
 from opentrons.hardware_control.modules import (
@@ -15,6 +16,7 @@ from opentrons.hardware_control.modules import (
     TempDeck,
     Thermocycler,
     AbsorbanceReader,
+    FlexStacker,
 )
 from opentrons.hardware_control.nozzle_manager import NozzleMap
 from opentrons.protocol_engine.state.module_substates import (
@@ -23,6 +25,7 @@ from opentrons.protocol_engine.state.module_substates import (
     TemperatureModuleId,
     ThermocyclerModuleId,
     AbsorbanceReaderId,
+    FlexStackerId,
 )
 from ..errors import (
     FailedToLoadPipetteError,
@@ -40,13 +43,11 @@ from ..state.modules import HardwareModule
 from ..types import (
     LabwareLocation,
     DeckSlotLocation,
-    ModuleLocation,
-    OnLabwareLocation,
     LabwareOffset,
-    LabwareOffsetLocation,
     ModuleModel,
     ModuleDefinition,
     AddressableAreaLocation,
+    LoadedLabware,
 )
 
 
@@ -127,30 +128,18 @@ class EquipmentHandler:
             or pipette_data_provider.VirtualPipetteDataProvider()
         )
 
-    async def load_labware(
-        self,
-        load_name: str,
-        namespace: str,
-        version: int,
-        location: LabwareLocation,
-        labware_id: Optional[str],
-    ) -> LoadedLabwareData:
-        """Load labware by assigning an identifier and pulling required data.
+    async def load_definition_for_details(
+        self, load_name: str, namespace: str, version: int
+    ) -> tuple[LabwareDefinition, str]:
+        """Load the definition for a labware from the parameters passed for it to a command.
 
         Args:
             load_name: The labware's load name.
             namespace: The labware's namespace.
             version: The labware's version.
-            location: The deck location at which labware is placed.
-            labware_id: An optional identifier to assign the labware. If None, an
-                identifier will be generated.
-
-        Raises:
-            ModuleNotLoadedError: If `location` references a module ID
-                that doesn't point to a valid loaded module.
 
         Returns:
-            A LoadedLabwareData object.
+            A tuple of the loaded LabwareDefinition object and its definition URI.
         """
         definition_uri = uri_from_details(
             load_name=load_name,
@@ -160,14 +149,43 @@ class EquipmentHandler:
 
         try:
             # Try to use existing definition in state.
-            definition = self._state_store.labware.get_definition_by_uri(definition_uri)
+            return (
+                self._state_store.labware.get_definition_by_uri(definition_uri),
+                definition_uri,
+            )
         except LabwareDefinitionDoesNotExistError:
             definition = await self._labware_data_provider.get_labware_definition(
                 load_name=load_name,
                 namespace=namespace,
                 version=version,
             )
+            return definition, definition_uri
+
+    async def load_labware_from_definition(
+        self,
+        definition: LabwareDefinition,
+        location: LabwareLocation,
+        labware_id: Optional[str],
+        labware_pending_load: dict[str, LoadedLabware] | None = None,
+    ) -> LoadedLabwareData:
+        """Load labware from already-found definition."""
+        definition_uri = uri_from_details(
+            load_name=definition.parameters.loadName,
+            namespace=definition.namespace,
+            version=definition.version,
+        )
+        return await self._load_labware_from_def_and_uri(
+            definition, definition_uri, location, labware_id, labware_pending_load
+        )
 
+    async def _load_labware_from_def_and_uri(
+        self,
+        definition: LabwareDefinition,
+        definition_uri: str,
+        location: LabwareLocation,
+        labware_id: str | None,
+        labware_pending_load: dict[str, LoadedLabware] | None,
+    ) -> LoadedLabwareData:
         labware_id = (
             labware_id if labware_id is not None else self._model_utils.generate_id()
         )
@@ -176,12 +194,45 @@ class EquipmentHandler:
         offset_id = self.find_applicable_labware_offset_id(
             labware_definition_uri=definition_uri,
             labware_location=location,
+            labware_pending_load=labware_pending_load,
         )
 
         return LoadedLabwareData(
             labware_id=labware_id, definition=definition, offsetId=offset_id
         )
 
+    async def load_labware(
+        self,
+        load_name: str,
+        namespace: str,
+        version: int,
+        location: LabwareLocation,
+        labware_id: Optional[str],
+    ) -> LoadedLabwareData:
+        """Load labware by assigning an identifier and pulling required data.
+
+        Args:
+            load_name: The labware's load name.
+            namespace: The labware's namespace.
+            version: The labware's version.
+            location: The deck location at which labware is placed.
+            labware_id: An optional identifier to assign the labware. If None, an
+                identifier will be generated.
+
+        Raises:
+            ModuleNotLoadedError: If `location` references a module ID
+                that doesn't point to a valid loaded module.
+
+        Returns:
+            A LoadedLabwareData object.
+        """
+        definition, definition_uri = await self.load_definition_for_details(
+            load_name, namespace, version
+        )
+        return await self._load_labware_from_def_and_uri(
+            definition, definition_uri, location, labware_id, None
+        )
+
     async def reload_labware(self, labware_id: str) -> ReloadedLabwareData:
         """Reload an already-loaded labware. This cannot change the labware location.
 
@@ -290,7 +341,7 @@ class EquipmentHandler:
     async def load_magnetic_block(
         self,
         model: ModuleModel,
-        location: Union[DeckSlotLocation, AddressableAreaLocation],
+        location: AddressableAreaLocation,
         module_id: Optional[str],
     ) -> LoadedModuleData:
         """Ensure the required magnetic block is attached.
@@ -321,7 +372,7 @@ class EquipmentHandler:
     async def load_module(
         self,
         model: ModuleModel,
-        location: DeckSlotLocation,
+        location: AddressableAreaLocation,
         module_id: Optional[str],
     ) -> LoadedModuleData:
         """Ensure the required module is attached.
@@ -355,12 +406,18 @@ class EquipmentHandler:
                 for hw_mod in self._hardware_api.attached_modules
             ]
 
-            serial_number_at_locaiton = self._state_store.geometry._addressable_areas.get_fixture_serial_from_deck_configuration_by_deck_slot(
-                location.slotName
+            serial_number_at_locaiton = self._state_store.geometry._addressable_areas.get_fixture_serial_from_deck_configuration_by_addressable_area(
+                addressable_area_name=location.addressableAreaName
+            )
+            cutout_id = self._state_store.geometry._addressable_areas.get_cutout_id_by_deck_slot_name(
+                slot_name=self._state_store.geometry._addressable_areas.get_addressable_area_base_slot(
+                    location.addressableAreaName
+                )
             )
+
             attached_module = self._state_store.modules.select_hardware_module_to_load(
                 model=model,
-                location=location,
+                location=cutout_id,
                 attached_modules=attached_modules,
                 expected_serial_number=serial_number_at_locaiton,
             )
@@ -386,6 +443,7 @@ class EquipmentHandler:
         version: int,
         location: LabwareLocation,
         quantity: int,
+        labware_ids: Optional[List[str]] = None,
     ) -> List[LoadedLabwareData]:
         """Load one or many lid labware by assigning an identifier and pulling required data.
 
@@ -394,6 +452,7 @@ class EquipmentHandler:
             namespace: The lid labware's namespace.
             version: The lid labware's version.
             location: The deck location at which lid(s) will be placed.
+            quantity: The quantity of lids to load at a location.
             labware_ids: An optional list of identifiers to assign the labware. If None,
                 an identifier will be generated.
 
@@ -425,21 +484,32 @@ class EquipmentHandler:
                 f"Requested quantity {quantity} is greater than the stack limit of {stack_limit} provided by definition for {load_name}."
             )
 
-        # Allow propagation of ModuleNotLoadedError.
-        if (
-            isinstance(location, DeckSlotLocation)
-            and definition.parameters.isDeckSlotCompatible is not None
-            and not definition.parameters.isDeckSlotCompatible
-        ):
+        is_deck_slot_compatible = (
+            True
+            if definition.parameters.isDeckSlotCompatible is None
+            else definition.parameters.isDeckSlotCompatible
+        )
+
+        if isinstance(location, DeckSlotLocation) and not is_deck_slot_compatible:
             raise ValueError(
                 f"Lid Labware {load_name} cannot be loaded onto a Deck Slot."
             )
 
-        load_labware_data_list = []
-        for i in range(quantity):
+        load_labware_data_list: list[LoadedLabwareData] = []
+        ids: list[str] = []
+        if labware_ids is not None:
+            if len(labware_ids) < quantity:
+                raise ValueError(
+                    f"Requested quantity {quantity} is greater than the number of labware lid IDs provided for {load_name}."
+                )
+            ids = labware_ids
+        else:
+            for i in range(quantity):
+                ids.append(self._model_utils.generate_id())
+        for id in ids:
             load_labware_data_list.append(
                 LoadedLabwareData(
-                    labware_id=self._model_utils.generate_id(),
+                    labware_id=id,
                     definition=definition,
                     offsetId=None,
                 )
@@ -581,6 +651,13 @@ class EquipmentHandler:
     ) -> Optional[AbsorbanceReader]:
         ...
 
+    @overload
+    def get_module_hardware_api(
+        self,
+        module_id: FlexStackerId,
+    ) -> Optional[FlexStacker]:
+        ...
+
     def get_module_hardware_api(self, module_id: str) -> Optional[AbstractModule]:
         """Get the hardware API for a given module."""
         use_virtual_modules = self._state_store.config.use_virtual_modules
@@ -599,8 +676,11 @@ class EquipmentHandler:
         )
 
     def find_applicable_labware_offset_id(
-        self, labware_definition_uri: str, labware_location: LabwareLocation
-    ) -> Optional[str]:
+        self,
+        labware_definition_uri: str,
+        labware_location: LabwareLocation,
+        labware_pending_load: dict[str, LoadedLabware] | None = None,
+    ) -> str | None:
         """Figure out what offset would apply to a labware in the given location.
 
         Raises:
@@ -612,8 +692,11 @@ class EquipmentHandler:
             or None if no labware offset will apply.
         """
         labware_offset_location = (
-            self._get_labware_offset_location_from_labware_location(labware_location)
+            self._state_store.geometry.get_projected_offset_location(
+                labware_location, labware_pending_load
+            )
         )
+
         if labware_offset_location is None:
             # No offset for off-deck location.
             # Returning None instead of raising an exception allows loading a labware
@@ -626,72 +709,6 @@ class EquipmentHandler:
         )
         return self._get_id_from_offset(offset)
 
-    def _get_labware_offset_location_from_labware_location(
-        self, labware_location: LabwareLocation
-    ) -> Optional[LabwareOffsetLocation]:
-        if isinstance(labware_location, DeckSlotLocation):
-            return LabwareOffsetLocation(slotName=labware_location.slotName)
-        elif isinstance(labware_location, ModuleLocation):
-            module_id = labware_location.moduleId
-            # Allow ModuleNotLoadedError to propagate.
-            # Note also that we match based on the module's requested model, not its
-            # actual model, to implement robot-server's documented HTTP API semantics.
-            module_model = self._state_store.modules.get_requested_model(
-                module_id=module_id
-            )
-
-            # If `module_model is None`, it probably means that this module was added by
-            # `ProtocolEngine.use_attached_modules()`, instead of an explicit
-            # `loadModule` command.
-            #
-            # This assert should never raise in practice because:
-            #   1. `ProtocolEngine.use_attached_modules()` is only used by
-            #      robot-server's "stateless command" endpoints, under `/commands`.
-            #   2. Those endpoints don't support loading labware, so this code will
-            #      never run.
-            #
-            # Nevertheless, if it does happen somehow, we do NOT want to pass the
-            # `None` value along to `LabwareView.find_applicable_labware_offset()`.
-            # `None` means something different there, which will cause us to return
-            # wrong results.
-            assert module_model is not None, (
-                "Can't find offsets for labware"
-                " that are loaded on modules"
-                " that were loaded with ProtocolEngine.use_attached_modules()."
-            )
-
-            module_location = self._state_store.modules.get_location(
-                module_id=module_id
-            )
-            slot_name = module_location.slotName
-            return LabwareOffsetLocation(slotName=slot_name, moduleModel=module_model)
-        elif isinstance(labware_location, OnLabwareLocation):
-            parent_labware_id = labware_location.labwareId
-            parent_labware_uri = self._state_store.labware.get_definition_uri(
-                parent_labware_id
-            )
-
-            base_location = self._state_store.labware.get_parent_location(
-                parent_labware_id
-            )
-            base_labware_offset_location = (
-                self._get_labware_offset_location_from_labware_location(base_location)
-            )
-            if base_labware_offset_location is None:
-                # No offset for labware sitting on labware off-deck
-                return None
-
-            # If labware is being stacked on itself, all labware in the stack will share a labware offset due to
-            # them sharing the same definitionUri in `LabwareOffsetLocation`. This will not be true for the
-            # bottom-most labware, which will have a `DeckSlotLocation` and have its definitionUri field empty.
-            return LabwareOffsetLocation(
-                slotName=base_labware_offset_location.slotName,
-                moduleModel=base_labware_offset_location.moduleModel,
-                definitionUri=parent_labware_uri,
-            )
-        else:  # Off deck
-            return None
-
     @staticmethod
     def _get_id_from_offset(labware_offset: Optional[LabwareOffset]) -> Optional[str]:
         return None if labware_offset is None else labware_offset.id

opentrons/protocol_engine/execution/labware_movement.py

@@ -1,4 +1,5 @@
 """Labware movement command handling."""
+
 from __future__ import annotations
 
 from typing import Optional, TYPE_CHECKING, overload
@@ -128,6 +129,13 @@ class LabwareMovementHandler:
             assert labware_id is not None  # From this method's @typing.overloads.
             labware_definition = self._state_store.labware.get_definition(labware_id)
 
+        from_labware_center = self._state_store.geometry.get_labware_grip_point(
+            labware_definition=labware_definition, location=current_location
+        )
+        to_labware_center = self._state_store.geometry.get_labware_grip_point(
+            labware_definition=labware_definition, location=new_location
+        )
+
         if use_virtual_gripper:
             # todo(mm, 2024-11-07): We should do this collision checking even when we
             # only have a `labware_definition`, not a `labware_id`. Resolve when
@@ -182,12 +190,6 @@ class LabwareMovementHandler:
                     current_labware=labware_definition,
                 )
             )
-            from_labware_center = self._state_store.geometry.get_labware_grip_point(
-                labware_definition=labware_definition, location=current_location
-            )
-            to_labware_center = self._state_store.geometry.get_labware_grip_point(
-                labware_definition=labware_definition, location=new_location
-            )
             movement_waypoints = get_gripper_labware_movement_waypoints(
                 from_labware_center=from_labware_center,
                 to_labware_center=to_labware_center,