opentrons 8.4.0a13__py2.py3-none-any.whl → 8.5.0a0__py2.py3-none-any.whl

opentrons/protocol_api/core/engine/transfer_components_executor.py

@@ -12,7 +12,6 @@ from opentrons_shared_data.liquid_classes.liquid_class_definition import (
     Coordinate,
     BlowoutLocation,
 )
-from opentrons_shared_data.pipette.types import LIQUID_PROBE_START_OFFSET_FROM_WELL_TOP
 
 from opentrons.protocol_api._liquid_properties import (
     Submerge,
@@ -23,7 +22,7 @@ from opentrons.protocol_api._liquid_properties import (
     TouchTipProperties,
 )
 from opentrons.protocol_engine.errors import TouchTipDisabledError
-from opentrons.types import Location, Point
+from opentrons.types import Location, Point, Mount
 from opentrons.protocols.advanced_control.transfers.transfer_liquid_utils import (
     LocationCheckDescriptors,
 )
@@ -119,11 +118,32 @@ class TransferComponentsExecutor:
         self,
         instrument_core: InstrumentCore,
         transfer_properties: TransferProperties,
-        target_location: Location,
-        target_well: WellCore,
+        target_location: Union[Location, TrashBin, WasteChute],
+        target_well: Optional[WellCore],
         tip_state: TipState,
         transfer_type: TransferType,
     ) -> None:
+        """Create a TransferComponentsExecutor instance.
+
+        One instance should be created to execute all the steps inside each of the
+        liquid class' transfer components- aspirate, dispense and multi-dispense.
+        The state of the TransferComponentsExecutor instance is expected to be valid
+        only for the component it was created.
+
+        For example, if we want to execute all the steps (submerge, dispense, retract, etc)
+        related to the 'dispense' component of a liquid-class based transfer, the class
+        will be used to initialize info about the dispense by assigning values
+        to class attributes as follows-
+        - target_location: the dispense location
+        - target_well: the well associated with dispense location, will be None when the
+                        target_location argument is a TrashBin or WasteChute
+        - tip_state: the state of the tip before dispense component steps are executed
+        - transfer_type: whether the dispense component is being called as a part of a
+                        1-to-1 transfer or a consolidation or a distribution
+
+        These attributes will remain the same throughout the component's execution,
+        except `tip_state`, which will keep updating as fluids are handled.
+        """
         self._instrument = instrument_core
         self._transfer_properties = transfer_properties
         self._target_location = target_location
@@ -140,7 +160,6 @@ class TransferComponentsExecutor:
         self,
         submerge_properties: Submerge,
         post_submerge_action: Literal["aspirate", "dispense"],
-        volume_for_pipette_mode_configuration: Optional[float],
     ) -> None:
         """Execute submerge steps.
 
@@ -148,56 +167,38 @@ class TransferComponentsExecutor:
         Should raise an error if this point is inside the liquid?
             For liquid meniscus this is easy to tell. Can’t be below meniscus
             For reference pos of anything else, do not allow submerge position to be below aspirate position
-        2. move to aspirate position at desired speed
+        2. move to aspirate/dispense position at desired speed
         3. delay
+
+        If target location is a trash bin or waste chute, the pipette will move to the disposal location given,
+        remove air gap and delay
         """
-        submerge_start_point = absolute_point_from_position_reference_and_offset(
-            well=self._target_well,
-            position_reference=submerge_properties.position_reference,
-            offset=submerge_properties.offset,
-        )
-        submerge_start_location = Location(
-            point=submerge_start_point, labware=self._target_location.labware
-        )
-        prep_before_moving_to_submerge = (
-            post_submerge_action == "aspirate"
-            and volume_for_pipette_mode_configuration is not None
-        )
-        if prep_before_moving_to_submerge:
-            # Move to the tip probe start position
-            self._instrument.move_to(
-                location=Location(
-                    point=self._target_well.get_top(
-                        LIQUID_PROBE_START_OFFSET_FROM_WELL_TOP.z
-                    ),
-                    labware=self._target_location.labware,
-                ),
+        submerge_start_location: Union[Location, TrashBin, WasteChute]
+        if isinstance(self._target_location, Location):
+            assert self._target_well is not None
+            submerge_start_point = absolute_point_from_position_reference_and_offset(
+                well=self._target_well,
+                well_volume_difference=0,
+                position_reference=submerge_properties.start_position.position_reference,
+                offset=submerge_properties.start_position.offset,
+                mount=self._instrument.get_mount(),
+            )
+            submerge_start_location = Location(
+                point=submerge_start_point, labware=self._target_location.labware
+            )
+            tx_utils.raise_if_location_inside_liquid(
+                location=submerge_start_location,
+                well_location=self._target_location,
                 well_core=self._target_well,
-                force_direct=False,
-                minimum_z_height=None,
-                speed=None,
+                location_check_descriptors=LocationCheckDescriptors(
+                    location_type="submerge start",
+                    pipetting_action=post_submerge_action,
+                ),
+                logger=log,
             )
-            self._remove_air_gap(location=submerge_start_location)
-            if (
-                self._transfer_type != TransferType.MANY_TO_ONE
-                and self._instrument.get_liquid_presence_detection()
-            ):
-                self._instrument.liquid_probe_with_recovery(
-                    well_core=self._target_well, loc=submerge_start_location
-                )
-            # TODO: do volume configuration + prepare for aspirate only if the mode needs to be changed
-            self._instrument.configure_for_volume(volume_for_pipette_mode_configuration)  # type: ignore[arg-type]
-            self._instrument.prepare_to_aspirate()
-        tx_utils.raise_if_location_inside_liquid(
-            location=submerge_start_location,
-            well_location=self._target_location,
-            well_core=self._target_well,
-            location_check_descriptors=LocationCheckDescriptors(
-                location_type="submerge start",
-                pipetting_action=post_submerge_action,
-            ),
-            logger=log,
-        )
+        else:
+            submerge_start_location = self._target_location
+
         self._instrument.move_to(
             location=submerge_start_location,
             well_core=self._target_well,
@@ -205,21 +206,26 @@ class TransferComponentsExecutor:
             minimum_z_height=None,
             speed=None,
         )
-        if not prep_before_moving_to_submerge:
-            self._remove_air_gap(location=submerge_start_location)
-        self._instrument.move_to(
-            location=self._target_location,
-            well_core=self._target_well,
-            force_direct=True,
-            minimum_z_height=None,
-            speed=submerge_properties.speed,
-        )
+        self._remove_air_gap(location=submerge_start_location)
+        if isinstance(self._target_location, Location):
+            self._instrument.move_to(
+                location=self._target_location,
+                well_core=self._target_well,
+                force_direct=True,
+                minimum_z_height=None,
+                speed=submerge_properties.speed,
+            )
+
         if submerge_properties.delay.enabled and submerge_properties.delay.duration:
             self._instrument.delay(submerge_properties.delay.duration)
 
     def aspirate_and_wait(self, volume: float) -> None:
         """Aspirate according to aspirate properties and wait if enabled."""
         # TODO: handle volume correction
+        assert (
+            isinstance(self._target_location, Location)
+            and self._target_well is not None
+        )
         aspirate_props = self._transfer_properties.aspirate
         correction_volume = aspirate_props.correction_by_volume.get_for_volume(volume)
         self._instrument.aspirate(
@@ -275,11 +281,15 @@ class TransferComponentsExecutor:
         NOTE: For most of our built-in definitions, we will keep _mix_ off because it is a very application specific thing.
         We should mention in our docs that users should adjust this property according to their application.
         """
-        if not mix_properties.enabled:
+        if not mix_properties.enabled or not isinstance(
+            self._target_location, Location
+        ):
             return
         # Assertion only for mypy purposes
         assert (
-            mix_properties.repetitions is not None and mix_properties.volume is not None
+            mix_properties.repetitions is not None
+            and mix_properties.volume is not None
+            and self._target_well is not None
         )
         push_out_vol = (
             self._transfer_properties.dispense.push_out_by_volume.get_for_volume(
@@ -337,11 +347,17 @@ class TransferComponentsExecutor:
                          during a multi-dispense.
         """
         # TODO: Raise error if retract is below the meniscus
+        assert (
+            isinstance(self._target_location, Location)
+            and self._target_well is not None
+        )
         retract_props = self._transfer_properties.aspirate.retract
         retract_point = absolute_point_from_position_reference_and_offset(
             well=self._target_well,
-            position_reference=retract_props.position_reference,
-            offset=retract_props.offset,
+            well_volume_difference=0,
+            position_reference=retract_props.end_position.position_reference,
+            offset=retract_props.end_position.offset,
+            mount=self._instrument.get_mount(),
         )
         retract_location = Location(
             retract_point, labware=self._target_location.labware
@@ -371,7 +387,7 @@ class TransferComponentsExecutor:
             assert (
                 touch_tip_props.speed is not None
                 and touch_tip_props.z_offset is not None
-                and touch_tip_props.mm_to_edge is not None
+                and touch_tip_props.mm_from_edge is not None
             )
             self._instrument.touch_tip(
                 location=retract_location,
@@ -379,7 +395,7 @@ class TransferComponentsExecutor:
                 radius=1,
                 z_offset=touch_tip_props.z_offset,
                 speed=touch_tip_props.speed,
-                mm_from_edge=touch_tip_props.mm_to_edge,
+                mm_from_edge=touch_tip_props.mm_from_edge,
             )
             self._instrument.move_to(
                 location=retract_location,
@@ -431,35 +447,47 @@ class TransferComponentsExecutor:
             - Prepare-to-aspirate (top of well)
             - Do air-gap (top of well)
         7. If drop tip, move to drop tip location, drop tip
+
+        If target location is a trash bin or waste chute, the retract movement step is skipped along with touch tip,
+        even if it is enabled.
         """
         # TODO: Raise error if retract is below the meniscus
-
         retract_props = self._transfer_properties.dispense.retract
-        retract_point = absolute_point_from_position_reference_and_offset(
-            well=self._target_well,
-            position_reference=retract_props.position_reference,
-            offset=retract_props.offset,
-        )
-        retract_location = Location(
-            retract_point, labware=self._target_location.labware
-        )
-        tx_utils.raise_if_location_inside_liquid(
-            location=retract_location,
-            well_location=self._target_location,
-            well_core=self._target_well,
-            location_check_descriptors=LocationCheckDescriptors(
-                location_type="retract end",
-                pipetting_action="dispense",
-            ),
-            logger=log,
-        )
-        self._instrument.move_to(
-            location=retract_location,
-            well_core=self._target_well,
-            force_direct=True,
-            minimum_z_height=None,
-            speed=retract_props.speed,
-        )
+
+        retract_location: Union[Location, TrashBin, WasteChute]
+        if isinstance(self._target_location, Location):
+            assert self._target_well is not None
+            retract_point = absolute_point_from_position_reference_and_offset(
+                well=self._target_well,
+                well_volume_difference=0,
+                position_reference=retract_props.end_position.position_reference,
+                offset=retract_props.end_position.offset,
+                mount=self._instrument.get_mount(),
+            )
+            retract_location = Location(
+                retract_point, labware=self._target_location.labware
+            )
+            tx_utils.raise_if_location_inside_liquid(
+                location=retract_location,
+                well_location=self._target_location,
+                well_core=self._target_well,
+                location_check_descriptors=LocationCheckDescriptors(
+                    location_type="retract end",
+                    pipetting_action="dispense",
+                ),
+                logger=log,
+            )
+            self._instrument.move_to(
+                location=retract_location,
+                well_core=self._target_well,
+                force_direct=True,
+                minimum_z_height=None,
+                speed=retract_props.speed,
+            )
+        else:
+            retract_location = self._target_location
+
+        # TODO should we delay here for a trash despite not having a "retract"?
         retract_delay = retract_props.delay
         if retract_delay.enabled and retract_delay.duration:
             self._instrument.delay(retract_delay.duration)
@@ -487,7 +515,9 @@ class TransferComponentsExecutor:
         # then skip the final air gap if we have been told to do so.
         self._do_touch_tip_and_air_gap(
             touch_tip_properties=retract_props.touch_tip,
-            location=retract_location,
+            location=retract_location
+            if isinstance(retract_location, Location)
+            else None,
             well=self._target_well,
             add_air_gap=False if is_final_air_gap and not add_final_air_gap else True,
         )
@@ -573,14 +603,19 @@ class TransferComponentsExecutor:
         and whether we are moving to another dispense or going back to the source.
         """
         # TODO: Raise error if retract is below the meniscus
-
+        assert (
+            isinstance(self._target_location, Location)
+            and self._target_well is not None
+        )
         assert self._transfer_properties.multi_dispense is not None
 
         retract_props = self._transfer_properties.multi_dispense.retract
         retract_point = absolute_point_from_position_reference_and_offset(
             well=self._target_well,
-            position_reference=retract_props.position_reference,
-            offset=retract_props.offset,
+            well_volume_difference=0,
+            position_reference=retract_props.end_position.position_reference,
+            offset=retract_props.end_position.offset,
+            mount=self._instrument.get_mount(),
         )
         retract_location = Location(
             retract_point, labware=self._target_location.labware
@@ -740,7 +775,7 @@ class TransferComponentsExecutor:
             assert (
                 touch_tip_properties.speed is not None
                 and touch_tip_properties.z_offset is not None
-                and touch_tip_properties.mm_to_edge is not None
+                and touch_tip_properties.mm_from_edge is not None
             )
             # TODO:, check that when blow out is a non-dest-well,
             #  whether the touch tip params from transfer props should be used for
@@ -753,7 +788,7 @@ class TransferComponentsExecutor:
                         radius=1,
                         z_offset=touch_tip_properties.z_offset,
                         speed=touch_tip_properties.speed,
-                        mm_from_edge=touch_tip_properties.mm_to_edge,
+                        mm_from_edge=touch_tip_properties.mm_from_edge,
                     )
                 except TouchTipDisabledError:
                     # TODO: log a warning
@@ -803,43 +838,33 @@ class TransferComponentsExecutor:
             self._instrument.delay(delay_props.duration)
         self._tip_state.append_air_gap(air_gap_volume)
 
-    def _remove_air_gap(self, location: Location) -> None:
+    def _remove_air_gap(self, location: Union[Location, TrashBin, WasteChute]) -> None:
         """Remove a previously added air gap."""
         last_air_gap = self._tip_state.last_liquid_and_air_gap_in_tip.air_gap
-        if last_air_gap == 0:
-            return
-
         dispense_props = self._transfer_properties.dispense
-        correction_volume = dispense_props.correction_by_volume.get_for_volume(
-            last_air_gap
-        )
-        # The minimum flow rate should be air_gap_volume per second
-        flow_rate = max(
-            dispense_props.flow_rate_by_volume.get_for_volume(last_air_gap),
-            last_air_gap,
-        )
-        self._instrument.dispense(
+        self._instrument.remove_air_gap_during_transfer_with_liquid_class(
+            last_air_gap=last_air_gap,
+            dispense_props=dispense_props,
             location=location,
-            well_core=None,
-            volume=last_air_gap,
-            rate=1,
-            flow_rate=flow_rate,
-            in_place=True,
-            push_out=0,
-            correction_volume=correction_volume,
         )
         self._tip_state.delete_air_gap(last_air_gap)
-        dispense_delay = dispense_props.delay
-        if dispense_delay.enabled and dispense_delay.duration:
-            self._instrument.delay(dispense_delay.duration)
 
 
 def absolute_point_from_position_reference_and_offset(
     well: WellCore,
+    well_volume_difference: float,
     position_reference: PositionReference,
     offset: Coordinate,
+    mount: Mount,
 ) -> Point:
-    """Return the absolute point, given the well, the position reference and offset."""
+    """Return the absolute point, given the well, the position reference and offset.
+
+    If using meniscus as the position reference, well_volume_difference should be specified.
+    `well_volume_difference` is the expected *difference* in well volume we want to consider
+    when estimating the height of the liquid meniscus after an aspirate/ dispense.
+    So, for liquid height estimation after an aspirate, well_volume_difference is
+    expected to be a -ve value while for a dispense, it will be a +ve value.
+    """
     match position_reference:
         case PositionReference.WELL_TOP:
             reference_point = well.get_top(0)
@@ -848,11 +873,17 @@ def absolute_point_from_position_reference_and_offset(
         case PositionReference.WELL_CENTER:
             reference_point = well.get_center()
         case PositionReference.LIQUID_MENISCUS:
-            meniscus_point = well.get_meniscus()
-            if not isinstance(meniscus_point, Point):
-                reference_point = well.get_center()
+            estimated_liquid_height = well.estimate_liquid_height_after_pipetting(
+                mount=mount,
+                operation_volume=well_volume_difference,
+            )
+            if isinstance(estimated_liquid_height, (float, int)):
+                reference_point = well.get_bottom(z_offset=estimated_liquid_height)
             else:
-                reference_point = meniscus_point
+                # If estimated liquid height gives a SimulatedProbeResult then
+                # assume meniscus is at well center.
+                # Will this cause more harm than good? Is there a better alternative to this?
+                reference_point = well.get_center()
         case _:
             raise ValueError(f"Unknown position reference {position_reference}")
     return reference_point + Point(offset.x, offset.y, offset.z)

opentrons/protocol_api/core/engine/well.py

@@ -223,3 +223,19 @@ class WellCore(AbstractWellCore):
         return self._engine_client.state.geometry.get_current_well_volume(
             labware_id=labware_id, well_name=well_name
         )
+
+    def height_from_volume(self, volume: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the height in a well corresponding to a given volume."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_well_height_at_volume(
+            labware_id=labware_id, well_name=well_name, volume=volume
+        )
+
+    def volume_from_height(self, height: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the volume contained in a well at any height."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_well_volume_at_height(
+            labware_id=labware_id, well_name=well_name, height=height
+        )

opentrons/protocol_api/core/instrument.py

@@ -365,7 +365,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, WellCoreType]],
-        dest: List[Tuple[types.Location, WellCoreType]],
+        dest: Union[List[Tuple[types.Location, WellCoreType]], TrashBin, WasteChute],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
         starting_tip: Optional[WellCoreType],
@@ -400,7 +400,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, WellCoreType]],
-        dest: Tuple[types.Location, WellCoreType],
+        dest: Union[Tuple[types.Location, WellCoreType], TrashBin, WasteChute],
         new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
         starting_tip: Optional[WellCoreType],

opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -605,7 +605,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
-        dest: List[Tuple[types.Location, LegacyWellCore]],
+        dest: Union[List[Tuple[types.Location, LegacyWellCore]], TrashBin, WasteChute],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
@@ -635,7 +635,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
-        dest: Tuple[types.Location, LegacyWellCore],
+        dest: Union[Tuple[types.Location, LegacyWellCore], TrashBin, WasteChute],
         new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],

opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -599,7 +599,7 @@ class LegacyProtocolCore(
         """Define a liquid to load into a well."""
         assert False, "define_liquid only supported on engine core"
 
-    def define_liquid_class(self, name: str) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int) -> LiquidClass:
         """Define a liquid class."""
         assert False, "define_liquid_class is only supported on engine core"
 

opentrons/protocol_api/core/legacy/legacy_well_core.py

@@ -143,6 +143,14 @@ class LegacyWellCore(AbstractWellCore):
         """Get the current well volume."""
         return 0.0
 
+    def height_from_volume(self, volume: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the height in a well corresponding to a given volume."""
+        return 0.0
+
+    def volume_from_height(self, height: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the volume contained in a well at any height."""
+        return 0.0
+
     # TODO(mc, 2022-10-28): is this used and/or necessary?
     def __repr__(self) -> str:
         """Use the well's display name as its repr."""

opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -519,7 +519,7 @@ class LegacyInstrumentCoreSimulator(
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
-        dest: List[Tuple[types.Location, LegacyWellCore]],
+        dest: Union[List[Tuple[types.Location, LegacyWellCore]], TrashBin, WasteChute],
         new_tip: TransferTipPolicyV2,
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
@@ -549,7 +549,7 @@ class LegacyInstrumentCoreSimulator(
         liquid_class: LiquidClass,
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
-        dest: Tuple[types.Location, LegacyWellCore],
+        dest: Union[Tuple[types.Location, LegacyWellCore], TrashBin, WasteChute],
         new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],

opentrons/protocol_api/core/protocol.py

@@ -230,7 +230,7 @@ class AbstractProtocol(
     def get_last_location(
         self,
         mount: Optional[Mount] = None,
-    ) -> Optional[Location]:
+    ) -> Optional[Union[Location, TrashBin, WasteChute]]:
         ...
 
     @abstractmethod
@@ -311,7 +311,7 @@ class AbstractProtocol(
         """Define a liquid to load into a well."""
 
     @abstractmethod
-    def define_liquid_class(self, name: str) -> LiquidClass:
+    def define_liquid_class(self, name: str, version: int) -> LiquidClass:
         """Define a liquid class for use in transfer functions."""
 
     @abstractmethod

opentrons/protocol_api/core/well.py

@@ -104,5 +104,13 @@ class AbstractWellCore(ABC):
     def get_liquid_volume(self) -> LiquidTrackingType:
         """Get the current volume within a well."""
 
+    @abstractmethod
+    def height_from_volume(self, volume: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the height in a well corresponding to a given volume."""
+
+    @abstractmethod
+    def volume_from_height(self, height: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the volume contained in a well at any height."""
+
 
 WellCoreType = TypeVar("WellCoreType", bound=AbstractWellCore)