address comments on PR-17138

api/src/opentrons/protocol_api/core/engine/instrument.py

@@ -1189,6 +1189,7 @@ def dispense_liquid_class(
         8. Mix using the same flow rate and delays as specified for asp+disp,
            with the volume and the number of repetitions specified. Use the delays in asp & disp.
             - If the dispense position is outside the liquid, then raise error if mix is enabled.
+              Can only be checked if using liquid level detection/ meniscus-based positioning.
             - If the user wants to perform a mix then they should specify a dispense position that’s inside the liquid OR do mix() on the wells after transfer.
             - Do push out at the last dispense.
         9. Retract

api/src/opentrons/protocol_api/core/engine/transfer_components_executor.py

@@ -26,7 +26,7 @@
 
 @dataclass
 class LiquidAndAirGapPair:
-    """Pairing of a liquid and air gap in a tip, in that order."""
+    """Pairing of a liquid and air gap in a tip, with air gap below the liquid in a tip."""
 
     liquid: float = 0
     air_gap: float = 0
@@ -54,31 +54,31 @@ class TipState:
         default_factory=LiquidAndAirGapPair
     )
 
-    def add_liquid(self, volume: float) -> None:
+    def append_liquid(self, volume: float) -> None:
         # Neither aspirate nor a dispense process should be adding liquid
         # when there is an air gap present.
         assert (
             self.last_liquid_and_air_gap_in_tip.air_gap == 0
         ), "Air gap present in the tip."
         self.last_liquid_and_air_gap_in_tip.liquid += volume
 
-    def remove_liquid(self, volume: float) -> None:
+    def delete_liquid(self, volume: float) -> None:
         # Neither aspirate nor a dispense process should be removing liquid
         # when there is an air gap present.
         assert (
             self.last_liquid_and_air_gap_in_tip.air_gap == 0
         ), "Air gap present in the tip."
         self.last_liquid_and_air_gap_in_tip.liquid -= volume
 
-    def add_air_gap(self, volume: float) -> None:
+    def append_air_gap(self, volume: float) -> None:
         # Neither aspirate nor a dispense process should be adding air gaps
         # when there is already an air gap present.
         assert (
             self.last_liquid_and_air_gap_in_tip.air_gap == 0
         ), "Air gap already present in the tip."
         self.last_liquid_and_air_gap_in_tip.air_gap = volume
 
-    def remove_air_gap(self, volume: float) -> None:
+    def delete_air_gap(self, volume: float) -> None:
         assert (
             self.last_liquid_and_air_gap_in_tip.air_gap == volume
         ), "Last air gap volume doe not match the volume being removed"
@@ -168,7 +168,7 @@ def aspirate_and_wait(self, volume: float) -> None:
             in_place=True,
             is_meniscus=None,  # TODO: update this once meniscus is implemented
         )
-        self._tip_state.add_liquid(volume)
+        self._tip_state.append_liquid(volume)
         delay_props = aspirate_props.delay
         if delay_props.enabled:
             # Assertion only for mypy purposes
@@ -194,7 +194,7 @@ def dispense_and_wait(
         if push_out_override:
             # If a push out was performed, we need to reset the plunger before we can aspirate again
             self._tip_state.ready_to_aspirate = False
-        self._tip_state.remove_liquid(volume)
+        self._tip_state.delete_liquid(volume)
         dispense_delay = dispense_props.delay
         if dispense_delay.enabled:
             assert dispense_delay.duration is not None
@@ -224,18 +224,12 @@ def mix(self, mix_properties: MixProperties, last_dispense_push_out: bool) -> No
         )
         for n in range(mix_properties.repetitions, 0, -1):
             self.aspirate_and_wait(volume=mix_properties.volume)
-            if n == 1:
-                # At the last dispense, do push out if specified
-                self.dispense_and_wait(
-                    volume=mix_properties.volume,
-                    push_out_override=push_out_vol
-                    if last_dispense_push_out is True
-                    else 0,
-                )
-            else:
-                self.dispense_and_wait(
-                    volume=mix_properties.volume, push_out_override=0
-                )
+            self.dispense_and_wait(
+                volume=mix_properties.volume,
+                push_out_override=push_out_vol
+                if last_dispense_push_out is True and n == 1
+                else 0,
+            )
 
     def pre_wet(
         self,
@@ -384,6 +378,7 @@ def retract_after_dispensing(
                 in_place=True,
             )
             self._tip_state.ready_to_aspirate = False
+        # Regardless of the blowout location, do touch tip and air gap when leaving the dispense well
         self._do_touch_tip_and_air_gap(
             location=retract_location, well=self._target_well
         )
@@ -420,8 +415,9 @@ def retract_after_dispensing(
                     None  # TODO: Update this to correct well core
                 )
             last_air_gap = self._tip_state.last_liquid_and_air_gap_in_tip.air_gap
-            self._tip_state.remove_air_gap(last_air_gap)
+            self._tip_state.delete_air_gap(last_air_gap)
             self._tip_state.ready_to_aspirate = False
+            # Do touch tip and air gap again after blowing out into source well or trash
             self._do_touch_tip_and_air_gap(
                 location=touch_tip_and_air_gap_location,
                 well=touch_tip_and_air_gap_well,
@@ -492,7 +488,7 @@ def _add_air_gap(self, air_gap_volume: float) -> None:
             # Assertion only for mypy purposes
             assert delay_props.duration is not None
             self._instrument.delay(delay_props.duration)
-        self._tip_state.add_air_gap(air_gap_volume)
+        self._tip_state.append_air_gap(air_gap_volume)
 
     def _remove_air_gap(self, location: Location) -> None:
         """Remove a previously added air gap."""
@@ -516,7 +512,7 @@ def _remove_air_gap(self, location: Location) -> None:
             is_meniscus=None,
             push_out=0,
         )
-        self._tip_state.remove_air_gap(last_air_gap)
+        self._tip_state.delete_air_gap(last_air_gap)
         dispense_delay = dispense_props.delay
         if dispense_delay.enabled:
             assert dispense_delay.duration is not None

api/tests/opentrons/protocol_api/core/engine/test_transfer_components_executor.py

@@ -567,13 +567,7 @@ def test_retract_after_dispense_with_blowout_in_source(
         transfer_properties=sample_transfer_props,
         target_location=Location(Point(1, 1, 1), labware=None),
         target_well=dest_well,
-        tip_state=TipState(
-            ready_to_aspirate=True,
-            last_liquid_and_air_gap_in_tip=LiquidAndAirGapPair(
-                liquid=0,
-                air_gap=0,
-            ),
-        ),
+        tip_state=TipState(),
         transfer_type=TransferType.ONE_TO_ONE,
     )
     decoy.when(dest_well.get_bottom(0)).then_return(well_bottom_point)