opentrons 8.2.0a4__py2.py3-none-any.whl → 8.3.0a1__py2.py3-none-any.whl

opentrons/protocol_api/instrument_context.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 import logging
 from contextlib import ExitStack
 from typing import Any, List, Optional, Sequence, Union, cast, Dict
-from opentrons.protocol_engine.errors.exceptions import TipNotAttachedError
 from opentrons_shared_data.errors.exceptions import (
     CommandPreconditionViolated,
     CommandParameterLimitViolated,
     UnexpectedTipRemovalError,
+    UnsupportedHardwareCommand,
 )
+from opentrons_shared_data.robot.types import RobotTypeEnum
+
 from opentrons.legacy_broker import LegacyBroker
 from opentrons.hardware_control.dev_types import PipetteDict
 from opentrons import types
@@ -15,8 +17,7 @@ from opentrons.legacy_commands import commands as cmds
 
 from opentrons.legacy_commands import publisher
 from opentrons.protocols.advanced_control.mix import mix_from_kwargs
-from opentrons.protocols.advanced_control import transfers
-
+from opentrons.protocols.advanced_control.transfers import transfer as v1_transfer
 from opentrons.protocols.api_support.deck_type import NoTrashDefinedError
 from opentrons.protocols.api_support.types import APIVersion
 from opentrons.protocols.api_support import instrument
@@ -28,7 +29,6 @@ from opentrons.protocols.api_support.util import (
     APIVersionError,
     UnsupportedAPIError,
 )
-from opentrons.hardware_control.nozzle_manager import NozzleConfigurationType
 
 from .core.common import InstrumentCore, ProtocolCore
 from .core.engine import ENGINE_CORE_API_VERSION
@@ -36,10 +36,13 @@ from .core.legacy.legacy_instrument_core import LegacyInstrumentCore
 from .config import Clearances
 from .disposal_locations import TrashBin, WasteChute
 from ._nozzle_layout import NozzleLayout
+from ._liquid import LiquidClass
 from . import labware, validation
-
-
-AdvancedLiquidHandling = transfers.AdvancedLiquidHandling
+from ..config import feature_flags
+from ..protocols.advanced_control.transfers.common import (
+    TransferTipPolicyV2,
+    TransferTipPolicyV2Type,
+)
 
 _DEFAULT_ASPIRATE_CLEARANCE = 1.0
 _DEFAULT_DISPENSE_CLEARANCE = 1.0
@@ -60,6 +63,10 @@ _DISPOSAL_LOCATION_OFFSET_ADDED_IN = APIVersion(2, 18)
 """The version after which offsets for deck configured trash containers and changes to alternating tip drop behavior were introduced."""
 _PARTIAL_NOZZLE_CONFIGURATION_SINGLE_ROW_PARTIAL_COLUMN_ADDED_IN = APIVersion(2, 20)
 """The version after which partial nozzle configurations of single, row, and partial column layouts became available."""
+_AIR_GAP_TRACKING_ADDED_IN = APIVersion(2, 22)
+"""The version after which air gaps should be implemented with a separate call instead of an aspirate for better liquid volume tracking."""
+
+AdvancedLiquidHandling = v1_transfer.AdvancedLiquidHandling
 
 
 class InstrumentContext(publisher.CommandPublisher):
@@ -257,9 +264,10 @@ class InstrumentContext(publisher.CommandPublisher):
             self.api_version >= APIVersion(2, 20)
             and well is not None
             and self.liquid_presence_detection
-            and self._96_tip_config_valid()
+            and self._core.nozzle_configuration_valid_for_lld()
             and self._core.get_current_volume() == 0
         ):
+            self._raise_if_pressure_not_supported_by_pipette()
             self.require_liquid_presence(well=well)
 
         with publisher.publish_context(
@@ -513,6 +521,8 @@ class InstrumentContext(publisher.CommandPublisher):
             ``pipette.mix(1, location=wellplate['A1'])`` is a valid call, but
             ``pipette.mix(1, wellplate['A1'])`` is not.
 
+        .. versionchanged:: 2.21
+            Does not repeatedly check for liquid presence.
         """
         _log.debug(
             "mixing {}uL with {} repetitions in {} at rate={}".format(
@@ -753,7 +763,11 @@ class InstrumentContext(publisher.CommandPublisher):
             ``pipette.air_gap(height=2)``. If you call ``air_gap`` with a single,
             unnamed argument, it will always be interpreted as a volume.
 
-
+        .. TODO: restore this as a note block for 2.22 docs
+           Before API version 2.22, this function was implemented as an aspirate, and
+           dispensing into a well would add the air gap volume to the liquid tracked in
+           the well. At or above API version 2.22, air gap volume is not counted as liquid
+           when dispensing into a well.
         """
         if not self._core.has_tip():
             raise UnexpectedTipRemovalError("air_gap", self.name, self.mount)
@@ -765,7 +779,12 @@ class InstrumentContext(publisher.CommandPublisher):
             raise RuntimeError("No previous Well cached to perform air gap")
         target = loc.labware.as_well().top(height)
         self.move_to(target, publish=False)
-        self.aspirate(volume)
+        if self.api_version >= _AIR_GAP_TRACKING_ADDED_IN:
+            c_vol = self._core.get_available_volume() if volume is None else volume
+            flow_rate = self._core.get_aspirate_flow_rate()
+            self._core.air_gap_in_place(c_vol, flow_rate)
+        else:
+            self.aspirate(volume)
         return self
 
     @publisher.publish(command=cmds.return_tip)
@@ -934,7 +953,7 @@ class InstrumentContext(publisher.CommandPublisher):
         if location is None:
             if (
                 nozzle_map is not None
-                and nozzle_map.configuration != NozzleConfigurationType.FULL
+                and nozzle_map.configuration != types.NozzleConfigurationType.FULL
                 and self.starting_tip is not None
             ):
                 # Disallowing this avoids concerning the system with the direction
@@ -1206,7 +1225,6 @@ class InstrumentContext(publisher.CommandPublisher):
         self._core.home_plunger()
         return self
 
-    # TODO (spp, 2024-03-08): verify if ok to & change source & dest types to AdvancedLiquidHandling
     @publisher.publish(command=cmds.distribute)
     @requires_version(2, 0)
     def distribute(
@@ -1246,7 +1264,6 @@ class InstrumentContext(publisher.CommandPublisher):
 
         return self.transfer(volume, source, dest, **kwargs)
 
-    # TODO (spp, 2024-03-08): verify if ok to & change source & dest types to AdvancedLiquidHandling
     @publisher.publish(command=cmds.consolidate)
     @requires_version(2, 0)
     def consolidate(
@@ -1396,9 +1413,9 @@ class InstrumentContext(publisher.CommandPublisher):
         mix_strategy, mix_opts = mix_from_kwargs(kwargs)
 
         if trash:
-            drop_tip = transfers.DropTipStrategy.TRASH
+            drop_tip = v1_transfer.DropTipStrategy.TRASH
         else:
-            drop_tip = transfers.DropTipStrategy.RETURN
+            drop_tip = v1_transfer.DropTipStrategy.RETURN
 
         new_tip = kwargs.get("new_tip")
         if isinstance(new_tip, str):
@@ -1420,19 +1437,19 @@ class InstrumentContext(publisher.CommandPublisher):
 
         if blow_out and not blowout_location:
             if self.current_volume:
-                blow_out_strategy = transfers.BlowOutStrategy.SOURCE
+                blow_out_strategy = v1_transfer.BlowOutStrategy.SOURCE
             else:
-                blow_out_strategy = transfers.BlowOutStrategy.TRASH
+                blow_out_strategy = v1_transfer.BlowOutStrategy.TRASH
         elif blow_out and blowout_location:
             if blowout_location == "source well":
-                blow_out_strategy = transfers.BlowOutStrategy.SOURCE
+                blow_out_strategy = v1_transfer.BlowOutStrategy.SOURCE
             elif blowout_location == "destination well":
-                blow_out_strategy = transfers.BlowOutStrategy.DEST
+                blow_out_strategy = v1_transfer.BlowOutStrategy.DEST
             elif blowout_location == "trash":
-                blow_out_strategy = transfers.BlowOutStrategy.TRASH
+                blow_out_strategy = v1_transfer.BlowOutStrategy.TRASH
 
         if new_tip != types.TransferTipPolicy.NEVER:
-            tr, next_tip = labware.next_available_tip(
+            _, next_tip = labware.next_available_tip(
                 self.starting_tip,
                 self.tip_racks,
                 active_channels,
@@ -1444,9 +1461,9 @@ class InstrumentContext(publisher.CommandPublisher):
 
         touch_tip = None
         if kwargs.get("touch_tip"):
-            touch_tip = transfers.TouchTipStrategy.ALWAYS
+            touch_tip = v1_transfer.TouchTipStrategy.ALWAYS
 
-        default_args = transfers.Transfer()
+        default_args = v1_transfer.Transfer()
 
         disposal = kwargs.get("disposal_volume")
         if disposal is None:
@@ -1459,7 +1476,7 @@ class InstrumentContext(publisher.CommandPublisher):
                 f"working volume, {max_volume}uL"
             )
 
-        transfer_args = transfers.Transfer(
+        transfer_args = v1_transfer.Transfer(
             new_tip=new_tip or default_args.new_tip,
             air_gap=air_gap,
             carryover=kwargs.get("carryover") or default_args.carryover,
@@ -1472,10 +1489,10 @@ class InstrumentContext(publisher.CommandPublisher):
             blow_out_strategy=blow_out_strategy or default_args.blow_out_strategy,
             touch_tip_strategy=(touch_tip or default_args.touch_tip_strategy),
         )
-        transfer_options = transfers.TransferOptions(
+        transfer_options = v1_transfer.TransferOptions(
             transfer=transfer_args, mix=mix_opts
         )
-        plan = transfers.TransferPlan(
+        plan = v1_transfer.TransferPlan(
             volume,
             source,
             dest,
@@ -1488,10 +1505,113 @@ class InstrumentContext(publisher.CommandPublisher):
         self._execute_transfer(plan)
         return self
 
-    def _execute_transfer(self, plan: transfers.TransferPlan) -> None:
+    def _execute_transfer(self, plan: v1_transfer.TransferPlan) -> None:
         for cmd in plan:
             getattr(self, cmd["method"])(*cmd["args"], **cmd["kwargs"])
 
+    def transfer_liquid(
+        self,
+        liquid_class: LiquidClass,
+        volume: float,
+        source: Union[
+            labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]]
+        ],
+        dest: Union[
+            labware.Well, Sequence[labware.Well], Sequence[Sequence[labware.Well]]
+        ],
+        new_tip: TransferTipPolicyV2Type = "once",
+        tip_drop_location: Optional[
+            Union[types.Location, labware.Well, TrashBin, WasteChute]
+        ] = None,  # Maybe call this 'tip_drop_location' which is similar to PD
+    ) -> InstrumentContext:
+        """Transfer liquid from source to dest using the specified liquid class properties.
+
+        TODO: Add args description.
+        """
+        if not feature_flags.allow_liquid_classes(
+            robot_type=RobotTypeEnum.robot_literal_to_enum(
+                self._protocol_core.robot_type
+            )
+        ):
+            raise NotImplementedError("This method is not implemented.")
+
+        flat_sources_list = validation.ensure_valid_flat_wells_list_for_transfer_v2(
+            source
+        )
+        flat_dests_list = validation.ensure_valid_flat_wells_list_for_transfer_v2(dest)
+        for well in flat_sources_list + flat_dests_list:
+            instrument.validate_takes_liquid(
+                location=well.top(),
+                reject_module=True,
+                reject_adapter=True,
+            )
+        if len(flat_sources_list) != len(flat_dests_list):
+            raise ValueError(
+                "Sources and destinations should be of the same length in order to perform a transfer."
+                " To transfer liquid from one source to many destinations, use 'distribute_liquid',"
+                " to transfer liquid onto one destinations from many sources, use 'consolidate_liquid'."
+            )
+
+        valid_new_tip = validation.ensure_new_tip_policy(new_tip)
+        if valid_new_tip == TransferTipPolicyV2.NEVER:
+            if self._last_tip_picked_up_from is None:
+                raise RuntimeError(
+                    "Pipette has no tip attached to perform transfer."
+                    " Either do a pick_up_tip beforehand or specify a new_tip parameter"
+                    " of 'once' or 'always'."
+                )
+            else:
+                tiprack = self._last_tip_picked_up_from.parent
+        else:
+            tiprack, well = labware.next_available_tip(
+                starting_tip=self.starting_tip,
+                tip_racks=self.tip_racks,
+                channels=self.active_channels,
+                nozzle_map=self._core.get_nozzle_map(),
+            )
+        if self.current_volume != 0:
+            raise RuntimeError(
+                "A transfer on a liquid class cannot start with liquid already in the tip."
+                " Ensure that all previously aspirated liquid is dispensed before starting"
+                " a new transfer."
+            )
+
+        _trash_location: Union[types.Location, labware.Well, TrashBin, WasteChute]
+        if tip_drop_location is None:
+            saved_trash = self.trash_container
+            if isinstance(saved_trash, labware.Labware):
+                _trash_location = saved_trash.wells()[0]
+            else:
+                _trash_location = saved_trash
+        else:
+            _trash_location = tip_drop_location
+
+        checked_trash_location = (
+            validation.ensure_valid_tip_drop_location_for_transfer_v2(
+                tip_drop_location=_trash_location
+            )
+        )
+        liquid_class_id = self._core.load_liquid_class(
+            liquid_class=liquid_class,
+            pipette_load_name=self.name,
+            tiprack_uri=tiprack.uri,
+        )
+
+        self._core.transfer_liquid(
+            liquid_class_id=liquid_class_id,
+            volume=volume,
+            source=[well._core for well in flat_sources_list],
+            dest=[well._core for well in flat_dests_list],
+            new_tip=valid_new_tip,
+            trash_location=(
+                checked_trash_location._core
+                if isinstance(checked_trash_location, labware.Well)
+                else checked_trash_location
+            ),
+        )
+
+        return self
+
     @requires_version(2, 0)
     def delay(self, *args: Any, **kwargs: Any) -> None:
         """
@@ -1694,6 +1814,8 @@ class InstrumentContext(publisher.CommandPublisher):
     @liquid_presence_detection.setter
     @requires_version(2, 20)
     def liquid_presence_detection(self, enable: bool) -> None:
+        if enable:
+            self._raise_if_pressure_not_supported_by_pipette()
         self._core.set_liquid_presence_detection(enable)
 
     @property
@@ -1870,19 +1992,6 @@ class InstrumentContext(publisher.CommandPublisher):
         else:
             return self._protocol_core.get_last_location()
 
-    def _96_tip_config_valid(self) -> bool:
-        n_map = self._core.get_nozzle_map()
-        channels = self._core.get_active_channels()
-        if channels == 96:
-            if (
-                n_map.back_left != n_map.full_instrument_back_left
-                and n_map.front_right != n_map.full_instrument_front_right
-            ):
-                raise TipNotAttachedError(
-                    "Either the front right or the back left nozzle must have a tip attached to do LLD."
-                )
-        return True
-
     def __repr__(self) -> str:
         return "<{}: {} in {}>".format(
             self.__class__.__name__,
@@ -2143,8 +2252,8 @@ class InstrumentContext(publisher.CommandPublisher):
         .. note::
             The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.
         """
+        self._raise_if_pressure_not_supported_by_pipette()
         loc = well.top()
-        self._96_tip_config_valid()
         return self._core.detect_liquid_presence(well._core, loc)
 
     @requires_version(2, 20)
@@ -2156,8 +2265,8 @@ class InstrumentContext(publisher.CommandPublisher):
         .. note::
             The pressure sensors for the Flex 8-channel pipette are on channels 1 and 8 (positions A1 and H1). For the Flex 96-channel pipette, the pressure sensors are on channels 1 and 96 (positions A1 and H12). Other channels on multi-channel pipettes do not have sensors and cannot detect liquid.
         """
+        self._raise_if_pressure_not_supported_by_pipette()
         loc = well.top()
-        self._96_tip_config_valid()
         self._core.liquid_probe_with_recovery(well._core, loc)
 
     @requires_version(2, 20)
@@ -2170,9 +2279,8 @@ class InstrumentContext(publisher.CommandPublisher):
 
         This is intended for Opentrons internal use only and is not a guaranteed API.
         """
-
+        self._raise_if_pressure_not_supported_by_pipette()
         loc = well.top()
-        self._96_tip_config_valid()
         height = self._core.liquid_probe_without_recovery(well._core, loc)
         return height
 
@@ -2192,6 +2300,12 @@ class InstrumentContext(publisher.CommandPublisher):
                     )
             # SINGLE, QUADRANT and ALL are supported by all pipettes
 
+    def _raise_if_pressure_not_supported_by_pipette(self) -> None:
+        if not self._core._pressure_supported_by_pipette():
+            raise UnsupportedHardwareCommand(
+                "Pressure sensor not available for this pipette"
+            )
+
     def _handle_aspirate_target(
         self, target: validation.ValidTarget
     ) -> tuple[types.Location, Optional[labware.Well], Optional[bool]]: