opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/flex_stacker/retrieve.py

@@ -0,0 +1,339 @@
+"""Command models to retrieve a labware from a Flex Stacker."""
+
+from __future__ import annotations
+from typing import Literal, TYPE_CHECKING, Any, Union
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons_shared_data.errors.exceptions import (
+    FlexStackerStallError,
+    FlexStackerShuttleMissingError,
+    FlexStackerHopperLabwareError,
+    FlexStackerShuttleLabwareError,
+    FlexStackerShuttleNotEmptyError,
+)
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ...errors import (
+    ErrorOccurrence,
+    CannotPerformModuleAction,
+    LocationIsOccupiedError,
+    FlexStackerLabwarePoolNotYetDefinedError,
+)
+from ...resources import ModelUtils
+from ...state import update_types
+from ...types import (
+    ModuleLocation,
+    LabwareLocationSequence,
+    InStackerHopperLocation,
+)
+from .common import (
+    labware_locations_for_group,
+    build_retrieve_labware_move_updates,
+    FlexStackerStallOrCollisionError,
+    FlexStackerShuttleError,
+    FlexStackerHopperError,
+    FlexStackerLabwareRetrieveError,
+    FlexStackerShuttleOccupiedError,
+    primary_location_sequence,
+    adapter_location_sequence,
+    lid_location_sequence,
+)
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+RetrieveCommandType = Literal["flexStacker/retrieve"]
+
+RecoverableExceptions = Union[
+    FlexStackerStallError,
+    FlexStackerShuttleMissingError,
+    FlexStackerHopperLabwareError,
+    FlexStackerShuttleLabwareError,
+    FlexStackerShuttleNotEmptyError,
+]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class RetrieveParams(BaseModel):
+    """Input parameters for a labware retrieval command."""
+
+    moduleId: str = Field(
+        ...,
+        description="Unique ID of the Flex Stacker.",
+    )
+    labwareId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Do not use. Present for internal backward compatibility.",
+        json_schema_extra=_remove_default,
+    )
+    displayName: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Do not use. Present for internal backward compatibility.",
+        json_schema_extra=_remove_default,
+    )
+    adapterId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Do not use. Present for internal backward compatibility.",
+        json_schema_extra=_remove_default,
+    )
+    lidId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Do not use. Present for internal backward compatibility.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class RetrieveResult(BaseModel):
+    """Result data from a labware retrieval command."""
+
+    labwareId: str = Field(
+        ...,
+        description="The labware ID of the primary retrieved labware.",
+    )
+    adapterId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The optional Adapter Labware ID of the adapter under a primary labware.",
+    )
+    lidId: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The optional Lid Labware ID of the lid on a primary labware.",
+    )
+    primaryLocationSequence: LabwareLocationSequence = Field(
+        ..., description="The new location of the just-retrieved."
+    )
+    lidLocationSequence: LabwareLocationSequence | SkipJsonSchema[None] = Field(
+        None,
+        description="The new location of the just-retrieved adapter labware under a primary labware.",
+    )
+    adapterLocationSequence: LabwareLocationSequence | SkipJsonSchema[None] = Field(
+        None,
+        description="The new location of the just-retrieved lid labware on a primary labware.",
+    )
+    originalPrimaryLocationSequence: LabwareLocationSequence = Field(
+        ..., description="The original location of the just-retrieved primary labware"
+    )
+    originalAdapterLocationSequence: LabwareLocationSequence | SkipJsonSchema[
+        None
+    ] = Field(None, description="The original location of an adapter labware if any")
+    originalLidLocationSequence: LabwareLocationSequence | SkipJsonSchema[None] = Field(
+        None, description="The original location of a lid labware if any"
+    )
+    primaryLabwareURI: str = Field(
+        ...,
+        description="The labware definition URI of the primary labware.",
+    )
+    adapterLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the adapter labware.",
+    )
+    lidLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the lid labware.",
+    )
+
+
+_ExecuteReturn = Union[
+    SuccessData[RetrieveResult],
+    DefinedErrorData[FlexStackerStallOrCollisionError]
+    | DefinedErrorData[FlexStackerShuttleError]
+    | DefinedErrorData[FlexStackerHopperError]
+    | DefinedErrorData[FlexStackerLabwareRetrieveError]
+    | DefinedErrorData[FlexStackerShuttleOccupiedError],
+]
+
+
+class RetrieveImpl(AbstractCommandImpl[RetrieveParams, _ExecuteReturn]):
+    """Implementation of a labware retrieval command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+        self._model_utils = model_utils
+
+    def handle_recoverable_error(
+        self,
+        error: RecoverableExceptions,
+        intended_id: str,
+        state_update: update_types.StateUpdate,
+    ) -> (
+        DefinedErrorData[FlexStackerStallOrCollisionError]
+        | DefinedErrorData[FlexStackerShuttleError]
+        | DefinedErrorData[FlexStackerHopperError]
+        | DefinedErrorData[FlexStackerLabwareRetrieveError]
+        | DefinedErrorData[FlexStackerShuttleOccupiedError]
+    ):
+        """Handle a recoverable error raised during command execution."""
+        error_map = {
+            FlexStackerStallError: FlexStackerStallOrCollisionError,
+            FlexStackerShuttleMissingError: FlexStackerShuttleError,
+            FlexStackerHopperLabwareError: FlexStackerHopperError,
+            FlexStackerShuttleLabwareError: FlexStackerLabwareRetrieveError,
+            FlexStackerShuttleNotEmptyError: FlexStackerShuttleOccupiedError,
+        }
+        return DefinedErrorData(
+            public=error_map[type(error)](
+                id=self._model_utils.generate_id(),
+                createdAt=self._model_utils.get_timestamp(),
+                wrappedErrors=[
+                    ErrorOccurrence.from_failed(
+                        id=self._model_utils.generate_id(),
+                        createdAt=self._model_utils.get_timestamp(),
+                        error=error,
+                    )
+                ],
+                errorInfo={"labwareId": intended_id},
+            ),
+            state_update_if_false_positive=state_update,
+        )
+
+    async def execute(self, params: RetrieveParams) -> _ExecuteReturn:
+        """Execute the labware retrieval command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+        location = self._state_view.modules.get_location(params.moduleId)
+
+        if stacker_state.pool_primary_definition is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                f"The Flex Stacker in {location} must be configured before labware can be retrieved."
+            )
+
+        if len(stacker_state.contained_labware_bottom_first) == 0:
+            raise CannotPerformModuleAction(
+                message=f"Cannot retrieve labware from Flex Stacker in {location} because it contains no labware"
+            )
+
+        stacker_loc = ModuleLocation(moduleId=params.moduleId)
+
+        try:
+            self._state_view.labware.raise_if_labware_in_location(stacker_loc)
+        except LocationIsOccupiedError:
+            raise CannotPerformModuleAction(
+                f"Cannot retrieve a labware from Flex Stacker in {location} if the carriage is occupied"
+            )
+
+        to_retrieve = stacker_state.contained_labware_bottom_first[0]
+        remaining = stacker_state.contained_labware_bottom_first[1:]
+
+        locations, offsets = build_retrieve_labware_move_updates(
+            to_retrieve, stacker_state, self._state_view
+        )
+
+        # Update the state to reflect the labware is now in the Flex Stacker slot
+        # todo(chb, 2025-02-19): This ModuleLocation piece should probably instead be an AddressableAreaLocation
+        # but that has implications for where labware are set by things like module.load_labware(..) and what
+        # happens when we move labware.
+        stacker_area = (
+            self._state_view.modules.ensure_and_convert_module_fixture_location(
+                deck_slot=self._state_view.modules.get_location(
+                    params.moduleId
+                ).slotName,
+                model=self._state_view.modules.get(params.moduleId).model,
+            )
+        )
+        original_locations = labware_locations_for_group(
+            to_retrieve, [InStackerHopperLocation(moduleId=params.moduleId)]
+        )
+        new_locations = labware_locations_for_group(
+            to_retrieve,
+            self._state_view.geometry.get_predicted_location_sequence(
+                ModuleLocation(moduleId=params.moduleId)
+            ),
+        )
+
+        state_update = (
+            update_types.StateUpdate()
+            .set_batch_labware_location(
+                new_locations_by_id=locations, new_offset_ids_by_id=offsets
+            )
+            .update_flex_stacker_contained_labware(params.moduleId, remaining)
+            .set_addressable_area_used(stacker_area)
+        )
+
+        # Allow propagation of ModuleNotAttachedError.
+        stacker_hw = self._equipment.get_module_hardware_api(stacker_state.module_id)
+        if stacker_hw is not None:
+            try:
+                stacker_hw.set_stacker_identify(True)
+                await stacker_hw.dispense_labware(
+                    labware_height=stacker_state.get_pool_height_minus_overlap()
+                )
+            except (
+                FlexStackerStallError,
+                FlexStackerShuttleMissingError,
+                FlexStackerHopperLabwareError,
+                FlexStackerShuttleLabwareError,
+                FlexStackerShuttleNotEmptyError,
+            ) as e:
+                return self.handle_recoverable_error(
+                    e, to_retrieve.primaryLabwareId, state_update
+                )
+
+        if stacker_hw is not None:
+            stacker_hw.set_stacker_identify(False)
+
+        return SuccessData(
+            public=RetrieveResult.model_construct(
+                labwareId=to_retrieve.primaryLabwareId,
+                adapterId=to_retrieve.adapterLabwareId,
+                lidId=to_retrieve.lidLabwareId,
+                primaryLocationSequence=primary_location_sequence(new_locations),
+                adapterLocationSequence=adapter_location_sequence(new_locations),
+                lidLocationSequence=lid_location_sequence(new_locations),
+                originalPrimaryLocationSequence=primary_location_sequence(
+                    original_locations
+                ),
+                originalAdapterLocationSequence=adapter_location_sequence(
+                    original_locations
+                ),
+                originalLidLocationSequence=lid_location_sequence(original_locations),
+                primaryLabwareURI=self._state_view.labware.get_uri_from_definition(
+                    stacker_state.pool_primary_definition
+                ),
+                adapterLabwareURI=self._state_view.labware.get_uri_from_definition_unless_none(
+                    stacker_state.pool_adapter_definition
+                ),
+                lidLabwareURI=self._state_view.labware.get_uri_from_definition_unless_none(
+                    stacker_state.pool_lid_definition
+                ),
+            ),
+            state_update=state_update,
+        )
+
+
+class Retrieve(BaseCommand[RetrieveParams, RetrieveResult, ErrorOccurrence]):
+    """A command to retrieve a labware from a Flex Stacker."""
+
+    commandType: RetrieveCommandType = "flexStacker/retrieve"
+    params: RetrieveParams
+    result: RetrieveResult | None = None
+
+    _ImplementationCls: Type[RetrieveImpl] = RetrieveImpl
+
+
+class RetrieveCreate(BaseCommandCreate[RetrieveParams]):
+    """A request to execute a Flex Stacker retrieve command."""
+
+    commandType: RetrieveCommandType = "flexStacker/retrieve"
+    params: RetrieveParams
+
+    _CommandCls: Type[Retrieve] = Retrieve

opentrons/protocol_engine/commands/flex_stacker/set_stored_labware.py

@@ -0,0 +1,328 @@
+"""Command models to configure the stored labware pool of a Flex Stacker.."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Annotated
+from typing_extensions import Type
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import (
+    ErrorOccurrence,
+)
+from ...errors.exceptions import FlexStackerNotLogicallyEmptyError
+from ...types import (
+    StackerStoredLabwareGroup,
+    LabwareLocationSequence,
+    NotOnDeckLocationSequenceComponent,
+    InStackerHopperLocation,
+    SYSTEM_LOCATION,
+)
+from .common import (
+    INITIAL_COUNT_DESCRIPTION,
+    INITIAL_STORED_LABWARE_DESCRIPTION,
+    build_ids_to_fill,
+    build_or_assign_labware_to_hopper,
+    labware_locations_for_group,
+    labware_location_base_sequence,
+    primary_location_sequences,
+    adapter_location_sequences_with_default,
+    lid_location_sequences_with_default,
+)
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+    from opentrons.protocol_engine.resources import ModelUtils
+
+SetStoredLabwareCommandType = Literal["flexStacker/setStoredLabware"]
+
+
+class StackerStoredLabwareDetails(BaseModel):
+    """The parameters defining a labware to be stored in the stacker."""
+
+    loadName: str = Field(
+        ..., description="Name used to reference the definition of this labware."
+    )
+    namespace: str = Field(
+        ..., description="Namespace of the definition of this labware."
+    )
+    version: int = Field(..., description="Version of the definition of this labware.")
+
+
+class SetStoredLabwareParams(BaseModel):
+    """Input parameters for a setStoredLabware command."""
+
+    moduleId: str = Field(
+        ...,
+        description="Unique ID of the Flex Stacker.",
+    )
+    primaryLabware: StackerStoredLabwareDetails = Field(
+        ...,
+        description="The details of the primary labware (i.e. not the lid or adapter, if any) stored in the stacker.",
+    )
+    lidLabware: StackerStoredLabwareDetails | SkipJsonSchema[None] = Field(
+        default=None,
+        description="The details of the lid on the primary labware, if any.",
+    )
+    adapterLabware: StackerStoredLabwareDetails | SkipJsonSchema[None] = Field(
+        default=None,
+        description="The details of the adapter under the primary labware, if any.",
+    )
+    initialCount: Optional[Annotated[int, Field(ge=0)]] = Field(
+        None,
+        description=INITIAL_COUNT_DESCRIPTION,
+    )
+    initialStoredLabware: list[StackerStoredLabwareGroup] | None = Field(
+        None,
+        description=INITIAL_STORED_LABWARE_DESCRIPTION,
+    )
+    poolOverlapOverride: Optional[float] = Field(
+        None,
+        description=(
+            "Override for the Z stacking overlap of the labware pool. If not "
+            "provided, the protocol engine will calculate the overlap based on "
+            "the stacking offsets provided in the labware definitions."
+        ),
+    )
+
+
+class SetStoredLabwareResult(BaseModel):
+    """Result data from a setstoredlabware command."""
+
+    primaryLabwareDefinition: LabwareDefinition = Field(
+        ..., description="The definition of the primary labware."
+    )
+    lidLabwareDefinition: LabwareDefinition | SkipJsonSchema[None] = Field(
+        None, description="The definition of the lid on the primary labware, if any."
+    )
+    adapterLabwareDefinition: LabwareDefinition | SkipJsonSchema[None] = Field(
+        None,
+        description="The definition of the adapter under the primary labware, if any.",
+    )
+    storedLabware: list[StackerStoredLabwareGroup] = Field(
+        ..., description="The primary labware loaded into the stacker labware pool."
+    )
+    count: int = Field(
+        ..., description="The number of labware now stored in the hopper."
+    )
+    originalPrimaryLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The previous position of each primary labware, in the same order as storedLabware.",
+    )
+    originalAdapterLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The previous position of each adapter labware, in the same order as storedLabware. None if the pool does not specify an adapter.",
+    )
+    originalLidLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The previous position of each lid labware, in the same order as storedLabware. None if the pool does not specify a lid.",
+    )
+    newPrimaryLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The new position of each primary labware, in the same order as storedLabware.",
+    )
+    newAdapterLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The new position of each adapter labware, in the same order as storedLabware. None if the pool does not specify an adapter.",
+    )
+    newLidLabwareLocationSequences: (
+        list[LabwareLocationSequence] | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description="The new position of each lid labware, in the same order as storedLabware. None if the pool does not specify a lid labware.",
+    )
+
+
+class SetStoredLabwareImpl(
+    AbstractCommandImpl[SetStoredLabwareParams, SuccessData[SetStoredLabwareResult]]
+):
+    """Implementation of a setstoredlabware command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+        self._model_utils = model_utils
+
+    async def execute(
+        self, params: SetStoredLabwareParams
+    ) -> SuccessData[SetStoredLabwareResult]:
+        """Execute the setstoredlabwarecommand."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+        location = self._state_view.modules.get_location(params.moduleId)
+
+        if len(stacker_state.contained_labware_bottom_first) != 0:
+            # Note: this error catches if the protocol tells us the stacker is not empty, making this command
+            # invalid at this point in the protocol. This error is not recoverable and should occur during
+            # analysis; the protocol must be changed.
+
+            raise FlexStackerNotLogicallyEmptyError(
+                message=(
+                    f"The Flex Stacker in {location} must be known to be empty before reconfiguring its labware pool, but it has "
+                    f"{len(stacker_state.contained_labware_bottom_first)} labware"
+                )
+            )
+
+        labware_def, _ = await self._equipment.load_definition_for_details(
+            load_name=params.primaryLabware.loadName,
+            namespace=params.primaryLabware.namespace,
+            version=params.primaryLabware.version,
+        )
+        lid_def: LabwareDefinition | None = None
+        if params.lidLabware:
+            lid_def, _ = await self._equipment.load_definition_for_details(
+                load_name=params.lidLabware.loadName,
+                namespace=params.lidLabware.namespace,
+                version=params.lidLabware.version,
+            )
+        adapter_def: LabwareDefinition | None = None
+        if params.adapterLabware:
+            adapter_def, _ = await self._equipment.load_definition_for_details(
+                load_name=params.adapterLabware.loadName,
+                namespace=params.adapterLabware.namespace,
+                version=params.adapterLabware.version,
+            )
+
+        pool_definitions = (
+            self._state_view.labware.stacker_labware_pool_to_ordered_list(
+                labware_def, lid_def, adapter_def
+            )
+        )
+
+        pool_height = self._state_view.geometry.get_height_of_labware_stack(
+            pool_definitions
+        )
+
+        pool_overlap = (
+            params.poolOverlapOverride
+            if params.poolOverlapOverride
+            else self._state_view.labware.get_stacker_labware_overlap_offset(
+                pool_definitions
+            ).z
+        )
+
+        max_pool_count = self._state_view.modules.stacker_max_pool_count_by_height(
+            params.moduleId,
+            pool_height,
+            pool_overlap,
+        )
+        groups_to_load = build_ids_to_fill(
+            params.adapterLabware is not None,
+            params.lidLabware is not None,
+            params.initialStoredLabware,
+            params.initialCount,
+            max_pool_count,
+            0,
+            self._model_utils,
+        )
+        state_update, new_contained_labware = await build_or_assign_labware_to_hopper(
+            labware_def,
+            adapter_def,
+            lid_def,
+            params.moduleId,
+            groups_to_load,
+            [],
+            self._equipment,
+            self._state_view,
+        )
+
+        state_update = state_update.update_flex_stacker_labware_pool_definition(
+            params.moduleId,
+            max_pool_count,
+            pool_overlap,
+            pool_height,
+            labware_def,
+            adapter_def,
+            lid_def,
+        )
+        original_location_sequences = [
+            labware_locations_for_group(
+                group,
+                labware_location_base_sequence(
+                    group,
+                    self._state_view,
+                    [
+                        NotOnDeckLocationSequenceComponent(
+                            logicalLocationName=SYSTEM_LOCATION
+                        )
+                    ],
+                ),
+            )
+            for group in new_contained_labware
+        ]
+        new_location_sequences = [
+            labware_locations_for_group(
+                group, [InStackerHopperLocation(moduleId=params.moduleId)]
+            )
+            for group in new_contained_labware
+        ]
+        return SuccessData(
+            public=SetStoredLabwareResult.model_construct(
+                primaryLabwareDefinition=labware_def,
+                lidLabwareDefinition=lid_def,
+                adapterLabwareDefinition=adapter_def,
+                count=len(new_contained_labware),
+                storedLabware=new_contained_labware,
+                originalPrimaryLabwareLocationSequences=primary_location_sequences(
+                    original_location_sequences
+                ),
+                originalAdapterLabwareLocationSequences=adapter_location_sequences_with_default(
+                    original_location_sequences, adapter_def
+                ),
+                originalLidLabwareLocationSequences=lid_location_sequences_with_default(
+                    original_location_sequences, lid_def
+                ),
+                newPrimaryLabwareLocationSequences=primary_location_sequences(
+                    new_location_sequences
+                ),
+                newAdapterLabwareLocationSequences=adapter_location_sequences_with_default(
+                    new_location_sequences, adapter_def
+                ),
+                newLidLabwareLocationSequences=lid_location_sequences_with_default(
+                    new_location_sequences, lid_def
+                ),
+            ),
+            state_update=state_update,
+        )
+
+
+class SetStoredLabware(
+    BaseCommand[SetStoredLabwareParams, SetStoredLabwareResult, ErrorOccurrence]
+):
+    """A command to setstoredlabware the Flex Stacker."""
+
+    commandType: SetStoredLabwareCommandType = "flexStacker/setStoredLabware"
+    params: SetStoredLabwareParams
+    result: Optional[SetStoredLabwareResult] = None
+
+    _ImplementationCls: Type[SetStoredLabwareImpl] = SetStoredLabwareImpl
+
+
+class SetStoredLabwareCreate(BaseCommandCreate[SetStoredLabwareParams]):
+    """A request to execute a Flex Stacker SetStoredLabware command."""
+
+    commandType: SetStoredLabwareCommandType = "flexStacker/setStoredLabware"
+    params: SetStoredLabwareParams
+
+    _CommandCls: Type[SetStoredLabware] = SetStoredLabware