fix(api): post-dispense air gaps in LC based transfers (#19025)

Closes AUTH-2138

# Overview

We were previously using `airGapByVolume` of post-aspirate retract
property for finding air gaps to use during post-dispense retracts. This
PR fixes that so we use the `airGapByVolume` property of a
post-single-dispense or a post-multi-dispense in such cases.

Additionally, when adding air gaps in-between multi-dispenses (when
conditioning volume is zero), we should be using the total tip volume as
the lookup volume for `airGapByVolume` but we were just using `0`uL.

## Risk assessment

Medium. This fixes the air gaps in a lot of cases, but the impact of
this change is not too high practically speaking.

Author: sanni-t

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

@@ -543,6 +543,11 @@ def retract_after_dispensing(
             blowout_props.enabled
             and blowout_props.location == BlowoutLocation.DESTINATION
         ) or not blowout_props.enabled
+
+        if is_final_air_gap and not add_final_air_gap:
+            air_gap_volume = 0.0
+        else:
+            air_gap_volume = retract_props.air_gap_by_volume.get_for_volume(0)
         # Regardless of the blowout location, do touch tip and air gap
         # when leaving the dispense well. If this will be the final air gap, i.e,
         # we won't be moving to a Trash or a Source for Blowout after this air gap,
@@ -551,7 +556,7 @@ def retract_after_dispensing(
             touch_tip_properties=retract_props.touch_tip,
             location=retract_location,
             well=self._target_well,
-            add_air_gap=False if is_final_air_gap and not add_final_air_gap else True,
+            air_gap_volume=air_gap_volume,
         )
 
         if (
@@ -599,15 +604,21 @@ def retract_after_dispensing(
             last_air_gap = self._tip_state.last_liquid_and_air_gap_in_tip.air_gap
             self._tip_state.delete_air_gap(last_air_gap)
             self._tip_state.ready_to_aspirate = False
+
+            air_gap_volume = (
+                retract_props.air_gap_by_volume.get_for_volume(0)
+                if add_final_air_gap
+                else 0.0
+            )
             # Do touch tip and air gap again after blowing out into source well or trash
             self._do_touch_tip_and_air_gap_after_dispense(
                 touch_tip_properties=retract_props.touch_tip,
                 location=touch_tip_and_air_gap_location,
                 well=touch_tip_and_air_gap_well,
-                add_air_gap=add_final_air_gap,
+                air_gap_volume=air_gap_volume,
             )
 
-    def retract_during_multi_dispensing(
+    def retract_during_multi_dispensing(  # noqa: C901
         self,
         trash_location: Union[Location, TrashBin, WasteChute],
         source_location: Optional[Location],
@@ -720,6 +731,14 @@ def retract_during_multi_dispensing(
             else:
                 add_air_gap = True
 
+        air_gap_volume = (
+            retract_props.air_gap_by_volume.get_for_volume(
+                self.tip_state.last_liquid_and_air_gap_in_tip.liquid
+            )
+            if add_air_gap
+            else 0.0
+        )
+
         # Regardless of the blowout location, do touch tip
         # when leaving the dispense well.
         # Add an air gap depending on conditioning volume + whether this is
@@ -729,7 +748,7 @@ def retract_during_multi_dispensing(
             touch_tip_properties=retract_props.touch_tip,
             location=retract_location,
             well=self._target_well,
-            add_air_gap=add_air_gap,
+            air_gap_volume=air_gap_volume,
         )
 
         if (
@@ -776,25 +795,30 @@ def retract_during_multi_dispensing(
             self._tip_state.delete_last_air_gap_and_liquid()
             self._tip_state.ready_to_aspirate = False
 
+            if (
+                # Same check as before for when it's the final air gap of current retract
+                conditioning_volume > 0
+                and is_last_retract
+                and add_final_air_gap
+            ):
+                # The volume in tip at this point should be 0uL
+                air_gap_volume = retract_props.air_gap_by_volume.get_for_volume(0)
+            else:
+                air_gap_volume = 0
             # Do touch tip and air gap again after blowing out into source well or trash
             self._do_touch_tip_and_air_gap_after_dispense(
                 touch_tip_properties=retract_props.touch_tip,
                 location=touch_tip_and_air_gap_location,
                 well=touch_tip_and_air_gap_well,
-                add_air_gap=(
-                    # Same check as before for when it's the final air gap of current retract
-                    conditioning_volume > 0
-                    and is_last_retract
-                    and add_final_air_gap
-                ),
+                air_gap_volume=air_gap_volume,
             )
 
     def _do_touch_tip_and_air_gap_after_dispense(  # noqa: C901
         self,
         touch_tip_properties: TouchTipProperties,
         location: Union[Location, TrashBin, WasteChute],
         well: Optional[WellCore],
-        add_air_gap: bool,
+        air_gap_volume: float,
     ) -> None:
         """Perform touch tip and air gap as part of post-dispense retract.
 
@@ -840,7 +864,7 @@ def _do_touch_tip_and_air_gap_after_dispense(  # noqa: C901
                     # Full speed because the tip will already be out of the liquid
                     speed=None,
                 )
-        if add_air_gap or not self._tip_state.ready_to_aspirate:
+        if air_gap_volume > 0 or not self._tip_state.ready_to_aspirate:
             # If we need to move the plunger up either to prepare for aspirate or to add air gap,
             # move to a safe location above the well if the retract location is not already
             # at or above this safe location
@@ -886,12 +910,8 @@ def _do_touch_tip_and_air_gap_after_dispense(  # noqa: C901
             if not self._tip_state.ready_to_aspirate:
                 self._instrument.prepare_to_aspirate()
                 self._tip_state.ready_to_aspirate = True
-            if add_air_gap:
-                self._add_air_gap(
-                    air_gap_volume=self._transfer_properties.aspirate.retract.air_gap_by_volume.get_for_volume(
-                        0
-                    )
-                )
+            if air_gap_volume > 0:
+                self._add_air_gap(air_gap_volume=air_gap_volume)
 
     def _add_air_gap(
         self,

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

@@ -1134,7 +1134,7 @@ def test_retract_after_dispense_with_blowout_in_source(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1258,6 +1258,10 @@ def test_retract_after_dispense_with_blowout_in_destination(
     air_gap_correction_by_vol = 0.321
 
     sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+        0,
+        1234,  # Explicitly check that this value is not used during post-dispense air gap
+    )
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1366,7 +1370,7 @@ def test_retract_after_dispense_with_blowout_in_trash_well(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1493,7 +1497,7 @@ def test_retract_after_dispense_with_blowout_in_disposal_location(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1599,7 +1603,7 @@ def test_retract_after_dispense_in_trash_with_blowout_in_source(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1697,7 +1701,7 @@ def test_retract_after_dispense_in_trash_with_blowout_in_destination(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1780,7 +1784,7 @@ def test_retract_after_dispense_in_trash_with_blowout_in_disposal_location(
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -1899,7 +1903,7 @@ def test_retract_after_dispense_with_blowout_in_src_moves_to_safe_loc_for_air_ga
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
+    sample_transfer_props.dispense.retract.air_gap_by_volume.set_for_volume(
         0, air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
@@ -2039,26 +2043,33 @@ def test_multi_dispense_retract_after_dispense_without_conditioning_volume_or_bl
     dest_well = decoy.mock(cls=WellCore)
     well_top_point = Point(1, 2, 3)
     sample_transfer_props.multi_dispense.retract.touch_tip.enabled = True  # type: ignore[union-attr]
-    air_gap_volume = 0.123
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
-        0, air_gap_volume
+    sample_transfer_props.multi_dispense.retract.air_gap_by_volume.set_for_volume(  # type: ignore[union-attr]
+        100, 51
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
-        air_gap_volume, air_gap_flow_rate_by_vol
+        51, air_gap_flow_rate_by_vol
     )
     sample_transfer_props.aspirate.correction_by_volume.set_for_volume(
-        air_gap_volume, air_gap_correction_by_vol
+        51, air_gap_correction_by_vol
     )
-
     subject = TransferComponentsExecutor(
         instrument_core=mock_instrument_core,
         transfer_properties=sample_transfer_props,
         target_location=Location(Point(1, 1, 1), labware=None),
         target_well=dest_well,
-        tip_state=TipState(),
+        tip_state=TipState(
+            ready_to_aspirate=True,
+            last_liquid_and_air_gap_in_tip=LiquidAndAirGapPair(
+                # Since we'll be testing retract_during_multi_dispensing right after
+                # initializing the executor, this is the tip state that retract_during_multi_dispensing
+                # will start with.
+                liquid=100,
+                air_gap=0,
+            ),
+        ),
         transfer_type=TransferType.ONE_TO_MANY,
     )
     decoy.when(mock_instrument_core.get_current_volume()).then_return(0)
@@ -2112,7 +2123,7 @@ def test_multi_dispense_retract_after_dispense_without_conditioning_volume_or_bl
             and [
                 mock_instrument_core.air_gap_in_place(
                     # type: ignore[func-returns-value]
-                    volume=air_gap_volume,
+                    volume=51,
                     flow_rate=air_gap_flow_rate_by_vol,
                     correction_volume=air_gap_correction_by_vol,
                 ),
@@ -2159,8 +2170,8 @@ def test_multi_dispense_retract_after_dispense_with_blowout_without_conditioning
     air_gap_flow_rate_by_vol = 123
     air_gap_correction_by_vol = 0.321
 
-    sample_transfer_props.aspirate.retract.air_gap_by_volume.set_for_volume(
-        0, air_gap_volume
+    sample_transfer_props.multi_dispense.retract.air_gap_by_volume.set_for_all_volumes(  # type: ignore[union-attr]
+        air_gap_volume
     )
     sample_transfer_props.aspirate.flow_rate_by_volume.set_for_volume(
         air_gap_volume, air_gap_flow_rate_by_vol