opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/commands/aspirate_in_place.py

@@ -0,0 +1,184 @@
+"""Aspirate in place command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from opentrons.hardware_control import HardwareControlAPI
+
+from .pipetting_common import (
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    BaseLiquidHandlingResult,
+    OverpressureError,
+    aspirate_in_place,
+    DEFAULT_CORRECTION_VOLUME,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..errors.exceptions import PipetteNotReadyToAspirateError
+from ..state.update_types import CLEAR
+from ..types import CurrentWell
+
+if TYPE_CHECKING:
+    from ..execution import PipettingHandler, GantryMover
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+    from ..notes import CommandNoteAdder
+
+AspirateInPlaceCommandType = Literal["aspirateInPlace"]
+
+
+class AspirateInPlaceParams(PipetteIdMixin, AspirateVolumeMixin, FlowRateMixin):
+    """Payload required to aspirate in place."""
+
+    pass
+
+
+class AspirateInPlaceResult(BaseLiquidHandlingResult):
+    """Result data from the execution of a AspirateInPlace command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[AspirateInPlaceResult],
+    DefinedErrorData[OverpressureError],
+]
+
+
+class AspirateInPlaceImplementation(
+    AbstractCommandImpl[AspirateInPlaceParams, _ExecuteReturn]
+):
+    """AspirateInPlace command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        hardware_api: HardwareControlAPI,
+        state_view: StateView,
+        command_note_adder: CommandNoteAdder,
+        model_utils: ModelUtils,
+        gantry_mover: GantryMover,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._command_note_adder = command_note_adder
+        self._model_utils = model_utils
+        self._gantry_mover = gantry_mover
+
+    async def execute(self, params: AspirateInPlaceParams) -> _ExecuteReturn:
+        """Aspirate without moving the pipette.
+
+        Raises:
+            TipNotAttachedError: if no tip is attached to the pipette.
+            PipetteNotReadyToAspirateError: pipette plunger is not ready.
+        """
+        ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
+            pipette_id=params.pipetteId
+        )
+        if not ready_to_aspirate:
+            raise PipetteNotReadyToAspirateError(
+                "Pipette cannot aspirate in place because a previous dispense or blowout"
+                " pushed the plunger beyond the bottom position."
+                " The subsequent aspirate must be from a specific well so the plunger"
+                " can be reset in a known safe position."
+            )
+
+        current_position = await self._gantry_mover.get_position(params.pipetteId)
+        current_location = self._state_view.pipettes.get_current_location()
+
+        result = await aspirate_in_place(
+            pipette_id=params.pipetteId,
+            volume=params.volume,
+            flow_rate=params.flowRate,
+            location_if_error={
+                "retryLocation": (
+                    current_position.x,
+                    current_position.y,
+                    current_position.z,
+                )
+            },
+            command_note_adder=self._command_note_adder,
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+            correction_volume=params.correctionVolume or DEFAULT_CORRECTION_VOLUME,
+        )
+        if isinstance(result, DefinedErrorData):
+            if (
+                isinstance(current_location, CurrentWell)
+                and current_location.pipette_id == params.pipetteId
+            ):
+                return DefinedErrorData(
+                    public=result.public,
+                    state_update=result.state_update.set_liquid_operated(
+                        labware_id=current_location.labware_id,
+                        well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                            current_location.labware_id,
+                            current_location.well_name,
+                            params.pipetteId,
+                        ),
+                        volume_added=CLEAR,
+                    ),
+                    state_update_if_false_positive=result.state_update_if_false_positive,
+                )
+            else:
+                return result
+        else:
+            if (
+                isinstance(current_location, CurrentWell)
+                and current_location.pipette_id == params.pipetteId
+            ):
+                return SuccessData(
+                    public=AspirateInPlaceResult(volume=result.public.volume),
+                    state_update=result.state_update.set_liquid_operated(
+                        labware_id=current_location.labware_id,
+                        well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                            current_location.labware_id,
+                            current_location.well_name,
+                            params.pipetteId,
+                        ),
+                        volume_added=-result.public.volume
+                        * self._state_view.geometry.get_nozzles_per_well(
+                            current_location.labware_id,
+                            current_location.well_name,
+                            params.pipetteId,
+                        ),
+                    ),
+                )
+            else:
+                return SuccessData(
+                    public=AspirateInPlaceResult(volume=result.public.volume),
+                    state_update=result.state_update,
+                )
+
+
+class AspirateInPlace(
+    BaseCommand[AspirateInPlaceParams, AspirateInPlaceResult, OverpressureError]
+):
+    """AspirateInPlace command model."""
+
+    commandType: AspirateInPlaceCommandType = "aspirateInPlace"
+    params: AspirateInPlaceParams
+    result: Optional[AspirateInPlaceResult] = None
+
+    _ImplementationCls: Type[
+        AspirateInPlaceImplementation
+    ] = AspirateInPlaceImplementation
+
+
+class AspirateInPlaceCreate(BaseCommandCreate[AspirateInPlaceParams]):
+    """AspirateInPlace command request model."""
+
+    commandType: AspirateInPlaceCommandType = "aspirateInPlace"
+    params: AspirateInPlaceParams
+
+    _CommandCls: Type[AspirateInPlace] = AspirateInPlace

opentrons/protocol_engine/commands/aspirate_while_tracking.py

@@ -0,0 +1,211 @@
+"""Aspirate command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from .pipetting_common import (
+    OverpressureError,
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    BaseLiquidHandlingResult,
+    aspirate_while_tracking,
+)
+from .movement_common import (
+    LiquidHandlingWellLocationMixin,
+    DestinationPositionResult,
+    StallOrCollisionError,
+    move_to_well,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    DefinedErrorData,
+    SuccessData,
+)
+from ..state.update_types import StateUpdate
+from ..errors.exceptions import PipetteNotReadyToAspirateError
+from opentrons.hardware_control import HardwareControlAPI
+from ..state.update_types import CLEAR
+from ..types import DeckPoint
+
+if TYPE_CHECKING:
+    from ..execution import PipettingHandler, GantryMover, MovementHandler
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+    from ..notes import CommandNoteAdder
+
+
+AspirateWhileTrackingCommandType = Literal["aspirateWhileTracking"]
+
+
+class AspirateWhileTrackingParams(
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    LiquidHandlingWellLocationMixin,
+):
+    """Parameters required to aspirate from a specific well."""
+
+    pass
+
+
+class AspirateWhileTrackingResult(BaseLiquidHandlingResult, DestinationPositionResult):
+    """Result data from execution of an Aspirate command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[AspirateWhileTrackingResult],
+    DefinedErrorData[OverpressureError] | DefinedErrorData[StallOrCollisionError],
+]
+
+
+class AspirateWhileTrackingImplementation(
+    AbstractCommandImpl[AspirateWhileTrackingParams, _ExecuteReturn]
+):
+    """AspirateWhileTracking command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        state_view: StateView,
+        hardware_api: HardwareControlAPI,
+        command_note_adder: CommandNoteAdder,
+        model_utils: ModelUtils,
+        gantry_mover: GantryMover,
+        movement: MovementHandler,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._command_note_adder = command_note_adder
+        self._model_utils = model_utils
+        self._gantry_mover = gantry_mover
+        self._movement = movement
+
+    async def execute(self, params: AspirateWhileTrackingParams) -> _ExecuteReturn:
+        """Move to and aspirate from the requested well.
+
+        Raises:
+            TipNotAttachedError: if no tip is attached to the pipette.
+            PipetteNotReadyToAspirateError: pipette plunger is not ready.
+        """
+        ready_to_aspirate = self._state_view.pipettes.get_ready_to_aspirate(
+            pipette_id=params.pipetteId
+        )
+        if not ready_to_aspirate:
+            raise PipetteNotReadyToAspirateError(
+                "Pipette cannot aspirate while tracking because a previous dispense or"
+                " blowout pushed the plunger beyond the bottom position."
+                " The subsequent aspirate must be from a specific well so the plunger"
+                " can be reset in a known safe position."
+            )
+        state_update = StateUpdate()
+
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            labware_id=params.labwareId,
+            well_name=params.wellName,
+            well_location=params.wellLocation,
+            operation_volume=-params.volume,
+        )
+        state_update.append(move_result.state_update)
+        if isinstance(move_result, DefinedErrorData):
+            return DefinedErrorData(
+                public=move_result.public, state_update=state_update
+            )
+
+        aspirate_result = await aspirate_while_tracking(
+            pipette_id=params.pipetteId,
+            labware_id=params.labwareId,
+            well_name=params.wellName,
+            volume=params.volume,
+            flow_rate=params.flowRate,
+            location_if_error={
+                "retryLocation": (
+                    move_result.public.position.x,
+                    move_result.public.position.y,
+                    move_result.public.position.z,
+                )
+            },
+            command_note_adder=self._command_note_adder,
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+        )
+        position_after_aspirate = await self._gantry_mover.get_position(
+            params.pipetteId
+        )
+        result_deck_point = DeckPoint.model_construct(
+            x=position_after_aspirate.x,
+            y=position_after_aspirate.y,
+            z=position_after_aspirate.z,
+        )
+        if isinstance(aspirate_result, DefinedErrorData):
+            return DefinedErrorData(
+                public=aspirate_result.public,
+                state_update=aspirate_result.state_update.set_liquid_operated(
+                    labware_id=params.labwareId,
+                    well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                        params.labwareId,
+                        params.wellName,
+                        params.pipetteId,
+                    ),
+                    volume_added=CLEAR,
+                ),
+                state_update_if_false_positive=aspirate_result.state_update_if_false_positive,
+            )
+
+        return SuccessData(
+            public=AspirateWhileTrackingResult(
+                volume=aspirate_result.public.volume,
+                position=result_deck_point,
+            ),
+            state_update=aspirate_result.state_update.set_liquid_operated(
+                labware_id=params.labwareId,
+                well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                    params.labwareId,
+                    params.wellName,
+                    params.pipetteId,
+                ),
+                volume_added=-aspirate_result.public.volume
+                * self._state_view.geometry.get_nozzles_per_well(
+                    params.labwareId,
+                    params.wellName,
+                    params.pipetteId,
+                ),
+            ),
+        )
+
+
+class AspirateWhileTracking(
+    BaseCommand[
+        AspirateWhileTrackingParams,
+        AspirateWhileTrackingResult,
+        OverpressureError | StallOrCollisionError,
+    ]
+):
+    """AspirateWhileTracking command model."""
+
+    commandType: AspirateWhileTrackingCommandType = "aspirateWhileTracking"
+    params: AspirateWhileTrackingParams
+    result: Optional[AspirateWhileTrackingResult] = None
+
+    _ImplementationCls: Type[
+        AspirateWhileTrackingImplementation
+    ] = AspirateWhileTrackingImplementation
+
+
+class AspirateWhileTrackingCreate(BaseCommandCreate[AspirateWhileTrackingParams]):
+    """Create aspirateWhileTracking command request model."""
+
+    commandType: AspirateWhileTrackingCommandType = "aspirateWhileTracking"
+    params: AspirateWhileTrackingParams
+
+    _CommandCls: Type[AspirateWhileTracking] = AspirateWhileTracking

opentrons/protocol_engine/commands/blow_out.py

@@ -0,0 +1,146 @@
+"""Blow-out command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+
+from .pipetting_common import (
+    OverpressureError,
+    PipetteIdMixin,
+    FlowRateMixin,
+    blow_out_in_place,
+)
+from .movement_common import (
+    WellLocationMixin,
+    DestinationPositionResult,
+    move_to_well,
+    StallOrCollisionError,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    DefinedErrorData,
+    SuccessData,
+)
+from ..state.update_types import StateUpdate
+
+from opentrons.hardware_control import HardwareControlAPI
+
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler, PipettingHandler
+    from ..state.state import StateView
+    from ..resources import ModelUtils
+
+
+BlowOutCommandType = Literal["blowout"]
+
+
+class BlowOutParams(PipetteIdMixin, FlowRateMixin, WellLocationMixin):
+    """Payload required to blow-out a specific well."""
+
+    pass
+
+
+class BlowOutResult(DestinationPositionResult):
+    """Result data from the execution of a blow-out command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[BlowOutResult],
+    DefinedErrorData[OverpressureError] | DefinedErrorData[StallOrCollisionError],
+]
+
+
+class BlowOutImplementation(AbstractCommandImpl[BlowOutParams, _ExecuteReturn]):
+    """BlowOut command implementation."""
+
+    def __init__(
+        self,
+        movement: MovementHandler,
+        pipetting: PipettingHandler,
+        state_view: StateView,
+        hardware_api: HardwareControlAPI,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._movement = movement
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._model_utils = model_utils
+
+    async def execute(self, params: BlowOutParams) -> _ExecuteReturn:
+        """Move to and blow-out the requested well."""
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            labware_id=params.labwareId,
+            well_name=params.wellName,
+            well_location=params.wellLocation,
+        )
+        if isinstance(move_result, DefinedErrorData):
+            return move_result
+        blow_out_result = await blow_out_in_place(
+            pipette_id=params.pipetteId,
+            flow_rate=params.flowRate,
+            location_if_error={
+                "retryLocation": (
+                    move_result.public.position.x,
+                    move_result.public.position.y,
+                    move_result.public.position.z,
+                )
+            },
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+        )
+        if isinstance(blow_out_result, DefinedErrorData):
+            return DefinedErrorData(
+                public=blow_out_result.public,
+                state_update=StateUpdate.reduce(
+                    move_result.state_update, blow_out_result.state_update
+                ),
+                state_update_if_false_positive=StateUpdate.reduce(
+                    move_result.state_update,
+                    blow_out_result.state_update_if_false_positive,
+                ),
+            )
+        else:
+            return SuccessData(
+                public=BlowOutResult(position=move_result.public.position),
+                state_update=StateUpdate.reduce(
+                    move_result.state_update, blow_out_result.state_update
+                ).set_pipette_ready_to_aspirate(
+                    pipette_id=params.pipetteId, ready_to_aspirate=False
+                ),
+            )
+
+
+class BlowOut(
+    BaseCommand[
+        BlowOutParams,
+        BlowOutResult,
+        OverpressureError | StallOrCollisionError,
+    ]
+):
+    """Blow-out command model."""
+
+    commandType: BlowOutCommandType = "blowout"
+    params: BlowOutParams
+    result: Optional[BlowOutResult] = None
+
+    _ImplementationCls: Type[BlowOutImplementation] = BlowOutImplementation
+
+
+class BlowOutCreate(BaseCommandCreate[BlowOutParams]):
+    """Create blow-out command request model."""
+
+    commandType: BlowOutCommandType = "blowout"
+    params: BlowOutParams
+
+    _CommandCls: Type[BlowOut] = BlowOut

opentrons/protocol_engine/commands/blow_out_in_place.py

@@ -0,0 +1,119 @@
+"""Blow-out in place command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+from pydantic import BaseModel
+
+from .pipetting_common import (
+    OverpressureError,
+    PipetteIdMixin,
+    FlowRateMixin,
+    blow_out_in_place,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    DefinedErrorData,
+    SuccessData,
+)
+from ..errors.error_occurrence import ErrorOccurrence
+
+from opentrons.hardware_control import HardwareControlAPI
+
+
+if TYPE_CHECKING:
+    from ..execution import PipettingHandler, GantryMover
+    from ..state.state import StateView
+    from ..resources import ModelUtils
+
+
+BlowOutInPlaceCommandType = Literal["blowOutInPlace"]
+
+
+class BlowOutInPlaceParams(PipetteIdMixin, FlowRateMixin):
+    """Payload required to blow-out in place."""
+
+    pass
+
+
+class BlowOutInPlaceResult(BaseModel):
+    """Result data from the execution of a BlowOutInPlace command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[BlowOutInPlaceResult],
+    DefinedErrorData[OverpressureError],
+]
+
+
+class BlowOutInPlaceImplementation(
+    AbstractCommandImpl[BlowOutInPlaceParams, _ExecuteReturn]
+):
+    """BlowOutInPlace command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        state_view: StateView,
+        hardware_api: HardwareControlAPI,
+        model_utils: ModelUtils,
+        gantry_mover: GantryMover,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._model_utils = model_utils
+        self._gantry_mover = gantry_mover
+
+    async def execute(self, params: BlowOutInPlaceParams) -> _ExecuteReturn:
+        """Blow-out without moving the pipette."""
+        current_position = await self._gantry_mover.get_position(params.pipetteId)
+        result = await blow_out_in_place(
+            pipette_id=params.pipetteId,
+            flow_rate=params.flowRate,
+            location_if_error={
+                "retryLocation": (
+                    current_position.x,
+                    current_position.y,
+                    current_position.z,
+                )
+            },
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+        )
+        if isinstance(result, DefinedErrorData):
+            return result
+        return SuccessData(
+            public=BlowOutInPlaceResult(),
+            state_update=result.state_update.set_pipette_ready_to_aspirate(
+                pipette_id=params.pipetteId, ready_to_aspirate=False
+            ),
+        )
+
+
+class BlowOutInPlace(
+    BaseCommand[BlowOutInPlaceParams, BlowOutInPlaceResult, ErrorOccurrence]
+):
+    """BlowOutInPlace command model."""
+
+    commandType: BlowOutInPlaceCommandType = "blowOutInPlace"
+    params: BlowOutInPlaceParams
+    result: Optional[BlowOutInPlaceResult] = None
+
+    _ImplementationCls: Type[
+        BlowOutInPlaceImplementation
+    ] = BlowOutInPlaceImplementation
+
+
+class BlowOutInPlaceCreate(BaseCommandCreate[BlowOutInPlaceParams]):
+    """BlowOutInPlace command request model."""
+
+    commandType: BlowOutInPlaceCommandType = "blowOutInPlace"
+    params: BlowOutInPlaceParams
+
+    _CommandCls: Type[BlowOutInPlace] = BlowOutInPlace