fix(api): raise better error during LC transfer when trying to dispense more than tip liquid volume (#18844)

# Overview

Without the change in this PR, if an attempt is made to dispense more
than the volume present in tip, an obscure error saying `'Value must be
a positive float.'`. This error stems from the `dispense_and_wait`
method when trying to find the correction volume for a negative volume
found by calculating tip volume after dispense as `current_tip_vol -
dispense_vol`.

This PR adds a quick check for tip volume and raises an informative
error to the user.

## Risk assessment

None. Only adds an error message.

Author: sanni-t

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

@@ -30,6 +30,9 @@
     NoLiquidClassPropertyError,
 )
 from opentrons.protocols.advanced_control.transfers import common as tx_commons
+from opentrons.protocols.advanced_control.transfers.transfer_liquid_utils import (
+    check_current_volume_before_dispensing,
+)
 from opentrons.protocol_engine import commands as cmd
 from opentrons.protocol_engine import (
     DeckPoint,
@@ -2143,9 +2146,12 @@ def remove_air_gap_during_transfer_with_liquid_class(
         """Remove an air gap that was previously added during a transfer."""
         if last_air_gap == 0:
             return
-
+        current_vol = self.get_current_volume()
+        check_current_volume_before_dispensing(
+            current_volume=current_vol, dispense_volume=last_air_gap
+        )
         correction_volume = dispense_props.correction_by_volume.get_for_volume(
-            self.get_current_volume() - last_air_gap
+            current_vol - last_air_gap
         )
         # The minimum flow rate should be air_gap_volume per second
         flow_rate = max(

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

@@ -25,6 +25,7 @@
 from opentrons.types import Location, Point, Mount
 from opentrons.protocols.advanced_control.transfers.transfer_liquid_utils import (
     LocationCheckDescriptors,
+    check_current_volume_before_dispensing,
 )
 from opentrons.protocols.advanced_control.transfers import (
     transfer_liquid_utils as tx_utils,
@@ -253,8 +254,12 @@ def dispense_and_wait(
         push_out_override: Optional[float],
     ) -> None:
         """Dispense according to dispense properties and wait if enabled."""
+        current_vol = self._instrument.get_current_volume()
+        check_current_volume_before_dispensing(
+            current_volume=current_vol, dispense_volume=volume
+        )
         correction_volume = dispense_properties.correction_by_volume.get_for_volume(
-            self._instrument.get_current_volume() - volume
+            current_vol - volume
         )
         self._instrument.dispense(
             location=self._target_location,

api/src/opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py

@@ -212,3 +212,20 @@ def _group_wells_for_nozzle_configuration(  # noqa: C901
         grouped_wells.reverse()
 
     return grouped_wells
+
+
+def check_current_volume_before_dispensing(
+    current_volume: float,
+    dispense_volume: float,
+) -> None:
+    """Check if the current volume is valid for dispensing the dispense volume."""
+    if current_volume < dispense_volume:
+        # Although this should never happen, we can get into an unexpected state
+        # following error recovery and not have the expected amount of liquid in the tip.
+        # If this happens, we want to raise a useful error so the user can understand
+        # the cause of the problem. If we don't make this check for current volume,
+        # an unhelpful error might get raised when a '..byVolume' property encounters
+        # a negative volume (current_volume - dispense_volume).
+        raise RuntimeError(
+            f"Cannot dispense {dispense_volume}uL when the tip has only {current_volume}uL."
+        )

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

@@ -2425,7 +2425,7 @@ def test_remove_air_gap_during_transfer_with_liquid_class(
     """It should remove air gap by calling dispense and delay with liquid class props."""
     test_transfer_props = decoy.mock(cls=TransferProperties)
     air_gap_correction_by_vol = 0.321
-    current_volume = 0.654
+    current_volume = 3.21
 
     test_transfer_props.dispense.delay.duration = 321
     test_transfer_props.dispense.delay.enabled = True
@@ -2463,6 +2463,32 @@ def test_remove_air_gap_during_transfer_with_liquid_class(
     )
 
 
+@pytest.mark.parametrize("version", versions_at_or_above(APIVersion(2, 24)))
+def test_remove_air_gap_during_transfer_raises_if_tip_volume_less_than_dispense_vol(
+    decoy: Decoy,
+    mock_engine_client: EngineClient,
+    mock_protocol_core: ProtocolCore,
+    subject: InstrumentCore,
+    version: APIVersion,
+) -> None:
+    """It should raise an error if tip volume is less than dispense volume."""
+    test_transfer_props = decoy.mock(cls=TransferProperties)
+    decoy.when(mock_protocol_core.api_version).then_return(version)
+    decoy.when(
+        mock_engine_client.state.pipettes.get_aspirated_volume(
+            pipette_id=subject.pipette_id
+        )
+    ).then_return(50)
+    with pytest.raises(
+        RuntimeError, match="Cannot dispense 50.1uL when the tip has only 50uL."
+    ):
+        subject.remove_air_gap_during_transfer_with_liquid_class(
+            last_air_gap=50.1,
+            dispense_props=test_transfer_props.dispense,
+            location=Location(Point(1, 2, 3), labware=None),
+        )
+
+
 @pytest.mark.parametrize("version", versions_at_or_above(APIVersion(2, 23)))
 def test_remove_air_gap_during_transfer_with_liquid_class_handles_delays(
     decoy: Decoy,

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

@@ -476,6 +476,32 @@ def test_dispense_and_wait_skips_delay(
     )
 
 
+def test_dispense_and_wait_raises_if_tip_volume_less_than_dispense_vol(
+    decoy: Decoy,
+    mock_instrument_core: InstrumentCore,
+    sample_transfer_props: TransferProperties,
+) -> None:
+    """Should raise a useful error if trying to dispense more than liquid present in tip."""
+    decoy.when(mock_instrument_core.get_current_volume()).then_return(50)
+
+    subject = TransferComponentsExecutor(
+        instrument_core=mock_instrument_core,
+        transfer_properties=sample_transfer_props,
+        target_location=Location(Point(1, 2, 3), labware=None),
+        target_well=decoy.mock(cls=WellCore),
+        tip_state=TipState(),
+        transfer_type=TransferType.ONE_TO_ONE,
+    )
+    with pytest.raises(
+        RuntimeError, match="Cannot dispense 51uL when the tip has only 50uL."
+    ):
+        subject.dispense_and_wait(
+            dispense_properties=sample_transfer_props.dispense,
+            volume=51,
+            push_out_override=123,
+        )
+
+
 def test_dispense_into_trash_and_wait(
     decoy: Decoy,
     mock_instrument_core: InstrumentCore,