opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/commands/move_to_addressable_area.py

@@ -0,0 +1,176 @@
+"""Move to addressable area command request, result, and implementation models."""
+from __future__ import annotations
+from pydantic import Field
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+
+from opentrons_shared_data.pipette.types import PipetteNameType
+
+from ..errors import LocationNotAccessibleByPipetteError
+from ..types import AddressableOffsetVector
+from ..resources import fixture_validation
+from .pipetting_common import (
+    PipetteIdMixin,
+)
+from .movement_common import (
+    MovementMixin,
+    DestinationPositionResult,
+    move_to_addressable_area,
+    StallOrCollisionError,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler
+    from ..state.state import StateView
+    from ..resources.model_utils import ModelUtils
+
+MoveToAddressableAreaCommandType = Literal["moveToAddressableArea"]
+
+
+class MoveToAddressableAreaParams(PipetteIdMixin, MovementMixin):
+    """Payload required to move a pipette to a specific addressable area.
+
+    An *addressable area* is a space in the robot that may or may not be usable depending on how
+    the robot's deck is configured. For example, if a Flex is configured with a waste chute, it will
+    have additional addressable areas representing the opening of the waste chute, where tips and
+    labware can be dropped.
+
+    This moves the pipette so all of its nozzles are centered over the addressable area.
+    If the pipette is currently configured with a partial tip layout, this centering is over all
+    the pipette's physical nozzles, not just the nozzles that are active.
+
+    The z-position will be chosen to put the bottom of the tips---or the bottom of the nozzles,
+    if there are no tips---level with the top of the addressable area.
+
+    When this command is executed, Protocol Engine will make sure the robot's deck is configured
+    such that the requested addressable area actually exists. For example, if you request
+    the addressable area B4, it will make sure the robot is set up with a B3/B4 staging area slot.
+    If that's not the case, the command will fail.
+    """
+
+    addressableAreaName: str = Field(
+        ...,
+        description=(
+            "The name of the addressable area that you want to use."
+            " Valid values are the `id`s of `addressableArea`s in the"
+            " [deck definition](https://github.com/Opentrons/opentrons/tree/edge/shared-data/deck)."
+        ),
+    )
+    offset: AddressableOffsetVector = Field(
+        AddressableOffsetVector(x=0, y=0, z=0),
+        description="Relative offset of addressable area to move pipette's critical point.",
+    )
+    stayAtHighestPossibleZ: bool = Field(
+        False,
+        description=(
+            "If `true`, the pipette will retract to its highest possible height"
+            " and stay there instead of descending to the destination."
+            " `minimumZHeight` will be ignored."
+        ),
+    )
+
+
+class MoveToAddressableAreaResult(DestinationPositionResult):
+    """Result data from the execution of a MoveToAddressableArea command."""
+
+    pass
+
+
+_ExecuteReturn = (
+    SuccessData[MoveToAddressableAreaResult] | DefinedErrorData[StallOrCollisionError]
+)
+
+
+class MoveToAddressableAreaImplementation(
+    AbstractCommandImpl[MoveToAddressableAreaParams, _ExecuteReturn]
+):
+    """Move to addressable area command implementation."""
+
+    def __init__(
+        self,
+        movement: MovementHandler,
+        state_view: StateView,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._movement = movement
+        self._state_view = state_view
+        self._model_utils = model_utils
+
+    async def execute(self, params: MoveToAddressableAreaParams) -> _ExecuteReturn:
+        """Move the requested pipette to the requested addressable area."""
+        self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
+            params.addressableAreaName
+        )
+        loaded_pipette = self._state_view.pipettes.get(params.pipetteId)
+        if loaded_pipette.pipetteName in (
+            PipetteNameType.P10_SINGLE,
+            PipetteNameType.P10_MULTI,
+            PipetteNameType.P50_MULTI,
+            PipetteNameType.P50_SINGLE,
+            PipetteNameType.P300_SINGLE,
+            PipetteNameType.P300_MULTI,
+            PipetteNameType.P1000_SINGLE,
+        ):
+            extra_z_offset: Optional[float] = 5.0
+        else:
+            extra_z_offset = None
+
+        if fixture_validation.is_staging_slot(params.addressableAreaName):
+            raise LocationNotAccessibleByPipetteError(
+                f"Cannot move pipette to staging slot {params.addressableAreaName}"
+            )
+
+        result = await move_to_addressable_area(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            addressable_area_name=params.addressableAreaName,
+            offset=params.offset,
+            force_direct=params.forceDirect,
+            minimum_z_height=params.minimumZHeight,
+            speed=params.speed,
+            stay_at_highest_possible_z=params.stayAtHighestPossibleZ,
+            highest_possible_z_extra_offset=extra_z_offset,
+        )
+        if isinstance(result, DefinedErrorData):
+            return result
+        else:
+            return SuccessData(
+                public=MoveToAddressableAreaResult(position=result.public.position),
+                state_update=result.state_update,
+            )
+
+
+class MoveToAddressableArea(
+    BaseCommand[
+        MoveToAddressableAreaParams,
+        MoveToAddressableAreaResult,
+        StallOrCollisionError,
+    ]
+):
+    """Move to addressable area command model."""
+
+    commandType: MoveToAddressableAreaCommandType = "moveToAddressableArea"
+    params: MoveToAddressableAreaParams
+    result: Optional[MoveToAddressableAreaResult] = None
+
+    _ImplementationCls: Type[
+        MoveToAddressableAreaImplementation
+    ] = MoveToAddressableAreaImplementation
+
+
+class MoveToAddressableAreaCreate(BaseCommandCreate[MoveToAddressableAreaParams]):
+    """Move to addressable area command creation request model."""
+
+    commandType: MoveToAddressableAreaCommandType = "moveToAddressableArea"
+    params: MoveToAddressableAreaParams
+
+    _CommandCls: Type[MoveToAddressableArea] = MoveToAddressableArea

opentrons/protocol_engine/commands/move_to_addressable_area_for_drop_tip.py

@@ -0,0 +1,198 @@
+"""Move to addressable area for drop tip command request, result, and implementation models."""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Any
+from typing_extensions import Literal
+
+from pydantic import Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..errors import LocationNotAccessibleByPipetteError
+from ..types import AddressableOffsetVector
+from ..resources import fixture_validation
+from .pipetting_common import (
+    PipetteIdMixin,
+)
+from .movement_common import (
+    MovementMixin,
+    DestinationPositionResult,
+    move_to_addressable_area,
+    StallOrCollisionError,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler
+    from ..state.state import StateView
+    from ..resources.model_utils import ModelUtils
+
+MoveToAddressableAreaForDropTipCommandType = Literal["moveToAddressableAreaForDropTip"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class MoveToAddressableAreaForDropTipParams(PipetteIdMixin, MovementMixin):
+    """Payload required to move a pipette to a specific addressable area.
+
+    An *addressable area* is a space in the robot that may or may not be usable depending on how
+    the robot's deck is configured. For example, if a Flex is configured with a waste chute, it will
+    have additional addressable areas representing the opening of the waste chute, where tips and
+    labware can be dropped.
+
+    This moves the pipette so all of its nozzles are centered over the addressable area.
+    If the pipette is currently configured with a partial tip layout, this centering is over all
+    the pipette's physical nozzles, not just the nozzles that are active.
+
+    The z-position will be chosen to put the bottom of the tips---or the bottom of the nozzles,
+    if there are no tips---level with the top of the addressable area.
+
+    When this command is executed, Protocol Engine will make sure the robot's deck is configured
+    such that the requested addressable area actually exists. For example, if you request
+    the addressable area B4, it will make sure the robot is set up with a B3/B4 staging area slot.
+    If that's not the case, the command will fail.
+    """
+
+    addressableAreaName: str = Field(
+        ...,
+        description=(
+            "The name of the addressable area that you want to use."
+            " Valid values are the `id`s of `addressableArea`s in the"
+            " [deck definition](https://github.com/Opentrons/opentrons/tree/edge/shared-data/deck)."
+        ),
+    )
+    offset: AddressableOffsetVector = Field(
+        AddressableOffsetVector(x=0, y=0, z=0),
+        description="Relative offset of addressable area to move pipette's critical point.",
+    )
+    alternateDropLocation: bool | SkipJsonSchema[None] = Field(
+        False,
+        description=(
+            "Whether to alternate location where tip is dropped within the addressable area."
+            " If True, this command will ignore the offset provided and alternate"
+            " between dropping tips at two predetermined locations inside the specified"
+            " labware well."
+            " If False, the tip will be dropped at the top center of the area."
+        ),
+        json_schema_extra=_remove_default,
+    )
+    ignoreTipConfiguration: bool | SkipJsonSchema[None] = Field(
+        True,
+        description=(
+            "Whether to utilize the critical point of the tip configuraiton when moving to an addressable area."
+            " If True, this command will ignore the tip configuration and use the center of the entire instrument"
+            " as the critical point for movement."
+            " If False, this command will use the critical point provided by the current tip configuration."
+        ),
+        json_schema_extra=_remove_default,
+    )
+
+
+class MoveToAddressableAreaForDropTipResult(DestinationPositionResult):
+    """Result data from the execution of a MoveToAddressableAreaForDropTip command."""
+
+    pass
+
+
+_ExecuteReturn = (
+    SuccessData[MoveToAddressableAreaForDropTipResult]
+    | DefinedErrorData[StallOrCollisionError]
+)
+
+
+class MoveToAddressableAreaForDropTipImplementation(
+    AbstractCommandImpl[MoveToAddressableAreaForDropTipParams, _ExecuteReturn]
+):
+    """Move to addressable area for drop tip command implementation."""
+
+    def __init__(
+        self,
+        movement: MovementHandler,
+        state_view: StateView,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._movement = movement
+        self._state_view = state_view
+        self._model_utils = model_utils
+
+    async def execute(
+        self, params: MoveToAddressableAreaForDropTipParams
+    ) -> _ExecuteReturn:
+        """Move the requested pipette to the requested addressable area in preperation of a drop tip."""
+        self._state_view.addressable_areas.raise_if_area_not_in_deck_configuration(
+            params.addressableAreaName
+        )
+
+        if fixture_validation.is_staging_slot(params.addressableAreaName):
+            raise LocationNotAccessibleByPipetteError(
+                f"Cannot move pipette to staging slot {params.addressableAreaName}"
+            )
+
+        if params.alternateDropLocation:
+            offset = self._state_view.geometry.get_next_tip_drop_location_for_addressable_area(
+                addressable_area_name=params.addressableAreaName,
+                pipette_id=params.pipetteId,
+            )
+        else:
+            offset = params.offset
+
+        result = await move_to_addressable_area(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            addressable_area_name=params.addressableAreaName,
+            offset=offset,
+            force_direct=params.forceDirect,
+            minimum_z_height=params.minimumZHeight,
+            speed=params.speed,
+            ignore_tip_configuration=params.ignoreTipConfiguration,
+        )
+        if isinstance(result, DefinedErrorData):
+            return result
+        else:
+            return SuccessData(
+                public=MoveToAddressableAreaForDropTipResult(
+                    position=result.public.position,
+                ),
+                state_update=result.state_update,
+            )
+
+
+class MoveToAddressableAreaForDropTip(
+    BaseCommand[
+        MoveToAddressableAreaForDropTipParams,
+        MoveToAddressableAreaForDropTipResult,
+        StallOrCollisionError,
+    ]
+):
+    """Move to addressable area for drop tip command model."""
+
+    commandType: MoveToAddressableAreaForDropTipCommandType = (
+        "moveToAddressableAreaForDropTip"
+    )
+    params: MoveToAddressableAreaForDropTipParams
+    result: Optional[MoveToAddressableAreaForDropTipResult] = None
+
+    _ImplementationCls: Type[
+        MoveToAddressableAreaForDropTipImplementation
+    ] = MoveToAddressableAreaForDropTipImplementation
+
+
+class MoveToAddressableAreaForDropTipCreate(
+    BaseCommandCreate[MoveToAddressableAreaForDropTipParams]
+):
+    """Move to addressable area for drop tip command creation request model."""
+
+    commandType: MoveToAddressableAreaForDropTipCommandType = (
+        "moveToAddressableAreaForDropTip"
+    )
+    params: MoveToAddressableAreaForDropTipParams
+
+    _CommandCls: Type[MoveToAddressableAreaForDropTip] = MoveToAddressableAreaForDropTip

opentrons/protocol_engine/commands/move_to_coordinates.py

@@ -0,0 +1,107 @@
+"""Move to coordinates command request, result, and implementation models."""
+from __future__ import annotations
+
+from pydantic import Field
+from typing import Optional, Type, TYPE_CHECKING
+from typing_extensions import Literal
+
+
+from ..types import DeckPoint
+from .pipetting_common import PipetteIdMixin
+from .movement_common import (
+    MovementMixin,
+    DestinationPositionResult,
+    move_to_coordinates,
+    StallOrCollisionError,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler
+    from ..resources.model_utils import ModelUtils
+
+
+MoveToCoordinatesCommandType = Literal["moveToCoordinates"]
+
+
+class MoveToCoordinatesParams(PipetteIdMixin, MovementMixin):
+    """Payload required to move a pipette to coordinates."""
+
+    coordinates: DeckPoint = Field(
+        ...,
+        description="X, Y and Z coordinates in mm from deck's origin location (left-front-bottom corner of work space)",
+    )
+
+
+class MoveToCoordinatesResult(DestinationPositionResult):
+    """Result data from the execution of a MoveToCoordinates command."""
+
+    pass
+
+
+_ExecuteReturn = (
+    SuccessData[MoveToCoordinatesResult] | DefinedErrorData[StallOrCollisionError]
+)
+
+
+class MoveToCoordinatesImplementation(
+    AbstractCommandImpl[MoveToCoordinatesParams, _ExecuteReturn]
+):
+    """Move to coordinates command implementation."""
+
+    def __init__(
+        self,
+        movement: MovementHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._movement = movement
+        self._model_utils = model_utils
+
+    async def execute(self, params: MoveToCoordinatesParams) -> _ExecuteReturn:
+        """Move the requested pipette to the requested coordinates."""
+        result = await move_to_coordinates(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            deck_coordinates=params.coordinates,
+            direct=params.forceDirect,
+            additional_min_travel_z=params.minimumZHeight,
+            speed=params.speed,
+        )
+        if isinstance(result, DefinedErrorData):
+            return result
+        else:
+            return SuccessData(
+                public=MoveToCoordinatesResult(position=result.public.position),
+                state_update=result.state_update,
+            )
+
+
+class MoveToCoordinates(
+    BaseCommand[MoveToCoordinatesParams, MoveToCoordinatesResult, StallOrCollisionError]
+):
+    """Move to well command model."""
+
+    commandType: MoveToCoordinatesCommandType = "moveToCoordinates"
+    params: MoveToCoordinatesParams
+    result: Optional[MoveToCoordinatesResult] = None
+
+    _ImplementationCls: Type[
+        MoveToCoordinatesImplementation
+    ] = MoveToCoordinatesImplementation
+
+
+class MoveToCoordinatesCreate(BaseCommandCreate[MoveToCoordinatesParams]):
+    """Move to coordinates command creation request model."""
+
+    commandType: MoveToCoordinatesCommandType = "moveToCoordinates"
+    params: MoveToCoordinatesParams
+
+    _CommandCls: Type[MoveToCoordinates] = MoveToCoordinates

opentrons/protocol_engine/commands/move_to_well.py

@@ -0,0 +1,119 @@
+"""Move to well command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type
+from typing_extensions import Literal
+
+from .pipetting_common import (
+    PipetteIdMixin,
+)
+from .movement_common import (
+    LiquidHandlingWellLocationMixin,
+    MovementMixin,
+    DestinationPositionResult,
+    StallOrCollisionError,
+    move_to_well,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler
+    from ..state.state import StateView
+    from ..resources.model_utils import ModelUtils
+
+MoveToWellCommandType = Literal["moveToWell"]
+
+
+class MoveToWellParams(PipetteIdMixin, LiquidHandlingWellLocationMixin, MovementMixin):
+    """Payload required to move a pipette to a specific well."""
+
+    pass
+
+
+class MoveToWellResult(DestinationPositionResult):
+    """Result data from the execution of a MoveToWell command."""
+
+    pass
+
+
+class MoveToWellImplementation(
+    AbstractCommandImpl[
+        MoveToWellParams,
+        SuccessData[MoveToWellResult] | DefinedErrorData[StallOrCollisionError],
+    ]
+):
+    """Move to well command implementation."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        movement: MovementHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._movement = movement
+        self._model_utils = model_utils
+
+    async def execute(
+        self, params: MoveToWellParams
+    ) -> SuccessData[MoveToWellResult] | DefinedErrorData[StallOrCollisionError]:
+        """Move the requested pipette to the requested well."""
+        pipette_id = params.pipetteId
+        labware_id = params.labwareId
+        well_name = params.wellName
+        well_location = params.wellLocation
+        # TODO(cm): implement move_to_well with meniscus + volume offset
+        if well_location.volumeOffset:
+            if (
+                well_location.volumeOffset != 0
+                and well_location.volumeOffset != "operationVolume"
+            ):
+                raise ValueError("volume offset not supported with MoveToWell")
+
+        move_result = await move_to_well(
+            model_utils=self._model_utils,
+            movement=self._movement,
+            pipette_id=pipette_id,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+            force_direct=params.forceDirect,
+            minimum_z_height=params.minimumZHeight,
+            speed=params.speed,
+            operation_volume=None,
+        )
+        if isinstance(move_result, DefinedErrorData):
+            return move_result
+        else:
+            return SuccessData(
+                public=MoveToWellResult(position=move_result.public.position),
+                state_update=move_result.state_update,
+            )
+
+
+class MoveToWell(
+    BaseCommand[MoveToWellParams, MoveToWellResult, StallOrCollisionError]
+):
+    """Move to well command model."""
+
+    commandType: MoveToWellCommandType = "moveToWell"
+    params: MoveToWellParams
+    result: Optional[MoveToWellResult] = None
+
+    _ImplementationCls: Type[MoveToWellImplementation] = MoveToWellImplementation
+
+
+class MoveToWellCreate(BaseCommandCreate[MoveToWellParams]):
+    """Move to well command creation request model."""
+
+    commandType: MoveToWellCommandType = "moveToWell"
+    params: MoveToWellParams
+
+    _CommandCls: Type[MoveToWell] = MoveToWell