opentrons 8.3.2__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

opentrons/protocol_engine/execution/pipetting.py

@@ -1,5 +1,5 @@
 """Pipetting command handling."""
-from typing import Optional, Iterator
+from typing import Optional, Iterator, Tuple
 from typing_extensions import Protocol as TypingProtocol
 from contextlib import contextmanager
 
@@ -13,8 +13,13 @@ from ..errors.exceptions import (
     InvalidAspirateVolumeError,
     InvalidPushOutVolumeError,
     InvalidDispenseVolumeError,
+    InvalidLiquidHeightFound,
 )
 from opentrons.protocol_engine.types import WellLocation
+from opentrons.protocol_engine.types.liquid_level_detection import (
+    SimulatedProbeResult,
+    LiquidTrackingType,
+)
 
 # 1e-9 µL (1 femtoliter!) is a good value because:
 # * It's large relative to rounding errors that occur in practice in protocols. For
@@ -30,6 +35,9 @@ _VOLUME_ROUNDING_ERROR_TOLERANCE = 1e-9
 class PipettingHandler(TypingProtocol):
     """Liquid handling commands."""
 
+    def get_state_view(self) -> StateView:
+        """Get the stateview associated with this handler."""
+
     def get_is_ready_to_aspirate(self, pipette_id: str) -> bool:
         """Get whether a pipette is ready to aspirate."""
 
@@ -42,15 +50,41 @@ class PipettingHandler(TypingProtocol):
         volume: float,
         flow_rate: float,
         command_note_adder: CommandNoteAdder,
+        correction_volume: float = 0.0,
     ) -> float:
         """Set flow-rate and aspirate."""
 
+    async def aspirate_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
+        flow_rate: float,
+        command_note_adder: CommandNoteAdder,
+    ) -> float:
+        """Set flow-rate and aspirate while tracking."""
+
+    async def dispense_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
+        flow_rate: float,
+        push_out: Optional[float],
+        is_full_dispense: bool = False,
+    ) -> float:
+        """Set flow-rate and dispense while tracking."""
+
     async def dispense_in_place(
         self,
         pipette_id: str,
         volume: float,
         flow_rate: float,
         push_out: Optional[float],
+        is_full_dispense: bool,
+        correction_volume: float = 0.0,
     ) -> float:
         """Set flow-rate and dispense."""
 
@@ -67,18 +101,25 @@ class PipettingHandler(TypingProtocol):
         labware_id: str,
         well_name: str,
         well_location: WellLocation,
-    ) -> float:
+    ) -> LiquidTrackingType:
         """Detect liquid level."""
 
+    async def increase_evo_disp_count(self, pipette_id: str) -> None:
+        """Increase evo tip dispense action count."""
+
 
 class HardwarePipettingHandler(PipettingHandler):
-    """Liquid handling, using the Hardware API.""" ""
+    """Liquid handling, using the Hardware API."""
 
     def __init__(self, state_view: StateView, hardware_api: HardwareControlAPI) -> None:
         """Initialize a PipettingHandler instance."""
         self._state_view = state_view
         self._hardware_api = hardware_api
 
+    def get_state_view(self) -> StateView:
+        """Get the stateview associated with this handler."""
+        return self._state_view
+
     def get_is_ready_to_aspirate(self, pipette_id: str) -> bool:
         """Get whether a pipette is ready to aspirate."""
         hw_pipette = self._state_view.pipettes.get_hardware_pipette(
@@ -88,6 +129,7 @@ class HardwarePipettingHandler(PipettingHandler):
         return (
             self._state_view.pipettes.get_aspirated_volume(pipette_id) is not None
             and hw_pipette.config["ready_to_aspirate"]
+            and self._state_view.pipettes.get_ready_to_aspirate(pipette_id)
         )
 
     async def prepare_for_aspirate(self, pipette_id: str) -> None:
@@ -99,10 +141,48 @@ class HardwarePipettingHandler(PipettingHandler):
         hw_mount = self._state_view.pipettes.get_mount(pipette_id).to_hw_mount()
         await self._hardware_api.prepare_for_aspirate(mount=hw_mount)
 
-    async def aspirate_in_place(
+    def get_hw_aspirate_params(
+        self,
+        pipette_id: str,
+        volume: float,
+        command_note_adder: CommandNoteAdder,
+    ) -> Tuple[HardwarePipette, float]:
+        """Get params for hardware aspirate."""
+        _adjusted_volume = _validate_aspirate_volume(
+            state_view=self._state_view,
+            pipette_id=pipette_id,
+            aspirate_volume=volume,
+            command_note_adder=command_note_adder,
+        )
+        _hw_pipette = self._state_view.pipettes.get_hardware_pipette(
+            pipette_id=pipette_id,
+            attached_pipettes=self._hardware_api.attached_instruments,
+        )
+        return _hw_pipette, _adjusted_volume
+
+    def get_hw_dispense_params(
         self,
         pipette_id: str,
         volume: float,
+    ) -> Tuple[HardwarePipette, float]:
+        """Get params for hardware dispense."""
+        _adjusted_volume = _validate_dispense_volume(
+            state_view=self._state_view,
+            pipette_id=pipette_id,
+            dispense_volume=volume,
+        )
+        _hw_pipette = self._state_view.pipettes.get_hardware_pipette(
+            pipette_id=pipette_id,
+            attached_pipettes=self._hardware_api.attached_instruments,
+        )
+        return _hw_pipette, _adjusted_volume
+
+    async def aspirate_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
         flow_rate: float,
         command_note_adder: CommandNoteAdder,
     ) -> float:
@@ -112,19 +192,88 @@ class HardwarePipettingHandler(PipettingHandler):
             PipetteOverpressureError, propagated as-is from the hardware controller.
         """
         # get mount and config data from state and hardware controller
-        adjusted_volume = _validate_aspirate_volume(
-            state_view=self._state_view,
+        hw_pipette, adjusted_volume = self.get_hw_aspirate_params(
+            pipette_id, volume, command_note_adder
+        )
+        aspirate_z_distance = self._state_view.geometry.get_liquid_handling_z_change(
+            labware_id=labware_id,
+            well_name=well_name,
+            operation_volume=volume * -1,
             pipette_id=pipette_id,
-            aspirate_volume=volume,
-            command_note_adder=command_note_adder,
         )
-        hw_pipette = self._state_view.pipettes.get_hardware_pipette(
+        if isinstance(aspirate_z_distance, SimulatedProbeResult):
+            raise InvalidLiquidHeightFound(
+                "Aspirate distance must be a float in Hardware pipetting handler."
+            )
+        with self._set_flow_rate(pipette=hw_pipette, aspirate_flow_rate=flow_rate):
+            await self._hardware_api.aspirate_while_tracking(
+                mount=hw_pipette.mount,
+                z_distance=aspirate_z_distance,
+                flow_rate=flow_rate,
+                volume=adjusted_volume,
+            )
+        return adjusted_volume
+
+    async def dispense_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
+        flow_rate: float,
+        push_out: Optional[float],
+        is_full_dispense: bool = False,
+    ) -> float:
+        """Set flow-rate and dispense.
+
+        Raises:
+            PipetteOverpressureError, propagated as-is from the hardware controller.
+        """
+        # get mount and config data from state and hardware controller
+        hw_pipette, adjusted_volume = self.get_hw_dispense_params(pipette_id, volume)
+        dispense_z_distance = self._state_view.geometry.get_liquid_handling_z_change(
+            labware_id=labware_id,
+            well_name=well_name,
+            operation_volume=volume,
             pipette_id=pipette_id,
-            attached_pipettes=self._hardware_api.attached_instruments,
+        )
+        if isinstance(dispense_z_distance, SimulatedProbeResult):
+            raise InvalidLiquidHeightFound(
+                "Dispense distance must be a float in Hardware pipetting handler."
+            )
+        with self._set_flow_rate(pipette=hw_pipette, dispense_flow_rate=flow_rate):
+            await self._hardware_api.dispense_while_tracking(
+                mount=hw_pipette.mount,
+                z_distance=dispense_z_distance,
+                flow_rate=flow_rate,
+                volume=adjusted_volume,
+                push_out=push_out,
+                is_full_dispense=is_full_dispense,
+            )
+        return adjusted_volume
+
+    async def aspirate_in_place(
+        self,
+        pipette_id: str,
+        volume: float,
+        flow_rate: float,
+        command_note_adder: CommandNoteAdder,
+        correction_volume: float = 0.0,
+    ) -> float:
+        """Set flow-rate and aspirate.
+
+        Raises:
+            PipetteOverpressureError, propagated as-is from the hardware controller.
+        """
+        # get mount and config data from state and hardware controller
+        hw_pipette, adjusted_volume = self.get_hw_aspirate_params(
+            pipette_id, volume, command_note_adder
         )
         with self._set_flow_rate(pipette=hw_pipette, aspirate_flow_rate=flow_rate):
             await self._hardware_api.aspirate(
-                mount=hw_pipette.mount, volume=adjusted_volume
+                mount=hw_pipette.mount,
+                volume=adjusted_volume,
+                correction_volume=correction_volume,
             )
 
         return adjusted_volume
@@ -135,15 +284,11 @@ class HardwarePipettingHandler(PipettingHandler):
         volume: float,
         flow_rate: float,
         push_out: Optional[float],
+        is_full_dispense: bool,
+        correction_volume: float = 0.0,
     ) -> float:
         """Dispense liquid without moving the pipette."""
-        adjusted_volume = _validate_dispense_volume(
-            state_view=self._state_view, pipette_id=pipette_id, dispense_volume=volume
-        )
-        hw_pipette = self._state_view.pipettes.get_hardware_pipette(
-            pipette_id=pipette_id,
-            attached_pipettes=self._hardware_api.attached_instruments,
-        )
+        hw_pipette, adjusted_volume = self.get_hw_dispense_params(pipette_id, volume)
         # TODO (tz, 8-23-23): add a check for push_out not larger that the max volume allowed when working on this https://opentrons.atlassian.net/browse/RSS-329
         if push_out and push_out < 0:
             raise InvalidPushOutVolumeError(
@@ -151,7 +296,11 @@ class HardwarePipettingHandler(PipettingHandler):
             )
         with self._set_flow_rate(pipette=hw_pipette, dispense_flow_rate=flow_rate):
             await self._hardware_api.dispense(
-                mount=hw_pipette.mount, volume=adjusted_volume, push_out=push_out
+                mount=hw_pipette.mount,
+                volume=adjusted_volume,
+                push_out=push_out,
+                correction_volume=correction_volume,
+                is_full_dispense=is_full_dispense,
             )
 
         return adjusted_volume
@@ -176,8 +325,8 @@ class HardwarePipettingHandler(PipettingHandler):
         labware_id: str,
         well_name: str,
         well_location: WellLocation,
-    ) -> float:
-        """Detect liquid level."""
+    ) -> LiquidTrackingType:
+        """Return liquid level relative to the bottom of the well."""
         hw_pipette = self._state_view.pipettes.get_hardware_pipette(
             pipette_id=pipette_id,
             attached_pipettes=self._hardware_api.attached_instruments,
@@ -223,6 +372,14 @@ class HardwarePipettingHandler(PipettingHandler):
                 blow_out=original_blow_out_rate,
             )
 
+    async def increase_evo_disp_count(self, pipette_id: str) -> None:
+        """Increase evo tip dispense action count."""
+        hw_pipette = self._state_view.pipettes.get_hardware_pipette(
+            pipette_id=pipette_id,
+            attached_pipettes=self._hardware_api.attached_instruments,
+        )
+        await self._hardware_api.increase_evo_disp_count(mount=hw_pipette.mount)
+
 
 class VirtualPipettingHandler(PipettingHandler):
     """Liquid handling, using the virtual pipettes.""" ""
@@ -236,12 +393,19 @@ class VirtualPipettingHandler(PipettingHandler):
         """Initialize a PipettingHandler instance."""
         self._state_view = state_view
 
+    def get_state_view(self) -> StateView:
+        """Get the stateview associated with this handler."""
+        return self._state_view
+
     def get_is_ready_to_aspirate(self, pipette_id: str) -> bool:
         """Get whether a pipette is ready to aspirate."""
-        return self._state_view.pipettes.get_aspirated_volume(pipette_id) is not None
+        return self._state_view.pipettes.get_aspirated_volume(
+            pipette_id
+        ) is not None and self._state_view.pipettes.get_ready_to_aspirate(pipette_id)
 
     async def prepare_for_aspirate(self, pipette_id: str) -> None:
         """Virtually prepare to aspirate (no-op)."""
+        self._validate_tip_attached(pipette_id=pipette_id, command_name="aspirate")
 
     async def aspirate_in_place(
         self,
@@ -249,6 +413,7 @@ class VirtualPipettingHandler(PipettingHandler):
         volume: float,
         flow_rate: float,
         command_note_adder: CommandNoteAdder,
+        correction_volume: float = 0.0,
     ) -> float:
         """Virtually aspirate (no-op)."""
         self._validate_tip_attached(pipette_id=pipette_id, command_name="aspirate")
@@ -265,6 +430,8 @@ class VirtualPipettingHandler(PipettingHandler):
         volume: float,
         flow_rate: float,
         push_out: Optional[float],
+        is_full_dispense: bool,
+        correction_volume: float = 0.0,
     ) -> float:
         """Virtually dispense (no-op)."""
         # TODO (tz, 8-23-23): add a check for push_out not larger that the max volume allowed when working on this https://opentrons.atlassian.net/browse/RSS-329
@@ -290,10 +457,9 @@ class VirtualPipettingHandler(PipettingHandler):
         labware_id: str,
         well_name: str,
         well_location: WellLocation,
-    ) -> float:
+    ) -> LiquidTrackingType:
         """Detect liquid level."""
-        well_def = self._state_view.labware.get_well_definition(labware_id, well_name)
-        return well_def.depth
+        return SimulatedProbeResult()
 
     def _validate_tip_attached(self, pipette_id: str, command_name: str) -> None:
         """Validate if there is a tip attached."""
@@ -303,6 +469,50 @@ class VirtualPipettingHandler(PipettingHandler):
                 f"Cannot perform {command_name} without a tip attached"
             )
 
+    async def aspirate_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
+        flow_rate: float,
+        command_note_adder: CommandNoteAdder,
+    ) -> float:
+        """Virtually aspirate (no-op)."""
+        self._validate_tip_attached(pipette_id=pipette_id, command_name="aspirate")
+
+        return _validate_aspirate_volume(
+            state_view=self._state_view,
+            pipette_id=pipette_id,
+            aspirate_volume=volume,
+            command_note_adder=command_note_adder,
+        )
+
+    async def dispense_while_tracking(
+        self,
+        pipette_id: str,
+        labware_id: str,
+        well_name: str,
+        volume: float,
+        flow_rate: float,
+        push_out: Optional[float],
+        is_full_dispense: bool = False,
+    ) -> float:
+        """Virtually dispense (no-op)."""
+        # TODO (tz, 8-23-23): add a check for push_out not larger that the max volume allowed when working on this https://opentrons.atlassian.net/browse/RSS-329
+        if push_out and push_out < 0:
+            raise InvalidPushOutVolumeError(
+                "push out value cannot have a negative value."
+            )
+        self._validate_tip_attached(pipette_id=pipette_id, command_name="dispense")
+        return _validate_dispense_volume(
+            state_view=self._state_view, pipette_id=pipette_id, dispense_volume=volume
+        )
+
+    async def increase_evo_disp_count(self, pipette_id: str) -> None:
+        """Increase evo tip dispense action count."""
+        pass
+
 
 def create_pipetting_handler(
     state_view: StateView, hardware_api: HardwareControlAPI

opentrons/protocol_engine/execution/tip_handler.py

@@ -1,10 +1,14 @@
 """Tip pickup and drop procedures."""
 
-from typing import Optional, Dict
+from typing import Optional, Dict, Tuple
 from typing_extensions import Protocol as TypingProtocol
 
 from opentrons.hardware_control import HardwareControlAPI
-from opentrons.hardware_control.types import FailedTipStateCheck, InstrumentProbeType
+from opentrons.hardware_control.types import (
+    FailedTipStateCheck,
+    InstrumentProbeType,
+    TipScrapeType,
+)
 from opentrons.protocol_engine.errors.exceptions import PickUpTipTipNotAttachedError
 from opentrons.types import Mount, NozzleConfigurationType
 
@@ -82,6 +86,7 @@ class TipHandler(TypingProtocol):
         home_after: Optional[bool],
         do_not_ignore_tip_presence: bool = True,
         ignore_plunger: bool = False,
+        scrape_type: TipScrapeType = TipScrapeType.NONE,
     ) -> None:
         """Drop the attached tip into the current location.
 
@@ -196,6 +201,18 @@ async def _available_for_nozzle_layout(  # noqa: C901
     }
 
 
+def tip_on_left_side_96(back_left_nozzle: str) -> bool:
+    """Return if there is a tip on the left edge of the 96 channel."""
+    left_most_column = int(back_left_nozzle[1:])
+    return left_most_column == 1
+
+
+def tip_on_right_side_96(front_right_nozzle: str) -> bool:
+    """Return if there is a tip on the left edge of the 96 channel."""
+    right_most_column = int(front_right_nozzle[1:])
+    return right_most_column == 12
+
+
 class HardwareTipHandler(TipHandler):
     """Pick up and drop tips, using the Hardware API."""
 
@@ -232,6 +249,50 @@ class HardwareTipHandler(TipHandler):
             channels, style, primary_nozzle, front_right_nozzle, back_left_nozzle
         )
 
+    def get_tip_presence_config(
+        self, pipette_id: str
+    ) -> Tuple[bool, Optional[InstrumentProbeType]]:
+        """Return the supported settings for tip presence on a given pipette depending on it's current nozzle map."""
+        follow_singular_sensor = None
+
+        unsupported_layout_types_96 = [NozzleConfigurationType.SINGLE]
+        # NOTE: (09-20-2024) Current on multi-channel pipettes, utilizing less than 4 nozzles risks false positives on the tip presence sensor
+        supported_partial_nozzle_minimum = 4
+
+        nozzle_configuration = self._state_view.pipettes.get_nozzle_configuration(
+            pipette_id=pipette_id
+        )
+
+        match self._state_view.pipettes.get_channels(pipette_id):
+            case 1:
+                tip_presence_supported = True
+            case 8:
+                tip_presence_supported = (
+                    nozzle_configuration.tip_count >= supported_partial_nozzle_minimum
+                )
+            case 96:
+                tip_presence_supported = (
+                    nozzle_configuration.configuration
+                    not in unsupported_layout_types_96
+                    and nozzle_configuration.tip_count
+                    >= supported_partial_nozzle_minimum
+                )
+                if (
+                    nozzle_configuration.configuration != NozzleConfigurationType.FULL
+                    and tip_presence_supported
+                ):
+                    use_left = tip_on_left_side_96(nozzle_configuration.back_left)
+                    use_right = tip_on_right_side_96(nozzle_configuration.front_right)
+                    if not (use_left and use_right):
+                        if use_left:
+                            follow_singular_sensor = InstrumentProbeType.PRIMARY
+                        else:
+                            follow_singular_sensor = InstrumentProbeType.SECONDARY
+            case _:
+                raise ValueError("Unknown pipette type.")
+
+        return (tip_presence_supported, follow_singular_sensor)
+
     async def pick_up_tip(
         self,
         pipette_id: str,
@@ -261,9 +322,18 @@ class HardwareTipHandler(TipHandler):
         await self._hardware_api.tip_pickup_moves(
             mount=hw_mount, presses=None, increment=None
         )
-        if do_not_ignore_tip_presence:
+
+        tip_presence_supported, follow_singular_sensor = self.get_tip_presence_config(
+            pipette_id
+        )
+
+        if do_not_ignore_tip_presence and tip_presence_supported:
             try:
-                await self.verify_tip_presence(pipette_id, TipPresenceStatus.PRESENT)
+                await self.verify_tip_presence(
+                    pipette_id,
+                    TipPresenceStatus.PRESENT,
+                    follow_singular_sensor=follow_singular_sensor,
+                )
             except TipNotAttachedError as e:
                 raise PickUpTipTipNotAttachedError(tip_geometry=tip_geometry) from e
 
@@ -279,19 +349,22 @@ class HardwareTipHandler(TipHandler):
         home_after: Optional[bool],
         do_not_ignore_tip_presence: bool = True,
         ignore_plunger: bool = False,
+        scrape_type: TipScrapeType = TipScrapeType.NONE,
     ) -> None:
         """See documentation on abstract base class."""
         hw_mount = self._get_hw_mount(pipette_id)
 
         # Let the hardware controller handle defaulting home_after since its behavior
         # differs between machines
+        kwargs = {}
         if home_after is not None:
-            kwargs = {"home_after": home_after}
-        else:
-            kwargs = {}
+            kwargs["home_after"] = home_after
 
         await self._hardware_api.tip_drop_moves(
-            mount=hw_mount, ignore_plunger=ignore_plunger, **kwargs
+            mount=hw_mount,
+            ignore_plunger=ignore_plunger,
+            scrape_type=scrape_type,
+            **kwargs,
         )
 
         if do_not_ignore_tip_presence:
@@ -342,30 +415,6 @@ class HardwareTipHandler(TipHandler):
         follow_singular_sensor: Optional[InstrumentProbeType] = None,
     ) -> None:
         """See documentation on abstract base class."""
-        nozzle_configuration = self._state_view.pipettes.get_nozzle_configuration(
-            pipette_id=pipette_id
-        )
-
-        # Configuration metrics by which tip presence checking is ignored
-        unsupported_pipette_types = [8, 96]
-        unsupported_layout_types = [
-            NozzleConfigurationType.SINGLE,
-            NozzleConfigurationType.COLUMN,
-        ]
-        # NOTE: (09-20-2024) Current on multi-channel pipettes, utilizing less than 4 nozzles risks false positives on the tip presence sensor
-        supported_partial_nozzle_minimum = 4
-
-        if (
-            nozzle_configuration is not None
-            and self._state_view.pipettes.get_channels(pipette_id)
-            in unsupported_pipette_types
-            and nozzle_configuration.configuration in unsupported_layout_types
-            and len(nozzle_configuration.map_store) < supported_partial_nozzle_minimum
-        ):
-            # Tip presence sensing is not supported for single tip pick up on the 96ch Flex Pipette, nor with single and some partial layous of the 8ch Flex Pipette.
-            # This is due in part to a press distance tolerance which creates a risk case for false positives. In the case of single tip, the mechanical tolerance
-            # for presses with 100% success is below the minimum average achieved press distance for a given multi channel pipette in that configuration.
-            return
         try:
             ot3api = ensure_ot3_hardware(hardware_api=self._hardware_api)
             hw_mount = self._get_hw_mount(pipette_id)
@@ -445,6 +494,7 @@ class VirtualTipHandler(TipHandler):
         home_after: Optional[bool],
         do_not_ignore_tip_presence: bool = True,
         ignore_plunger: bool = False,
+        scrape_type: TipScrapeType = TipScrapeType.NONE,
     ) -> None:
         """Pick up a tip at the current location using a virtual pipette.