fix(api): optimize liquid class transfers by only changing volume mode when necessary (#20009)

Fixes an inefficiency in the liquid class transfer code where configure_for_volume was being called unconditionally

Author: jbleon95

api/src/opentrons/hardware_control/dev_types.py

@@ -22,6 +22,7 @@
     SupportedTipsDefinition,
     PipetteBoundingBoxOffsetDefinition,
     AvailableSensorDefinition,
+    PipetteLiquidPropertiesDefinition,
 )
 from opentrons_shared_data.gripper import (
     GripperModel,
@@ -106,6 +107,9 @@ class PipetteDict(InstrumentDict):
     shaft_ul_per_mm: float
     available_sensors: AvailableSensorDefinition
     volume_mode: LiquidClasses  # LiquidClasses refer to volume mode in this context
+    available_volume_modes: Dict[
+        LiquidClasses, PipetteLiquidPropertiesDefinition
+    ]  # Ditto
 
 
 class PipetteStateDict(TypedDict):

api/src/opentrons/hardware_control/instruments/ot2/pipette_handler.py

@@ -268,6 +268,7 @@ def get_attached_instrument(self, mount: MountType) -> PipetteDict:
             }
             result["shaft_ul_per_mm"] = instr.config.shaft_ul_per_mm
             result["volume_mode"] = instr.liquid_class_name
+            result["available_volume_modes"] = instr.config.liquid_properties
         return cast(PipetteDict, result)
 
     @property

api/src/opentrons/hardware_control/instruments/ot3/pipette_handler.py

@@ -295,6 +295,7 @@ def get_attached_instrument(self, mount: OT3Mount) -> PipetteDict:
             result["shaft_ul_per_mm"] = instr.config.shaft_ul_per_mm
             result["available_sensors"] = instr.config.available_sensors
             result["volume_mode"] = instr.liquid_class_name
+            result["available_volume_modes"] = instr.config.liquid_properties
         return cast(PipetteDict, result)
 
     @property

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

@@ -2153,7 +2153,12 @@ def aspirate_liquid_class(
                 air_gap=0,
             )
         )
-        if volume_for_pipette_mode_configuration is not None:
+        if volume_for_pipette_mode_configuration is not None and (
+            self._protocol_core.api_version < APIVersion(2, 28)
+            or self._engine_client.state.pipettes.get_will_volume_mode_change(
+                self._pipette_id, volume_for_pipette_mode_configuration
+            )
+        ):
             prep_location = Location(
                 point=source_well.get_top(LIQUID_PROBE_START_OFFSET_FROM_WELL_TOP.z),
                 labware=source_loc.labware,
@@ -2171,10 +2176,14 @@ def aspirate_liquid_class(
                 location=prep_location,
             )
             last_liquid_and_airgap_in_tip.air_gap = 0
-            # TODO: do volume configuration + prepare for aspirate only if the mode needs to be changed
             self.configure_for_volume(volume_for_pipette_mode_configuration)
             self.prepare_to_aspirate()
 
+        elif not self._engine_client.state.pipettes.get_ready_to_aspirate(
+            self._pipette_id
+        ):
+            self.prepare_to_aspirate()
+
         aspirate_point = (
             tx_comps_executor.absolute_point_from_position_reference_and_offset(
                 well=source_well,

api/src/opentrons/protocol_engine/resources/pipette_data_provider.py

@@ -71,6 +71,7 @@ class LoadedStaticPipetteData:
     shaft_ul_per_mm: float
     available_sensors: pipette_definition.AvailableSensorDefinition
     volume_mode: pip_types.LiquidClasses  # pip_types Liquid Classes refers to volume modes
+    available_volume_modes_min_vol: Dict[pip_types.LiquidClasses, float]  # Ditto
 
 
 class VirtualPipetteDataProvider:
@@ -300,6 +301,10 @@ def _get_virtual_pipette_static_config_by_model(  # noqa: C901
             available_sensors=config.available_sensors
             or pipette_definition.AvailableSensorDefinition(sensors=[]),
             volume_mode=liquid_class,
+            available_volume_modes_min_vol={
+                volume_mode: props.min_volume
+                for volume_mode, props in config.liquid_properties.items()
+            },
         )
 
     def get_virtual_pipette_static_config(
@@ -356,6 +361,10 @@ def get_pipette_static_config(
         shaft_ul_per_mm=pipette_dict["shaft_ul_per_mm"],
         available_sensors=available_sensors,
         volume_mode=pipette_dict["volume_mode"],
+        available_volume_modes_min_vol={
+            volume_mode: props.min_volume
+            for volume_mode, props in pipette_dict["available_volume_modes"].items()
+        },
     )
 
 

api/src/opentrons/protocol_engine/state/pipettes.py

@@ -111,6 +111,7 @@ class StaticPipetteConfig:
     shaft_ul_per_mm: float
     available_sensors: pipette_definition.AvailableSensorDefinition
     volume_mode: VolumeModes
+    available_volume_modes_min_vol: Dict[VolumeModes, float]
 
 
 @dataclasses.dataclass
@@ -318,6 +319,7 @@ def _update_pipette_config(self, state_update: update_types.StateUpdate) -> None
                 shaft_ul_per_mm=config.shaft_ul_per_mm,
                 available_sensors=config.available_sensors,
                 volume_mode=config.volume_mode,
+                available_volume_modes_min_vol=config.available_volume_modes_min_vol,
             )
             self._state.flow_rates_by_id[
                 state_update.pipette_config.pipette_id
@@ -876,6 +878,30 @@ def get_is_low_volume_mode(self, pipette_id: str) -> bool:
         """Determine if the pipette is currently in low volume mode."""
         return self.get_config(pipette_id).volume_mode == VolumeModes.lowVolumeDefault
 
+    def get_volume_mode_from_volume(
+        self, pipette_id: str, volume: float
+    ) -> VolumeModes:
+        """Get the volume mode for the given pipette and volume quantity."""
+        available_volume_modes_min_vol = self.get_config(
+            pipette_id
+        ).available_volume_modes_min_vol
+        has_low_volume_mode = (
+            VolumeModes.lowVolumeDefault in available_volume_modes_min_vol
+        )
+
+        if not has_low_volume_mode:
+            return VolumeModes.default
+        if volume >= available_volume_modes_min_vol[VolumeModes.default]:
+            return VolumeModes.default
+        return VolumeModes.lowVolumeDefault
+
+    def get_will_volume_mode_change(self, pipette_id: str, volume: float) -> bool:
+        """Determine if the pipette will change volume mode based on current volume mode and new volume."""
+        return (
+            self.get_volume_mode_from_volume(pipette_id, volume)
+            != self.get_config(pipette_id).volume_mode
+        )
+
     def lookup_volume_to_mm_conversion(
         self, pipette_id: str, volume: float, action: str
     ) -> float:

api/src/opentrons/protocols/api_support/definitions.py

@@ -1,6 +1,6 @@
 from .types import APIVersion
 
-MAX_SUPPORTED_VERSION = APIVersion(2, 27)
+MAX_SUPPORTED_VERSION = APIVersion(2, 28)
 """The maximum supported protocol API version in this release."""
 
 MIN_SUPPORTED_VERSION = APIVersion(2, 0)