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

opentrons/protocol_engine/commands/load_labware.py

@@ -1,25 +1,28 @@
 """Load labware command request, result, and implementation models."""
+
 from __future__ import annotations
 from typing import TYPE_CHECKING, Optional, Type, Any
 
 from pydantic import BaseModel, Field
 from pydantic.json_schema import SkipJsonSchema
-from typing_extensions import Literal
+from typing_extensions import Literal, TypeGuard
 
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 
 from ..errors import LabwareIsNotAllowedInLocationError
 from ..resources import labware_validation, fixture_validation
 from ..types import (
-    LabwareLocation,
+    LoadableLabwareLocation,
     ModuleLocation,
     ModuleModel,
     OnLabwareLocation,
     DeckSlotLocation,
     AddressableAreaLocation,
+    LoadedModule,
 )
 
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from .labware_handling_common import LabwarePositionResultMixin
 from ..errors.error_occurrence import ErrorOccurrence
 from ..state.update_types import StateUpdate
 
@@ -38,7 +41,7 @@ def _remove_default(s: dict[str, Any]) -> None:
 class LoadLabwareParams(BaseModel):
     """Payload required to load a labware into a slot."""
 
-    location: LabwareLocation = Field(
+    location: LoadableLabwareLocation = Field(
         ...,
         description="Location the labware should be loaded into.",
     )
@@ -71,30 +74,13 @@ class LoadLabwareParams(BaseModel):
     )
 
 
-class LoadLabwareResult(BaseModel):
+class LoadLabwareResult(LabwarePositionResultMixin):
     """Result data from the execution of a LoadLabware command."""
 
-    labwareId: str = Field(
-        ...,
-        description="An ID to reference this labware in subsequent commands.",
-    )
     definition: LabwareDefinition = Field(
         ...,
         description="The full definition data for this labware.",
     )
-    offsetId: Optional[str] = Field(
-        # Default `None` instead of `...` so this field shows up as non-required in
-        # OpenAPI. The server is allowed to omit it or make it null.
-        None,
-        description=(
-            "An ID referencing the labware offset that will apply"
-            " to the newly-placed labware."
-            " This offset will be in effect until the labware is moved"
-            " with a `moveLabware` command."
-            " Null or undefined means no offset applies,"
-            " so the default of (0, 0, 0) will be used."
-        ),
-    )
 
 
 class LoadLabwareImplementation(
@@ -108,6 +94,15 @@ class LoadLabwareImplementation(
         self._equipment = equipment
         self._state_view = state_view
 
+    def _is_loading_to_module(
+        self, location: LoadableLabwareLocation, module_model: ModuleModel
+    ) -> TypeGuard[ModuleLocation]:
+        if not isinstance(location, ModuleLocation):
+            return False
+
+        module: LoadedModule = self._state_view.modules.get(location.moduleId)
+        return module.model == module_model
+
     async def execute(
         self, params: LoadLabwareParams
     ) -> SuccessData[LoadLabwareResult]:
@@ -148,6 +143,7 @@ class LoadLabwareImplementation(
         verified_location = self._state_view.geometry.ensure_location_not_occupied(
             params.location
         )
+
         loaded_labware = await self._equipment.load_labware(
             load_name=params.loadName,
             namespace=params.namespace,
@@ -164,34 +160,38 @@ class LoadLabwareImplementation(
             display_name=params.displayName,
         )
 
-        # TODO(jbl 2023-06-23) these validation checks happen after the labware is loaded, because they rely on
-        #   on the definition. In practice this will not cause any issues since they will raise protocol ending
-        #   exception, but for correctness should be refactored to do this check beforehand.
         if isinstance(verified_location, OnLabwareLocation):
             self._state_view.labware.raise_if_labware_cannot_be_stacked(
                 top_labware_definition=loaded_labware.definition,
                 bottom_labware_id=verified_location.labwareId,
             )
             # Validate load location is valid for lids
-            if (
-                labware_validation.validate_definition_is_lid(
-                    definition=loaded_labware.definition
-                )
-                and loaded_labware.definition.compatibleParentLabware is not None
-                and self._state_view.labware.get_load_name(verified_location.labwareId)
-                not in loaded_labware.definition.compatibleParentLabware
+            if labware_validation.validate_definition_is_lid(
+                definition=loaded_labware.definition
             ):
-                raise ValueError(
-                    f"Labware Lid {params.loadName} may not be loaded on parent labware {self._state_view.labware.get_display_name(verified_location.labwareId)}."
+                # This parent is assumed to be compatible, unless the lid enumerates
+                # all its compatible parents and this parent is missing from the list.
+                parent_is_incompatible = (
+                    loaded_labware.definition.compatibleParentLabware is not None
+                    and self._state_view.labware.get_load_name(
+                        verified_location.labwareId
+                    )
+                    not in loaded_labware.definition.compatibleParentLabware
                 )
 
+                if parent_is_incompatible:
+                    raise ValueError(
+                        f"Labware Lid {params.loadName} may not be loaded on parent labware"
+                        f" {self._state_view.labware.get_display_name(verified_location.labwareId)}."
+                    )
+
         # Validate labware for the absorbance reader
-        elif isinstance(params.location, ModuleLocation):
-            module = self._state_view.modules.get(params.location.moduleId)
-            if module is not None and module.model == ModuleModel.ABSORBANCE_READER_V1:
-                self._state_view.labware.raise_if_labware_incompatible_with_plate_reader(
-                    loaded_labware.definition
-                )
+        if self._is_loading_to_module(
+            params.location, ModuleModel.ABSORBANCE_READER_V1
+        ):
+            self._state_view.labware.raise_if_labware_incompatible_with_plate_reader(
+                loaded_labware.definition
+            )
 
         self._state_view.labware.raise_if_labware_cannot_be_ondeck(
             location=params.location, labware_definition=loaded_labware.definition
@@ -202,6 +202,9 @@ class LoadLabwareImplementation(
                 labwareId=loaded_labware.labware_id,
                 definition=loaded_labware.definition,
                 offsetId=loaded_labware.offsetId,
+                locationSequence=self._state_view.geometry.get_predicted_location_sequence(
+                    verified_location,
+                ),
             ),
             state_update=state_update,
         )

opentrons/protocol_engine/commands/load_lid.py

@@ -1,4 +1,5 @@
 """Load lid command request, result, and implementation models."""
+
 from __future__ import annotations
 from pydantic import BaseModel, Field
 from typing import TYPE_CHECKING, Optional, Type
@@ -9,10 +10,12 @@ from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 from ..errors import LabwareCannotBeStackedError, LabwareIsNotAllowedInLocationError
 from ..resources import labware_validation
 from ..types import (
-    LabwareLocation,
+    LoadableLabwareLocation,
     OnLabwareLocation,
+    OnLabwareLocationSequenceComponent,
 )
 
+from .labware_handling_common import LabwareHandlingResultMixin
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
 from ..state.update_types import StateUpdate
@@ -28,7 +31,7 @@ LoadLidCommandType = Literal["loadLid"]
 class LoadLidParams(BaseModel):
     """Payload required to load a lid onto a labware."""
 
-    location: LabwareLocation = Field(
+    location: LoadableLabwareLocation = Field(
         ...,
         description="Labware the lid should be loaded onto.",
     )
@@ -46,13 +49,9 @@ class LoadLidParams(BaseModel):
     )
 
 
-class LoadLidResult(BaseModel):
+class LoadLidResult(LabwareHandlingResultMixin):
     """Result data from the execution of a LoadLabware command."""
 
-    labwareId: str = Field(
-        ...,
-        description="An ID to reference this lid labware in subsequent commands.",
-    )
     definition: LabwareDefinition = Field(
         ...,
         description="The full definition data for this lid labware.",
@@ -88,9 +87,6 @@ class LoadLidImplementation(
             labware_id=None,
         )
 
-        # TODO(chb 2024-12-12) these validation checks happen after the labware is loaded, because they rely on
-        #   on the definition. In practice this will not cause any issues since they will raise protocol ending
-        #   exception, but for correctness should be refactored to do this check beforehand.
         if not labware_validation.validate_definition_is_lid(loaded_labware.definition):
             raise LabwareCannotBeStackedError(
                 f"Labware {params.loadName} is not a Lid and cannot be loaded onto {self._state_view.labware.get_display_name(params.location.labwareId)}."
@@ -99,9 +95,9 @@ class LoadLidImplementation(
         state_update = StateUpdate()
 
         # In the case of lids being loaded on top of other labware, set the parent labware's lid
-        state_update.set_lid(
-            parent_labware_id=params.location.labwareId,
-            lid_id=loaded_labware.labware_id,
+        state_update.set_lids(
+            parent_labware_ids=[params.location.labwareId],
+            lid_ids=[loaded_labware.labware_id],
         )
 
         state_update.set_loaded_labware(
@@ -122,6 +118,18 @@ class LoadLidImplementation(
             public=LoadLidResult(
                 labwareId=loaded_labware.labware_id,
                 definition=loaded_labware.definition,
+                # Note: the lid is not yet loaded and therefore won't be found as the lid id for the
+                # labware onto which we're loading it, so build that part of the location sequence
+                # here and then build the rest of the sequence from the parent labware
+                locationSequence=[
+                    OnLabwareLocationSequenceComponent(
+                        labwareId=params.location.labwareId,
+                        lidId=loaded_labware.labware_id,
+                    )
+                ]
+                + self._state_view.geometry.get_location_sequence(
+                    params.location.labwareId
+                ),
             ),
             state_update=state_update,
         )

opentrons/protocol_engine/commands/load_lid_stack.py

@@ -1,7 +1,9 @@
 """Load lid stack command request, result, and implementation models."""
+
 from __future__ import annotations
 from pydantic import BaseModel, Field
-from typing import TYPE_CHECKING, Optional, Type, List
+from typing import TYPE_CHECKING, Optional, Type, List, Any
+from pydantic.json_schema import SkipJsonSchema
 from typing_extensions import Literal
 
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
@@ -9,10 +11,13 @@ from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 from ..errors import LabwareIsNotAllowedInLocationError, ProtocolEngineError
 from ..resources import fixture_validation, labware_validation
 from ..types import (
-    LabwareLocation,
+    LoadableLabwareLocation,
+    SYSTEM_LOCATION,
     OnLabwareLocation,
     DeckSlotLocation,
     AddressableAreaLocation,
+    LabwareLocationSequence,
+    OnLabwareLocationSequenceComponent,
 )
 
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
@@ -21,11 +26,16 @@ from ..state.update_types import StateUpdate
 
 if TYPE_CHECKING:
     from ..state.state import StateView
-    from ..execution import EquipmentHandler
+    from ..execution import LoadedLabwareData, EquipmentHandler
 
 
 LoadLidStackCommandType = Literal["loadLidStack"]
 
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
 _LID_STACK_PE_LABWARE = "protocol_engine_lid_stack_object"
 _LID_STACK_PE_NAMESPACE = "opentrons"
 _LID_STACK_PE_VERSION = 1
@@ -34,7 +44,7 @@ _LID_STACK_PE_VERSION = 1
 class LoadLidStackParams(BaseModel):
     """Payload required to load a lid stack onto a location."""
 
-    location: LabwareLocation = Field(
+    location: LoadableLabwareLocation = Field(
         ...,
         description="Location the lid stack should be loaded into.",
     )
@@ -50,6 +60,18 @@ class LoadLidStackParams(BaseModel):
         ...,
         description="The lid labware definition version.",
     )
+    stackLabwareId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="An optional ID to assign to the lid stack labware object created."
+        "If None, an ID will be generated.",
+        json_schema_extra=_remove_default,
+    )
+    labwareIds: List[str] | SkipJsonSchema[None] = Field(
+        None,
+        description="An optional list of IDs to assign to the lids in the stack."
+        "If None, an ID will be generated.",
+        json_schema_extra=_remove_default,
+    )
     quantity: int = Field(
         ...,
         description="The quantity of lids to load.",
@@ -61,19 +83,31 @@ class LoadLidStackResult(BaseModel):
 
     stackLabwareId: str = Field(
         ...,
-        description="An ID to reference the Protocol Engine Labware Lid Stack in subsequent commands.",
+        description="An ID to reference the lid stack labware object created.",
     )
     labwareIds: List[str] = Field(
         ...,
         description="A list of lid labware IDs to reference the lids in this stack by. The first ID is the bottom of the stack.",
     )
-    definition: LabwareDefinition = Field(
+    definition: LabwareDefinition | None = Field(
         ...,
         description="The full definition data for this lid labware.",
     )
-    location: LabwareLocation = Field(
+    location: LoadableLabwareLocation = Field(
         ..., description="The Location that the stack of lid labware has been loaded."
     )
+    lidStackDefinition: LabwareDefinition | None = Field(
+        None,
+        description="The definition of the lid stack object. Optional for backwards-compatibility.",
+    )
+    stackLocationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description="The location sequence for the lid stack labware object created.",
+    )
+    locationSequences: List[LabwareLocationSequence] | None = Field(
+        None,
+        description="The location sequences for the lids just loaded into the stack. These are in the same order as labwareIds.",
+    )
 
 
 class LoadLidStackImplementation(
@@ -87,10 +121,7 @@ class LoadLidStackImplementation(
         self._equipment = equipment
         self._state_view = state_view
 
-    async def execute(
-        self, params: LoadLidStackParams
-    ) -> SuccessData[LoadLidStackResult]:
-        """Load definition and calibration data necessary for a lid stack."""
+    def _validate_location(self, params: LoadLidStackParams) -> LoadableLabwareLocation:
         if isinstance(params.location, AddressableAreaLocation):
             area_name = params.location.addressableAreaName
             if not (
@@ -107,36 +138,47 @@ class LoadLidStackImplementation(
             self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
                 params.location.slotName.id
             )
-
-        verified_location = self._state_view.geometry.ensure_location_not_occupied(
-            params.location
-        )
-
-        lid_stack_object = await self._equipment.load_labware(
-            load_name=_LID_STACK_PE_LABWARE,
-            namespace=_LID_STACK_PE_NAMESPACE,
-            version=_LID_STACK_PE_VERSION,
-            location=verified_location,
-            labware_id=None,
-        )
-        if not labware_validation.validate_definition_is_system(
-            lid_stack_object.definition
-        ):
+        if params.quantity <= 0 and params.location != SYSTEM_LOCATION:
             raise ProtocolEngineError(
-                message="Lid Stack Labware Object Labware Definition does not contain required allowed role 'system'."
+                message="Lid Stack Labware Object with quantity 0 must be loaded onto System Location."
             )
+        return self._state_view.geometry.ensure_location_not_occupied(params.location)
 
-        loaded_lid_labwares = await self._equipment.load_lids(
-            load_name=params.loadName,
-            namespace=params.namespace,
-            version=params.version,
-            location=OnLabwareLocation(labwareId=lid_stack_object.labware_id),
-            quantity=params.quantity,
+    def _format_results(
+        self,
+        verified_location: LoadableLabwareLocation,
+        lid_stack_object: LoadedLabwareData,
+        loaded_lid_labwares: list[LoadedLabwareData],
+        lid_labware_definition: LabwareDefinition | None,
+    ) -> SuccessData[LoadLidStackResult]:
+        stack_location_sequence = (
+            self._state_view.geometry.get_predicted_location_sequence(verified_location)
         )
-        loaded_lid_locations_by_id = {}
+        loaded_lid_locations_by_id: dict[str, OnLabwareLocation] = {}
+        loaded_lid_ids_ordered: list[str] = []
+        loaded_lid_location_sequences_ordered: list[LabwareLocationSequence] = []
+        lid_location_sequence_accumulated: LabwareLocationSequence = [
+            OnLabwareLocationSequenceComponent(
+                labwareId=lid_stack_object.labware_id, lidId=None
+            )
+        ] + stack_location_sequence
         load_location = OnLabwareLocation(labwareId=lid_stack_object.labware_id)
+        last_lid_id: str | None = None
         for loaded_lid in loaded_lid_labwares:
             loaded_lid_locations_by_id[loaded_lid.labware_id] = load_location
+            loaded_lid_ids_ordered.append(loaded_lid.labware_id)
+            if last_lid_id is None:
+                last_lid_id = loaded_lid.labware_id
+            else:
+                lid_location_sequence_accumulated = [
+                    OnLabwareLocationSequenceComponent(
+                        labwareId=last_lid_id, lidId=None
+                    )
+                ] + lid_location_sequence_accumulated
+                last_lid_id = loaded_lid.labware_id
+            loaded_lid_location_sequences_ordered.append(
+                [loc for loc in lid_location_sequence_accumulated]
+            )
             load_location = OnLabwareLocation(labwareId=loaded_lid.labware_id)
 
         state_update = StateUpdate()
@@ -144,29 +186,70 @@ class LoadLidStackImplementation(
             stack_id=lid_stack_object.labware_id,
             stack_object_definition=lid_stack_object.definition,
             stack_location=verified_location,
-            labware_ids=list(loaded_lid_locations_by_id.keys()),
-            labware_definition=loaded_lid_labwares[0].definition,
             locations=loaded_lid_locations_by_id,
+            labware_definition=lid_labware_definition,
         )
 
-        if isinstance(verified_location, OnLabwareLocation):
-            self._state_view.labware.raise_if_labware_cannot_be_stacked(
-                top_labware_definition=loaded_lid_labwares[
-                    params.quantity - 1
-                ].definition,
-                bottom_labware_id=verified_location.labwareId,
-            )
-
         return SuccessData(
             public=LoadLidStackResult(
                 stackLabwareId=lid_stack_object.labware_id,
-                labwareIds=list(loaded_lid_locations_by_id.keys()),
-                definition=loaded_lid_labwares[0].definition,
-                location=params.location,
+                lidStackDefinition=lid_stack_object.definition,
+                labwareIds=loaded_lid_ids_ordered,
+                definition=lid_labware_definition,
+                location=verified_location,
+                stackLocationSequence=stack_location_sequence,
+                locationSequences=loaded_lid_location_sequences_ordered,
             ),
             state_update=state_update,
         )
 
+    async def execute(
+        self, params: LoadLidStackParams
+    ) -> SuccessData[LoadLidStackResult]:
+        """Load definition and calibration data necessary for a lid stack."""
+        verified_location = self._validate_location(params)
+
+        lid_stack_object = await self._equipment.load_labware(
+            load_name=_LID_STACK_PE_LABWARE,
+            namespace=_LID_STACK_PE_NAMESPACE,
+            version=_LID_STACK_PE_VERSION,
+            location=verified_location,
+            labware_id=params.stackLabwareId,
+        )
+
+        if not labware_validation.validate_definition_is_system(
+            lid_stack_object.definition
+        ):
+            raise ProtocolEngineError(
+                message="Lid Stack Labware Object Labware Definition does not contain required allowed role 'system'."
+            )
+
+        loaded_lid_labwares: list[LoadedLabwareData] = []
+        lid_labware_definition: LabwareDefinition | None = None
+
+        if params.quantity > 0:
+            loaded_lid_labwares = await self._equipment.load_lids(
+                load_name=params.loadName,
+                namespace=params.namespace,
+                version=params.version,
+                location=OnLabwareLocation(labwareId=lid_stack_object.labware_id),
+                quantity=params.quantity,
+                labware_ids=params.labwareIds,
+            )
+            lid_labware_definition = loaded_lid_labwares[-1].definition
+            if isinstance(verified_location, OnLabwareLocation):
+                self._state_view.labware.raise_if_labware_cannot_be_stacked(
+                    top_labware_definition=lid_labware_definition,
+                    bottom_labware_id=verified_location.labwareId,
+                )
+
+        return self._format_results(
+            verified_location,
+            lid_stack_object,
+            loaded_lid_labwares,
+            lid_labware_definition,
+        )
+
 
 class LoadLidStack(
     BaseCommand[LoadLidStackParams, LoadLidStackResult, ErrorOccurrence]

opentrons/protocol_engine/commands/load_module.py

@@ -11,6 +11,7 @@ from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, Succes
 from ..errors.error_occurrence import ErrorOccurrence
 from ..types import (
     DeckSlotLocation,
+    AddressableAreaLocation,
     ModuleType,
     ModuleModel,
     ModuleDefinition,
@@ -129,41 +130,41 @@ class LoadModuleImplementation(
         module_type = params.model.as_type()
         self._ensure_module_location(params.location.slotName, module_type)
 
-        # todo(mm, 2024-12-03): Theoretically, we should be able to deal with
-        # addressable areas and deck configurations the same way between OT-2 and Flex.
-        # Can this be simplified?
-        if self._state_view.config.robot_type == "OT-2 Standard":
-            self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
-                params.location.slotName.id
-            )
-        else:
-            addressable_area_provided_by_module = (
+        if self._state_view.modules.get_deck_supports_module_fixtures():
+            addressable_area_module_reference = (
                 self._state_view.modules.ensure_and_convert_module_fixture_location(
                     deck_slot=params.location.slotName,
                     model=params.model,
                 )
             )
-            self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
-                addressable_area_provided_by_module
+        else:
+            addressable_area_module_reference = params.location.slotName.id
+            state_update.set_addressable_area_used(
+                addressable_area_name=addressable_area_module_reference
             )
 
-        verified_location = self._state_view.geometry.ensure_location_not_occupied(
-            params.location
+        self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
+            addressable_area_module_reference
         )
-        state_update.set_addressable_area_used(
-            addressable_area_name=params.location.slotName.id
+
+        self._state_view.geometry.ensure_location_not_occupied(
+            params.location, addressable_area_module_reference
         )
 
         if params.model == ModuleModel.MAGNETIC_BLOCK_V1:
             loaded_module = await self._equipment.load_magnetic_block(
                 model=params.model,
-                location=verified_location,
+                location=AddressableAreaLocation(
+                    addressableAreaName=addressable_area_module_reference
+                ),
                 module_id=params.moduleId,
             )
         else:
             loaded_module = await self._equipment.load_module(
                 model=params.model,
-                location=verified_location,
+                location=AddressableAreaLocation(
+                    addressableAreaName=addressable_area_module_reference
+                ),
                 module_id=params.moduleId,
             )
 

opentrons/protocol_engine/commands/load_pipette.py

@@ -138,6 +138,9 @@ class LoadPipetteImplementation(
             config=loaded_pipette.static_config,
         )
         state_update.set_fluid_unknown(pipette_id=loaded_pipette.pipette_id)
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_id=loaded_pipette.pipette_id, ready_to_aspirate=False
+        ),
 
         return SuccessData(
             public=LoadPipetteResult(pipetteId=loaded_pipette.pipette_id),