opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/load_lid.py

@@ -0,0 +1,154 @@
+"""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 (
+    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
+
+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: LoadableLabwareLocation = 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(LabwareHandlingResultMixin):
+    """Result data from the execution of a LoadLabware command."""
+
+    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,
+        )
+
+        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_lids(
+            parent_labware_ids=[params.location.labwareId],
+            lid_ids=[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,
+                # 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,
+        )
+
+
+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,272 @@
+"""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, Any
+from pydantic.json_schema import SkipJsonSchema
+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 (
+    LoadableLabwareLocation,
+    SYSTEM_LOCATION,
+    OnLabwareLocation,
+    DeckSlotLocation,
+    AddressableAreaLocation,
+    LabwareLocationSequence,
+    OnLabwareLocationSequenceComponent,
+)
+
+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 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
+
+
+class LoadLidStackParams(BaseModel):
+    """Payload required to load a lid stack onto a location."""
+
+    location: LoadableLabwareLocation = 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.",
+    )
+    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.",
+    )
+
+
+class LoadLidStackResult(BaseModel):
+    """Result data from the execution of a LoadLidStack command."""
+
+    stackLabwareId: str = Field(
+        ...,
+        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 | None = Field(
+        ...,
+        description="The full definition data for this lid labware.",
+    )
+    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(
+    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
+
+    def _validate_location(self, params: LoadLidStackParams) -> LoadableLabwareLocation:
+        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
+            )
+        if params.quantity <= 0 and params.location != SYSTEM_LOCATION:
+            raise ProtocolEngineError(
+                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)
+
+    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: 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()
+        state_update.set_loaded_lid_stack(
+            stack_id=lid_stack_object.labware_id,
+            stack_object_definition=lid_stack_object.definition,
+            stack_location=verified_location,
+            locations=loaded_lid_locations_by_id,
+            labware_definition=lid_labware_definition,
+        )
+
+        return SuccessData(
+            public=LoadLidStackResult(
+                stackLabwareId=lid_stack_object.labware_id,
+                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]
+):
+    """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

@@ -0,0 +1,95 @@
+"""Load liquid command request, result, and implementation models."""
+from __future__ import annotations
+from pydantic import BaseModel, Field
+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
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+    from ..resources import ModelUtils
+
+LoadLiquidCommandType = Literal["loadLiquid"]
+
+
+class LoadLiquidParams(BaseModel):
+    """Payload required to load a liquid into a well."""
+
+    liquidId: LiquidId = Field(
+        ...,
+        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(
+        ...,
+        description="Unique identifier of labware to load liquid into.",
+    )
+    volumeByWell: Dict[str, float] = Field(
+        ...,
+        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.",
+    )
+
+
+class LoadLiquidResult(BaseModel):
+    """Result data from the execution of a LoadLiquid command."""
+
+    pass
+
+
+class LoadLiquidImplementation(
+    AbstractCommandImpl[LoadLiquidParams, SuccessData[LoadLiquidResult]]
+):
+    """Load liquid 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: LoadLiquidParams) -> SuccessData[LoadLiquidResult]:
+        """Load data necessary for a liquid."""
+        self._state_view.liquid.validate_liquid_id(params.liquidId)
+
+        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(
+            labware_id=params.labwareId,
+            volumes=params.volumeByWell,
+            last_loaded=self._model_utils.get_timestamp(),
+        )
+
+        return SuccessData(public=LoadLiquidResult(), state_update=state_update)
+
+
+class LoadLiquid(BaseCommand[LoadLiquidParams, LoadLiquidResult, ErrorOccurrence]):
+    """Load liquid command resource model."""
+
+    commandType: LoadLiquidCommandType = "loadLiquid"
+    params: LoadLiquidParams
+    result: Optional[LoadLiquidResult] = None
+
+    _ImplementationCls: Type[LoadLiquidImplementation] = LoadLiquidImplementation
+
+
+class LoadLiquidCreate(BaseCommandCreate[LoadLiquidParams]):
+    """Load liquid command creation request."""
+
+    commandType: LoadLiquidCommandType = "loadLiquid"
+    params: LoadLiquidParams
+
+    _CommandCls: Type[LoadLiquid] = LoadLiquid

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