opentrons 8.4.0a4__tar.gz → 8.4.0a6__tar.gz

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: opentrons
-Version: 8.4.0a4
+Version: 8.4.0a6
 Summary: The Opentrons API is a simple framework designed to make writing automated biology lab protocols easy.
 Author: Opentrons
 Author-email: engineering@opentrons.com
@@ -21,7 +21,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
 License-File: ../LICENSE
-Requires-Dist: opentrons-shared-data==8.4.0a4
+Requires-Dist: opentrons-shared-data==8.4.0a6
 Requires-Dist: aionotify==0.3.1
 Requires-Dist: anyio<4.0.0,>=3.6.1
 Requires-Dist: jsonschema<4.18.0,>=3.0.1
@@ -35,9 +35,9 @@ Requires-Dist: pyusb==1.2.1
 Requires-Dist: importlib-metadata>=1.0; python_version < "3.8"
 Requires-Dist: packaging>=21.0
 Provides-Extra: ot2-hardware
-Requires-Dist: opentrons-hardware==8.4.0a4; extra == "ot2-hardware"
+Requires-Dist: opentrons-hardware==8.4.0a6; extra == "ot2-hardware"
 Provides-Extra: flex-hardware
-Requires-Dist: opentrons-hardware[FLEX]==8.4.0a4; extra == "flex-hardware"
+Requires-Dist: opentrons-hardware[FLEX]==8.4.0a6; extra == "flex-hardware"
 
 .. _Full API Documentation: http://docs.opentrons.com
 

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/core/engine/instrument.py

@@ -12,6 +12,7 @@ from typing import (
     Tuple,
     NamedTuple,
     Generator,
+    Literal,
 )
 from opentrons.types import (
     Location,
@@ -747,6 +748,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
         force_direct: bool,
         minimum_z_height: Optional[float],
         speed: Optional[float],
+        check_for_movement_conflicts: bool = True,
     ) -> None:
         if well_core is not None:
             if isinstance(location, (TrashBin, WasteChute)):
@@ -765,6 +767,14 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             assert isinstance(well_location, LiquidHandlingWellLocation)
             if well_location.volumeOffset and well_location.volumeOffset != 0:
                 raise ValueError("volume offset not supported with move_to")
+            if check_for_movement_conflicts:
+                pipette_movement_conflict.check_safe_for_pipette_movement(
+                    engine_state=self._engine_client.state,
+                    pipette_id=self._pipette_id,
+                    labware_id=labware_id,
+                    well_name=well_name,
+                    well_location=well_location,
+                )
             self._engine_client.execute_command(
                 cmd.MoveToWellParams(
                     pipetteId=self._pipette_id,
@@ -1399,7 +1409,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
         volume: float,
         source: Tuple[Location, WellCore],
         dest: List[Tuple[Location, WellCore]],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[Location, LabwareCore]],
         starting_tip: Optional[WellCore],
         trash_location: Union[Location, TrashBin, WasteChute],
@@ -1415,8 +1425,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             dest: List of destination wells, with each well represented as a tuple of
                     types.Location and WellCore.
                     types.Location is only necessary for saving the last accessed location.
-            new_tip: Whether the transfer should use a new tip 'once', 'never', 'always',
-                     or 'per source'.
+            new_tip: Whether the transfer should use a new tip 'once' or 'never'.
             tiprack_uri: The URI of the tiprack that the transfer settings are for.
             tip_drop_location: Location where the tip will be dropped (if appropriate).
 
@@ -1432,6 +1441,8 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             raise RuntimeError(
                 "No tipracks found for pipette in order to perform transfer"
             )
+        assert new_tip in [TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE]
+
         tiprack_uri_for_transfer_props = tip_racks[0][1].get_uri()
         working_volume = min(
             self.get_max_volume(),
@@ -1559,7 +1570,6 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             )
             return tip_well
 
-        tip_used = False
         if new_tip != TransferTipPolicyV2.NEVER:
             last_tip_picked_up_from = _pick_up_tip()
 
@@ -1604,16 +1614,6 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
                 )
             )
 
-            if new_tip == TransferTipPolicyV2.ALWAYS and tip_used:
-                _drop_tip()
-                last_tip_picked_up_from = _pick_up_tip()
-                tip_contents = [
-                    tx_comps_executor.LiquidAndAirGapPair(
-                        liquid=0,
-                        air_gap=0,
-                    )
-                ]
-
             use_single_dispense = False
             if total_aspirate_volume == volume and len(vol_dest_combo) == 1:
                 # We are only doing a single transfer. Either because this is the last
@@ -1696,7 +1696,6 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
                         disposal_volume=disposal_vol,
                     )
                 is_first_step = False
-            tip_used = True
 
         if new_tip != TransferTipPolicyV2.NEVER:
             _drop_tip()
@@ -1728,7 +1727,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
         volume: float,
         source: List[Tuple[Location, WellCore]],
         dest: Tuple[Location, WellCore],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[Location, LabwareCore]],
         starting_tip: Optional[WellCore],
         trash_location: Union[Location, TrashBin, WasteChute],
@@ -1738,7 +1737,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             raise RuntimeError(
                 "No tipracks found for pipette in order to perform transfer"
             )
-
+        assert new_tip in [TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE]
         tiprack_uri_for_transfer_props = tip_racks[0][1].get_uri()
         try:
             transfer_props = liquid_class.get_for(
@@ -1841,7 +1840,6 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
         if new_tip == TransferTipPolicyV2.ONCE:
             last_tip_picked_up_from = _pick_up_tip()
 
-        prev_src: Optional[Tuple[Location, WellCore]] = None
         tip_contents = [
             tx_comps_executor.LiquidAndAirGapPair(
                 liquid=0,
@@ -1849,6 +1847,7 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
             )
         ]
         next_step_volume, next_source = next(source_per_volume_step)
+        is_first_step = True
         is_last_step = False
         while not is_last_step:
             total_dispense_volume = 0.0
@@ -1863,21 +1862,17 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
                     is_last_step = True
                     break
 
-            if new_tip == TransferTipPolicyV2.ALWAYS:
-                if prev_src is not None:
-                    _drop_tip()
-                last_tip_picked_up_from = _pick_up_tip()
-                tip_contents = [
-                    tx_comps_executor.LiquidAndAirGapPair(
-                        liquid=0,
-                        air_gap=0,
-                    )
-                ]
-            # TODO (spp, 2025-03-24): add LPD feature when 'per source' tip policy is added for consolidate_liquid
-            with self.lpd_for_transfer(enable=False):
-                for step_num, (step_volume, step_source) in enumerate(
-                    vol_aspirate_combo
-                ):
+            if (
+                self.get_liquid_presence_detection()
+                and new_tip != TransferTipPolicyV2.NEVER
+                and is_first_step
+            ):
+                enable_lpd = True
+            else:
+                enable_lpd = False
+
+            for step_num, (step_volume, step_source) in enumerate(vol_aspirate_combo):
+                with self.lpd_for_transfer(enable=enable_lpd):
                     tip_contents = self.aspirate_liquid_class(
                         volume=step_volume,
                         source=step_source,
@@ -1888,6 +1883,8 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
                             total_dispense_volume if step_num == 0 else None
                         ),
                     )
+                is_first_step = False
+                enable_lpd = False
             tip_contents = self.dispense_liquid_class(
                 volume=total_dispense_volume,
                 dest=dest,
@@ -1902,7 +1899,6 @@ class InstrumentCore(AbstractInstrument[WellCore, LabwareCore]):
                 ),
                 trash_location=trash_location,
             )
-            prev_src = next_source
         if new_tip != TransferTipPolicyV2.NEVER:
             _drop_tip()
 

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/core/engine/transfer_components_executor.py

@@ -99,6 +99,14 @@ class TipState:
         ), "Last air gap volume doe not match the volume being removed"
         self.last_liquid_and_air_gap_in_tip.air_gap = 0
 
+    def delete_last_air_gap_and_liquid(self) -> None:
+        air_gap_in_tip = self.last_liquid_and_air_gap_in_tip.air_gap
+        liquid_in_tip = self.last_liquid_and_air_gap_in_tip.liquid
+        if air_gap_in_tip:
+            self.delete_air_gap(air_gap_in_tip)
+        if liquid_in_tip:
+            self.delete_liquid(volume=liquid_in_tip)
+
 
 class TransferType(Enum):
     ONE_TO_ONE = "one_to_one"
@@ -525,6 +533,9 @@ class TransferComponentsExecutor:
                     if isinstance(trash_location, Location)
                     else None
                 )
+            # A non-multi-dispense blowout will only have air and maybe droplets in the tip
+            # since we only blowout after dispensing the full tip contents.
+            # So delete the air gap from tip state
             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
@@ -608,6 +619,10 @@ class TransferComponentsExecutor:
                 well_core=None,
                 in_place=True,
             )
+            # A blowout will remove all air gap and liquid (disposal volume) from the tip
+            # so delete them from tip state (although practically, there will not be
+            # any air gaps in the tip before blowing out in the destination well)
+            self._tip_state.delete_last_air_gap_and_liquid()
             self._tip_state.ready_to_aspirate = False
 
         # A retract will perform total of two air gaps if we need to blow out in source or trash:
@@ -695,8 +710,9 @@ class TransferComponentsExecutor:
                     if isinstance(trash_location, Location)
                     else None
                 )
-            last_air_gap = self._tip_state.last_liquid_and_air_gap_in_tip.air_gap
-            self._tip_state.delete_air_gap(last_air_gap)
+            # A blowout will remove all air gap and liquid (disposal volume) from the tip
+            # so delete them from tip state
+            self._tip_state.delete_last_air_gap_and_liquid()
             self._tip_state.ready_to_aspirate = False
 
             # Do touch tip and air gap again after blowing out into source well or trash

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/core/instrument.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import abstractmethod, ABC
-from typing import Any, Generic, Optional, TypeVar, Union, List, Tuple
+from typing import Any, Generic, Optional, TypeVar, Union, List, Tuple, Literal
 
 from opentrons import types
 from opentrons.hardware_control.dev_types import PipetteDict
@@ -190,6 +190,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         force_direct: bool,
         minimum_z_height: Optional[float],
         speed: Optional[float],
+        check_for_movement_conflicts: bool,
     ) -> None:
         ...
 
@@ -381,7 +382,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         volume: float,
         source: Tuple[types.Location, WellCoreType],
         dest: List[Tuple[types.Location, WellCoreType]],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
         starting_tip: Optional[WellCoreType],
         trash_location: Union[types.Location, TrashBin, WasteChute],
@@ -400,7 +401,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
         volume: float,
         source: List[Tuple[types.Location, WellCoreType]],
         dest: Tuple[types.Location, WellCoreType],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LabwareCoreType]],
         starting_tip: Optional[WellCoreType],
         trash_location: Union[types.Location, TrashBin, WasteChute],

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, Optional, Union, List, Tuple
+from typing import TYPE_CHECKING, Optional, Union, List, Tuple, Literal
 
 from opentrons import types
 from opentrons.hardware_control import CriticalPoint
@@ -367,6 +367,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         force_direct: bool = False,
         minimum_z_height: Optional[float] = None,
         speed: Optional[float] = None,
+        check_for_movement_conflicts: bool = False,
     ) -> None:
         """Move the instrument.
 
@@ -376,6 +377,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
             force_direct: Force a direct movement instead of an arc.
             minimum_z_height: Set a minimum travel height for a movement arc.
             speed: Override the travel speed in mm/s.
+            check_for_movement_conflicts: Not used in legacy implementation
 
         Raises:
             LabwareHeightError: An item on the deck is taller than
@@ -619,7 +621,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         volume: float,
         source: Tuple[types.Location, LegacyWellCore],
         dest: List[Tuple[types.Location, LegacyWellCore]],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
@@ -634,7 +636,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore, LegacyLabwareCore]
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
         dest: Tuple[types.Location, LegacyWellCore],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING, Optional, Union, List, Tuple
+from typing import TYPE_CHECKING, Optional, Union, List, Tuple, Literal
 
 from opentrons import types
 from opentrons.hardware_control.dev_types import PipetteDict
@@ -325,6 +325,7 @@ class LegacyInstrumentCoreSimulator(
         force_direct: bool = False,
         minimum_z_height: Optional[float] = None,
         speed: Optional[float] = None,
+        check_for_movement_conflicts: bool = False,  # Not used in this implementation
     ) -> None:
         """Simulation of only the motion planning portion of move_to."""
         if isinstance(location, (TrashBin, WasteChute)):
@@ -534,7 +535,7 @@ class LegacyInstrumentCoreSimulator(
         volume: float,
         source: Tuple[types.Location, LegacyWellCore],
         dest: List[Tuple[types.Location, LegacyWellCore]],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],
@@ -549,7 +550,7 @@ class LegacyInstrumentCoreSimulator(
         volume: float,
         source: List[Tuple[types.Location, LegacyWellCore]],
         dest: Tuple[types.Location, LegacyWellCore],
-        new_tip: TransferTipPolicyV2,
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
         tip_racks: List[Tuple[types.Location, LegacyLabwareCore]],
         starting_tip: Optional[LegacyWellCore],
         trash_location: Union[types.Location, TrashBin, WasteChute],

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/instrument_context.py

@@ -1529,7 +1529,7 @@ class InstrumentContext(publisher.CommandPublisher):
         """Move a particular type of liquid from one well or group of wells to another.
 
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
-            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
         :type liquid_class: :py:class:`.LiquidClass`
 
@@ -1552,6 +1552,8 @@ class InstrumentContext(publisher.CommandPublisher):
             tips. Depending on the liquid class, the pipette may also blow out liquid here.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
+
+            :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -1634,7 +1636,7 @@ class InstrumentContext(publisher.CommandPublisher):
         Distribute a particular type of liquid from one well to a group of wells.
 
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
-            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
         :type liquid_class: :py:class:`.LiquidClass`
 
@@ -1645,8 +1647,7 @@ class InstrumentContext(publisher.CommandPublisher):
         :param new_tip: When to pick up and drop tips during the command.
             Defaults to ``"once"``.
 
-              - ``"once"`` or ``"per source"``: Use one tip for the entire command.
-              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
+              - ``"once"``: Use one tip for the entire command.
               - ``"never"``: Do not pick up or drop tips at all.
 
             See :ref:`param-tip-handling` for details.
@@ -1655,6 +1656,8 @@ class InstrumentContext(publisher.CommandPublisher):
             tips. Depending on the liquid class, the pipette may also blow out liquid here.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
+
+            :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -1681,9 +1684,14 @@ class InstrumentContext(publisher.CommandPublisher):
                 f"Source should be a single well (or resolve to a single transfer for multi-channel) "
                 f"but received {transfer_args.sources_list}."
             )
-        if transfer_args.tip_policy == TransferTipPolicyV2.PER_SOURCE:
-            raise RuntimeError(
-                'Tip transfer policy "per source" incompatible with distribute.'
+        if transfer_args.tip_policy not in [
+            TransferTipPolicyV2.ONCE,
+            TransferTipPolicyV2.NEVER,
+        ]:
+            raise ValueError(
+                f"Incompatible `new_tip` value of {new_tip}."
+                f" `distribute_with_liquid_class()` only supports `new_tip` values of"
+                f" 'once' and 'never'."
             )
 
         verified_source = transfer_args.sources_list[0]
@@ -1708,7 +1716,7 @@ class InstrumentContext(publisher.CommandPublisher):
                     (types.Location(types.Point(), labware=well), well._core)
                     for well in transfer_args.destinations_list
                 ],
-                new_tip=transfer_args.tip_policy,
+                new_tip=transfer_args.tip_policy,  # type: ignore[arg-type]
                 tip_racks=[
                     (types.Location(types.Point(), labware=rack), rack._core)
                     for rack in transfer_args.tip_racks
@@ -1741,7 +1749,7 @@ class InstrumentContext(publisher.CommandPublisher):
         Consolidate a particular type of liquid from a group of wells to one well.
 
         :param liquid_class: The type of liquid to move. You must specify the liquid class,
-            even if you have used :py:meth:`.load_liquid` to indicate what liquid the
+            even if you have used :py:meth:`.Labware.load_liquid` to indicate what liquid the
             source contains.
         :type liquid_class: :py:class:`.LiquidClass`
 
@@ -1753,8 +1761,6 @@ class InstrumentContext(publisher.CommandPublisher):
             Defaults to ``"once"``.
 
               - ``"once"``: Use one tip for the entire command.
-              - ``"always"``: Use a new tip for each set of aspirate and dispense steps.
-              - ``"per source"``: Not available when consolidating.
               - ``"never"``: Do not pick up or drop tips at all.
 
             See :ref:`param-tip-handling` for details.
@@ -1763,6 +1769,8 @@ class InstrumentContext(publisher.CommandPublisher):
             tips. Depending on the liquid class, the pipette may also blow out liquid here.
         :param return_tip: Whether to drop used tips in their original locations
             in the tip rack, instead of the trash.
+
+            :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -1789,9 +1797,14 @@ class InstrumentContext(publisher.CommandPublisher):
                 f"Destination should be a single well (or resolve to a single transfer for multi-channel) "
                 f"but received {transfer_args.destinations_list}."
             )
-        if transfer_args.tip_policy == TransferTipPolicyV2.PER_SOURCE:
-            raise RuntimeError(
-                'Tip transfer policy "per source" incompatible with consolidate.'
+        if transfer_args.tip_policy not in [
+            TransferTipPolicyV2.ONCE,
+            TransferTipPolicyV2.NEVER,
+        ]:
+            raise ValueError(
+                f"Incompatible `new_tip` value of {new_tip}."
+                f" `consolidate_with_liquid_class()` only supports `new_tip` values of"
+                f" 'once' and 'never'."
             )
 
         verified_dest = transfer_args.destinations_list[0]
@@ -1816,7 +1829,7 @@ class InstrumentContext(publisher.CommandPublisher):
                     types.Location(types.Point(), labware=verified_dest),
                     verified_dest._core,
                 ),
-                new_tip=transfer_args.tip_policy,
+                new_tip=transfer_args.tip_policy,  # type: ignore[arg-type]
                 tip_racks=[
                     (types.Location(types.Point(), labware=rack), rack._core)
                     for rack in transfer_args.tip_racks
@@ -1907,6 +1920,7 @@ class InstrumentContext(publisher.CommandPublisher):
                     force_direct=force_direct,
                     minimum_z_height=minimum_z_height,
                     speed=speed,
+                    check_for_movement_conflicts=False,
                 )
             else:
                 if publish:
@@ -1925,6 +1939,7 @@ class InstrumentContext(publisher.CommandPublisher):
                     force_direct=force_direct,
                     minimum_z_height=minimum_z_height,
                     speed=speed,
+                    check_for_movement_conflicts=False,
                 )
 
         return self
@@ -2639,7 +2654,7 @@ class InstrumentContext(publisher.CommandPublisher):
     def measure_liquid_height(self, well: labware.Well) -> LiquidTrackingType:
         """Check the height of the liquid within a well.
 
-        :returns: The height, in mm, of the liquid from the deck.
+        :returns: The height, in mm, of the liquid from the bottom of the well.
         """
         self._raise_if_pressure_not_supported_by_pipette()
         loc = well.top()

{opentrons-8.4.0a4 → opentrons-8.4.0a6}/src/opentrons/protocol_api/labware.py

@@ -263,15 +263,15 @@ class Well:
 
     @requires_version(2, 21)
     def meniscus(
-        self, target: Literal["start", "end", "dynamic"], z: float = 0.0
+        self, z: float = 0.0, target: Literal["start", "end", "dynamic"] = "end"
     ) -> Location:
         """
         :param z: An offset on the z-axis, in mm. Positive offsets are higher and
             negative offsets are lower.
-        :param target: The relative position inside the well to target when performing a liquid handling operation.
-        :return: A :py:class:`~opentrons.types.Location` that indicates location is meniscus and that holds the ``z`` offset in its point.z field.
+        :param target: The relative position of the liquid meniscus inside the well to target when performing a liquid handling operation.
+
+        :return: A :py:class:`~opentrons.types.Location` corresponding to the liquid meniscus, plus a target position and ``z`` offset as specified.
 
-        :meta private:
         """
         return Location(
             point=Point(x=0, y=0, z=z),
@@ -326,9 +326,9 @@ class Well:
         :param Liquid liquid: The liquid to load into the well.
         :param float volume: The volume of liquid to load, in µL.
 
-        .. TODO: flag as deprecated in 2.22 docs
-            In API version 2.22 and later, use :py:meth:`~Labware.load_liquid`, :py:meth:`~Labware.load_liquid_by_well`,
-            or :py:meth:`~Labware.load_empty` to load liquid into a well.
+        .. deprecated:: 2.22
+            Use :py:meth:`.Labware.load_liquid`, :py:meth:`.Labware.load_liquid_by_well`, or :py:meth:`.Labware.load_empty` instead.
+
         """
         self._core.load_liquid(
             liquid=liquid,
@@ -1270,22 +1270,15 @@ class Labware:
     ) -> None:
         """Mark several wells as containing the same amount of liquid.
 
-        This method should be called at the beginning of a protocol, soon after loading the labware and before
-        liquid handling operations begin. It is a base of information for liquid tracking functionality. If a well in a labware
-        has not been named in a call to :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
-        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked.
-
-        For example, to load 10µL of a liquid named ``water`` (defined with :py:meth:`~ProtocolContext.define_liquid`)
-        into all the wells of a labware, you could call ``labware.load_liquid(labware.wells(), 10, water)``.
-
-        If you want to load different volumes of liquid into different wells, use :py:meth:`~Labware.load_liquid_by_well`.
-
-        If you want to mark the well as containing no liquid, use :py:meth:`~Labware.load_empty`.
+        This method should be called at the beginning of a protocol, soon after loading labware and before
+        liquid handling operations begin. Loading liquids is required for liquid tracking functionality. If a well
+        hasn't been assigned a starting volume with :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
+        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.
 
         :param wells: The wells to load the liquid into.
-        :type wells: List of well names or list of Well objects, for instance from :py:meth:`~Labware.wells`.
+        :type wells: List of string well names or list of :py:class:`.Well` objects (e.g., from :py:meth:`~Labware.wells`).
 
-        :param volume: The volume of liquid to load into each well, in 10µL.
+        :param volume: The volume of liquid to load into each well.
         :type volume: float
 
         :param liquid: The liquid to load into each well, previously defined by :py:meth:`~ProtocolContext.define_liquid`
@@ -1321,18 +1314,9 @@ class Labware:
     ) -> None:
         """Mark several wells as containing unique volumes of liquid.
 
-        This method should be called at the beginning of a protocol, soon after loading the labware and before
-        liquid handling operations begin. It is a base of information for liquid tracking functionality. If a well in a labware
-        has not been named in a call to :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
-        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked.
-
-        For example, to load a decreasing amount of of a liquid named ``water`` (defined with :py:meth:`~ProtocolContext.define_liquid`)
-        into each successive well of a row, you could call
-        ``labware.load_liquid_by_well({'A1': 1000, 'A2': 950, 'A3': 900, ..., 'A12': 600}, water)``
-
-        If you want to load the same volume of a liquid into multiple wells, it is often easier to use :py:meth:`~Labware.load_liquid`.
-
-        If you want to mark the well as containing no liquid, use :py:meth:`~Labware.load_empty`.
+        This method should be called at the beginning of a protocol, soon after loading labware and before
+        liquid handling begins. Loading liquids is required for liquid tracking functionality. If a well hasn't been assigned a starting volume with :py:meth:`~Labware.load_empty`, :py:meth:`~Labware.load_liquid`, or
+        :py:meth:`~Labware.load_liquid_by_well`, the volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.
 
         :param volumes: A dictionary of well names (or :py:class:`Well` objects, for instance from ``labware['A1']``)
         :type wells: Dict[Union[str, Well], float]
@@ -1368,12 +1352,9 @@ class Labware:
     def load_empty(self, wells: Sequence[Union[Well, str]]) -> None:
         """Mark several wells as empty.
 
-        This method should be called at the beginning of a protocol, soon after loading the labware and before liquid handling
-        operations begin. It is a base of information for liquid tracking functionality. If a well in a labware has not been named
-        in a call to :py:meth:`Labware.load_empty`, :py:meth:`Labware.load_liquid`, or :py:meth:`Labware.load_liquid_by_well`, the
-        volume it contains is unknown and the well's liquid will not be tracked.
-
-        For instance, to mark all wells in the labware as empty, you can call ``labware.load_empty(labware.wells())``.
+        This method should be called at the beginning of a protocol, after loading the labware and before liquid handling
+        begins. Loading liquids is required for liquid tracking functionality. If a well in a labware hasn't been assigned a starting volume with :py:meth:`Labware.load_empty`, :py:meth:`Labware.load_liquid`, or :py:meth:`Labware.load_liquid_by_well`, the
+        volume it contains is unknown and the well's liquid will not be tracked throughout the protocol.
 
         :param wells: The list of wells to mark empty. To mark all wells as empty, pass ``labware.wells()``. You can also specify
                       wells by their names (for instance, ``labware.load_empty(['A1', 'A2'])``).