opentrons 8.2.0a3__py2.py3-none-any.whl → 8.3.0__py2.py3-none-any.whl

opentrons/protocol_engine/commands/load_lid.py

@@ -0,0 +1,146 @@
+"""Load lid command request, result, and implementation models."""
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
+from ..errors import LabwareCannotBeStackedError, LabwareIsNotAllowedInLocationError
+from ..resources import labware_validation
+from ..types import (
+    LabwareLocation,
+    OnLabwareLocation,
+)
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..state.update_types import StateUpdate
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..execution import EquipmentHandler
+
+
+LoadLidCommandType = Literal["loadLid"]
+
+
+class LoadLidParams(BaseModel):
+    """Payload required to load a lid onto a labware."""
+
+    location: LabwareLocation = Field(
+        ...,
+        description="Labware the lid should be loaded onto.",
+    )
+    loadName: str = Field(
+        ...,
+        description="Name used to reference a lid labware definition.",
+    )
+    namespace: str = Field(
+        ...,
+        description="The namespace the lid labware definition belongs to.",
+    )
+    version: int = Field(
+        ...,
+        description="The lid labware definition version.",
+    )
+
+
+class LoadLidResult(BaseModel):
+    """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.",
+    )
+
+
+class LoadLidImplementation(
+    AbstractCommandImpl[LoadLidParams, SuccessData[LoadLidResult]]
+):
+    """Load lid command implementation."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, state_view: StateView, **kwargs: object
+    ) -> None:
+        self._equipment = equipment
+        self._state_view = state_view
+
+    async def execute(self, params: LoadLidParams) -> SuccessData[LoadLidResult]:
+        """Load definition and calibration data necessary for a lid."""
+        if not isinstance(params.location, OnLabwareLocation):
+            raise LabwareIsNotAllowedInLocationError(
+                "Lid Labware is only allowed to be loaded on top of a labware. Try `load_lid_stack(...)` to load lids without parent labware."
+            )
+
+        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,
+            version=params.version,
+            location=verified_location,
+            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)}."
+            )
+
+        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_loaded_labware(
+            labware_id=loaded_labware.labware_id,
+            offset_id=loaded_labware.offsetId,
+            definition=loaded_labware.definition,
+            location=verified_location,
+            display_name=None,
+        )
+
+        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,
+            )
+
+        return SuccessData(
+            public=LoadLidResult(
+                labwareId=loaded_labware.labware_id,
+                definition=loaded_labware.definition,
+            ),
+            state_update=state_update,
+        )
+
+
+class LoadLid(BaseCommand[LoadLidParams, LoadLidResult, ErrorOccurrence]):
+    """Load lid command resource model."""
+
+    commandType: LoadLidCommandType = "loadLid"
+    params: LoadLidParams
+    result: Optional[LoadLidResult] = None
+
+    _ImplementationCls: Type[LoadLidImplementation] = LoadLidImplementation
+
+
+class LoadLidCreate(BaseCommandCreate[LoadLidParams]):
+    """Load lid command creation request."""
+
+    commandType: LoadLidCommandType = "loadLid"
+    params: LoadLidParams
+
+    _CommandCls: Type[LoadLid] = LoadLid

opentrons/protocol_engine/commands/load_lid_stack.py

@@ -0,0 +1,189 @@
+"""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_extensions import Literal
+
+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,
+    OnLabwareLocation,
+    DeckSlotLocation,
+    AddressableAreaLocation,
+)
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..state.update_types import StateUpdate
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..execution import EquipmentHandler
+
+
+LoadLidStackCommandType = Literal["loadLidStack"]
+
+_LID_STACK_PE_LABWARE = "protocol_engine_lid_stack_object"
+_LID_STACK_PE_NAMESPACE = "opentrons"
+_LID_STACK_PE_VERSION = 1
+
+
+class LoadLidStackParams(BaseModel):
+    """Payload required to load a lid stack onto a location."""
+
+    location: LabwareLocation = Field(
+        ...,
+        description="Location the lid stack should be loaded into.",
+    )
+    loadName: str = Field(
+        ...,
+        description="Name used to reference a lid labware definition.",
+    )
+    namespace: str = Field(
+        ...,
+        description="The namespace the lid labware definition belongs to.",
+    )
+    version: int = Field(
+        ...,
+        description="The lid labware definition version.",
+    )
+    quantity: int = Field(
+        ...,
+        description="The quantity of lids to load.",
+    )
+
+
+class LoadLidStackResult(BaseModel):
+    """Result data from the execution of a LoadLidStack command."""
+
+    stackLabwareId: str = Field(
+        ...,
+        description="An ID to reference the Protocol Engine Labware Lid Stack in subsequent commands.",
+    )
+    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(
+        ...,
+        description="The full definition data for this lid labware.",
+    )
+    location: LabwareLocation = Field(
+        ..., description="The Location that the stack of lid labware has been loaded."
+    )
+
+
+class LoadLidStackImplementation(
+    AbstractCommandImpl[LoadLidStackParams, SuccessData[LoadLidStackResult]]
+):
+    """Load lid stack command implementation."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, state_view: StateView, **kwargs: object
+    ) -> None:
+        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."""
+        if isinstance(params.location, AddressableAreaLocation):
+            area_name = params.location.addressableAreaName
+            if not (
+                fixture_validation.is_deck_slot(params.location.addressableAreaName)
+                or fixture_validation.is_abs_reader(params.location.addressableAreaName)
+            ):
+                raise LabwareIsNotAllowedInLocationError(
+                    f"Cannot load {params.loadName} onto addressable area {area_name}"
+                )
+            self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
+                area_name
+            )
+        elif isinstance(params.location, DeckSlotLocation):
+            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
+        ):
+            raise ProtocolEngineError(
+                message="Lid Stack Labware Object Labware Definition does not contain required allowed role 'system'."
+            )
+
+        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,
+        )
+        loaded_lid_locations_by_id = {}
+        load_location = OnLabwareLocation(labwareId=lid_stack_object.labware_id)
+        for loaded_lid in loaded_lid_labwares:
+            loaded_lid_locations_by_id[loaded_lid.labware_id] = load_location
+            load_location = OnLabwareLocation(labwareId=loaded_lid.labware_id)
+
+        state_update = StateUpdate()
+        state_update.set_loaded_lid_stack(
+            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,
+        )
+
+        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,
+            ),
+            state_update=state_update,
+        )
+
+
+class LoadLidStack(
+    BaseCommand[LoadLidStackParams, LoadLidStackResult, ErrorOccurrence]
+):
+    """Load lid stack command resource model."""
+
+    commandType: LoadLidStackCommandType = "loadLidStack"
+    params: LoadLidStackParams
+    result: Optional[LoadLidStackResult] = None
+
+    _ImplementationCls: Type[LoadLidStackImplementation] = LoadLidStackImplementation
+
+
+class LoadLidStackCreate(BaseCommandCreate[LoadLidStackParams]):
+    """Load lid stack command creation request."""
+
+    commandType: LoadLidStackCommandType = "loadLidStack"
+    params: LoadLidStackParams
+
+    _CommandCls: Type[LoadLidStack] = LoadLidStack

opentrons/protocol_engine/commands/load_liquid.py

@@ -5,6 +5,8 @@ from typing import Optional, Type, Dict, TYPE_CHECKING
 from typing_extensions import Literal
 
 from opentrons.protocol_engine.state.update_types import StateUpdate
+from opentrons.protocol_engine.types import LiquidId
+from opentrons.protocol_engine.errors import InvalidLiquidError
 
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
@@ -19,9 +21,9 @@ LoadLiquidCommandType = Literal["loadLiquid"]
 class LoadLiquidParams(BaseModel):
     """Payload required to load a liquid into a well."""
 
-    liquidId: str = Field(
+    liquidId: LiquidId = Field(
         ...,
-        description="Unique identifier of the liquid to load.",
+        description="Unique identifier of the liquid to load. If this is the sentinel value EMPTY, all values of volumeByWell must be 0.",
     )
     labwareId: str = Field(
         ...,
@@ -29,7 +31,7 @@ class LoadLiquidParams(BaseModel):
     )
     volumeByWell: Dict[str, float] = Field(
         ...,
-        description="Volume of liquid, in µL, loaded into each well by name, in this labware.",
+        description="Volume of liquid, in µL, loaded into each well by name, in this labware. If the liquid id is the sentinel value EMPTY, all volumes must be 0.",
     )
 
 
@@ -57,6 +59,12 @@ class LoadLiquidImplementation(
         self._state_view.labware.validate_liquid_allowed_in_labware(
             labware_id=params.labwareId, wells=params.volumeByWell
         )
+        if params.liquidId == "EMPTY":
+            for well_name, volume in params.volumeByWell.items():
+                if volume != 0.0:
+                    raise InvalidLiquidError(
+                        'loadLiquid commands that specify the special liquid "EMPTY" must set volume to be 0.0, but the volume for {well_name} is {volume}'
+                    )
 
         state_update = StateUpdate()
         state_update.set_liquid_loaded(
@@ -73,7 +81,7 @@ class LoadLiquid(BaseCommand[LoadLiquidParams, LoadLiquidResult, ErrorOccurrence
 
     commandType: LoadLiquidCommandType = "loadLiquid"
     params: LoadLiquidParams
-    result: Optional[LoadLiquidResult]
+    result: Optional[LoadLiquidResult] = None
 
     _ImplementationCls: Type[LoadLiquidImplementation] = LoadLiquidImplementation
 

opentrons/protocol_engine/commands/load_liquid_class.py

@@ -0,0 +1,144 @@
+"""LoadLiquidClass stores the liquid class settings used for a transfer into the Protocol Engine."""
+from __future__ import annotations
+
+from typing import Optional, Type, TYPE_CHECKING, Any
+
+from typing_extensions import Literal
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors import LiquidClassDoesNotExistError
+from ..errors.error_occurrence import ErrorOccurrence
+from ..errors.exceptions import LiquidClassRedefinitionError
+from ..state.update_types import LiquidClassLoadedUpdate, StateUpdate
+from ..types import LiquidClassRecord
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..resources import ModelUtils
+
+LoadLiquidClassCommandType = Literal["loadLiquidClass"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class LoadLiquidClassParams(BaseModel):
+    """The liquid class transfer properties to store."""
+
+    liquidClassId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Unique identifier for the liquid class to store. "
+        "If you do not supply a liquidClassId, we will generate one.",
+        json_schema_extra=_remove_default,
+    )
+    liquidClassRecord: LiquidClassRecord = Field(
+        ...,
+        description="The liquid class to store.",
+    )
+
+
+class LoadLiquidClassResult(BaseModel):
+    """Result from execution of LoadLiquidClass command."""
+
+    liquidClassId: str = Field(
+        ...,
+        description="The ID for the liquid class that was loaded, either the one you "
+        "supplied or the one we generated.",
+    )
+
+
+class LoadLiquidClassImplementation(
+    AbstractCommandImpl[LoadLiquidClassParams, SuccessData[LoadLiquidClassResult]]
+):
+    """Load Liquid Class command implementation."""
+
+    def __init__(
+        self, state_view: StateView, model_utils: ModelUtils, **kwargs: object
+    ) -> None:
+        self._state_view = state_view
+        self._model_utils = model_utils
+
+    async def execute(
+        self, params: LoadLiquidClassParams
+    ) -> SuccessData[LoadLiquidClassResult]:
+        """Store the liquid class in the Protocol Engine."""
+        liquid_class_id: Optional[str]
+        already_loaded = False
+
+        if params.liquidClassId:
+            liquid_class_id = params.liquidClassId
+            if self._liquid_class_id_already_loaded(
+                liquid_class_id, params.liquidClassRecord
+            ):
+                already_loaded = True
+        else:
+            liquid_class_id = (
+                self._state_view.liquid_classes.get_id_for_liquid_class_record(
+                    params.liquidClassRecord
+                )  # if liquidClassRecord was already loaded, reuse the existing ID
+            )
+            if liquid_class_id:
+                already_loaded = True
+            else:
+                liquid_class_id = self._model_utils.generate_id()
+
+        if already_loaded:
+            state_update = StateUpdate()  # liquid class already loaded, do nothing
+        else:
+            state_update = StateUpdate(
+                liquid_class_loaded=LiquidClassLoadedUpdate(
+                    liquid_class_id=liquid_class_id,
+                    liquid_class_record=params.liquidClassRecord,
+                )
+            )
+
+        return SuccessData(
+            public=LoadLiquidClassResult(liquidClassId=liquid_class_id),
+            state_update=state_update,
+        )
+
+    def _liquid_class_id_already_loaded(
+        self, liquid_class_id: str, liquid_class_record: LiquidClassRecord
+    ) -> bool:
+        """Check if the liquid_class_id has already been loaded.
+
+        If it has, make sure that liquid_class_record matches the previously loaded definition.
+        """
+        try:
+            existing_liquid_class_record = self._state_view.liquid_classes.get(
+                liquid_class_id
+            )
+        except LiquidClassDoesNotExistError:
+            return False
+
+        if liquid_class_record != existing_liquid_class_record:
+            raise LiquidClassRedefinitionError(
+                f"Liquid class {liquid_class_id} conflicts with previously loaded definition."
+            )
+        return True
+
+
+class LoadLiquidClass(
+    BaseCommand[LoadLiquidClassParams, LoadLiquidClassResult, ErrorOccurrence]
+):
+    """Load Liquid Class command resource model."""
+
+    commandType: LoadLiquidClassCommandType = "loadLiquidClass"
+    params: LoadLiquidClassParams
+    result: Optional[LoadLiquidClassResult] = None
+
+    _ImplementationCls: Type[
+        LoadLiquidClassImplementation
+    ] = LoadLiquidClassImplementation
+
+
+class LoadLiquidClassCreate(BaseCommandCreate[LoadLiquidClassParams]):
+    """Load Liquid Class command creation request."""
+
+    commandType: LoadLiquidClassCommandType = "loadLiquidClass"
+    params: LoadLiquidClassParams
+
+    _CommandCls: Type[LoadLiquidClass] = LoadLiquidClass

opentrons/protocol_engine/commands/load_module.py

@@ -1,8 +1,11 @@
 """Implementation, request models, and response models for the load module command."""
 from __future__ import annotations
-from typing import TYPE_CHECKING, Optional, Type
+from typing import TYPE_CHECKING, Optional, Type, Any
 from typing_extensions import Literal
 from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.protocol_engine.state.update_types import StateUpdate
 
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
 from ..errors.error_occurrence import ErrorOccurrence
@@ -25,6 +28,10 @@ if TYPE_CHECKING:
 LoadModuleCommandType = Literal["loadModule"]
 
 
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
 class LoadModuleParams(BaseModel):
     """Payload required to load a module."""
 
@@ -57,12 +64,13 @@ class LoadModuleParams(BaseModel):
         ),
     )
 
-    moduleId: Optional[str] = Field(
+    moduleId: str | SkipJsonSchema[None] = Field(
         None,
         description=(
             "An optional ID to assign to this module."
             " If None, an ID will be generated."
         ),
+        json_schema_extra=_remove_default,
     )
 
 
@@ -75,7 +83,7 @@ class LoadModuleResult(BaseModel):
 
     # TODO(mm, 2023-04-13): Remove this field. Jira RSS-221.
     definition: ModuleDefinition = Field(
-        deprecated=True,
+        json_schema_extra={"deprecated": True},
         description=(
             "The definition of the connected module."
             " This field is an implementation detail. We might change or remove it without warning."
@@ -116,26 +124,35 @@ class LoadModuleImplementation(
 
     async def execute(self, params: LoadModuleParams) -> SuccessData[LoadModuleResult]:
         """Check that the requested module is attached and assign its identifier."""
+        state_update = StateUpdate()
+
         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 = self._state_view.geometry._modules.ensure_and_convert_module_fixture_location(
-                deck_slot=params.location.slotName,
-                deck_type=self._state_view.config.deck_type,
-                model=params.model,
+            addressable_area_provided_by_module = (
+                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
+                addressable_area_provided_by_module
             )
 
         verified_location = self._state_view.geometry.ensure_location_not_occupied(
             params.location
         )
+        state_update.set_addressable_area_used(
+            addressable_area_name=params.location.slotName.id
+        )
 
         if params.model == ModuleModel.MAGNETIC_BLOCK_V1:
             loaded_module = await self._equipment.load_magnetic_block(
@@ -157,11 +174,15 @@ class LoadModuleImplementation(
                 model=loaded_module.definition.model,
                 definition=loaded_module.definition,
             ),
+            state_update=state_update,
         )
 
     def _ensure_module_location(
         self, slot: DeckSlotName, module_type: ModuleType
     ) -> None:
+        # 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":
             slot_def = self._state_view.addressable_areas.get_slot_definition(slot.id)
             compatible_modules = slot_def["compatibleModuleTypes"]
@@ -173,7 +194,7 @@ class LoadModuleImplementation(
             cutout_fixture_id = ModuleType.to_module_fixture_id(module_type)
             module_fixture = deck_configuration_provider.get_cutout_fixture(
                 cutout_fixture_id,
-                self._state_view.addressable_areas.state.deck_definition,
+                self._state_view.labware.get_deck_definition(),
             )
             cutout_id = (
                 self._state_view.addressable_areas.get_cutout_id_by_deck_slot_name(slot)
@@ -189,7 +210,7 @@ class LoadModule(BaseCommand[LoadModuleParams, LoadModuleResult, ErrorOccurrence
 
     commandType: LoadModuleCommandType = "loadModule"
     params: LoadModuleParams
-    result: Optional[LoadModuleResult]
+    result: Optional[LoadModuleResult] = None
 
     _ImplementationCls: Type[LoadModuleImplementation] = LoadModuleImplementation