opentrons 8.1.0a0__py2.py3-none-any.whl → 8.2.0a0__py2.py3-none-any.whl

opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -80,6 +80,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore]):
         rate: float,
         flow_rate: float,
         in_place: bool,
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Aspirate a given volume of liquid from the specified location.
         Args:
@@ -122,6 +123,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore]):
         flow_rate: float,
         in_place: bool,
         push_out: Optional[float],
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Dispense a given volume of liquid into the specified location.
         Args:

opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -17,7 +17,7 @@ from opentrons.protocols import labware as labware_definition
 
 from ...labware import Labware
 from ...disposal_locations import TrashBin, WasteChute
-from ..._liquid import Liquid
+from ..._liquid import Liquid, LiquidClass
 from ..._types import OffDeckType
 from ..protocol import AbstractProtocol
 from ..labware import LabwareLoadParams
@@ -267,7 +267,6 @@ class LegacyProtocolCore(
         """Load an adapter using its identifying parameters"""
         raise APIVersionError(api_element="Loading adapter")
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     def move_labware(
         self,
         labware_core: LegacyLabwareCore,
@@ -532,6 +531,10 @@ 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:
+        """Define a liquid class."""
+        assert False, "define_liquid_class is only supported on engine core"
+
     def get_labware_location(
         self, labware_core: LegacyLabwareCore
     ) -> Union[

opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -91,6 +91,7 @@ class LegacyInstrumentCoreSimulator(AbstractInstrument[LegacyWellCore]):
         rate: float,
         flow_rate: float,
         in_place: bool,
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         if self.get_current_volume() == 0:
             # Make sure we're at the top of the labware and clear of any
@@ -132,6 +133,7 @@ class LegacyInstrumentCoreSimulator(AbstractInstrument[LegacyWellCore]):
         flow_rate: float,
         in_place: bool,
         push_out: Optional[float],
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         if isinstance(location, (TrashBin, WasteChute)):
             raise APIVersionError(

opentrons/protocol_api/core/module.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import List, Optional, TypeVar, ClassVar
+from typing import List, Dict, Optional, TypeVar, ClassVar
 
 from opentrons.drivers.types import (
     HeaterShakerLabwareLatchStatus,
@@ -16,6 +16,7 @@ from opentrons.hardware_control.modules.types import (
     MagneticStatus,
     SpeedStatus,
 )
+from opentrons.protocol_engine.types import ABSMeasureMode
 from opentrons.types import DeckSlotName
 
 
@@ -355,9 +356,26 @@ class AbstractAbsorbanceReaderCore(AbstractModuleCore):
         """Get the module's unique hardware serial number."""
 
     @abstractmethod
-    def initialize(self, wavelength: int) -> None:
+    def initialize(
+        self,
+        mode: ABSMeasureMode,
+        wavelengths: List[int],
+        reference_wavelength: Optional[int] = None,
+    ) -> None:
         """Initialize the Absorbance Reader by taking zero reading."""
 
     @abstractmethod
-    def initiate_read(self) -> None:
-        """Initiate read on the Absorbance Reader."""
+    def read(self, filename: Optional[str] = None) -> Dict[int, Dict[str, float]]:
+        """Get an absorbance reading from the Absorbance Reader."""
+
+    @abstractmethod
+    def close_lid(self) -> None:
+        """Close the Absorbance Reader's lid."""
+
+    @abstractmethod
+    def open_lid(self) -> None:
+        """Open the Absorbance Reader's lid."""
+
+    @abstractmethod
+    def is_lid_on(self) -> bool:
+        """Return True if the Absorbance Reader's lid is currently closed."""

opentrons/protocol_api/core/protocol.py

@@ -18,7 +18,7 @@ from opentrons.protocols.api_support.util import AxisMaxSpeeds
 from .instrument import InstrumentCoreType
 from .labware import LabwareCoreType, LabwareLoadParams
 from .module import ModuleCoreType
-from .._liquid import Liquid
+from .._liquid import Liquid, LiquidClass
 from .._types import OffDeckType
 from ..disposal_locations import TrashBin, WasteChute
 
@@ -93,7 +93,6 @@ class AbstractProtocol(
         """Load an adapter using its identifying parameters"""
         ...
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     @abstractmethod
     def move_labware(
         self,
@@ -248,6 +247,10 @@ class AbstractProtocol(
     ) -> Liquid:
         """Define a liquid to load into a well."""
 
+    @abstractmethod
+    def define_liquid_class(self, name: str) -> LiquidClass:
+        """Define a liquid class for use in transfer functions."""
+
     @abstractmethod
     def get_labware_location(
         self, labware_core: LabwareCoreType

opentrons/protocol_api/instrument_context.py

@@ -39,12 +39,7 @@ from ._nozzle_layout import NozzleLayout
 from . import labware, validation
 
 
-AdvancedLiquidHandling = Union[
-    labware.Well,
-    types.Location,
-    Sequence[Union[labware.Well, types.Location]],
-    Sequence[Sequence[labware.Well]],
-]
+AdvancedLiquidHandling = transfers.AdvancedLiquidHandling
 
 _DEFAULT_ASPIRATE_CLEARANCE = 1.0
 _DEFAULT_DISPENSE_CLEARANCE = 1.0
@@ -222,8 +217,9 @@ class InstrumentContext(publisher.CommandPublisher):
             )
         )
 
-        well: Optional[labware.Well] = None
         move_to_location: types.Location
+        well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
         last_location = self._get_last_location_by_api_version()
         try:
             target = validation.validate_location(
@@ -237,17 +233,13 @@ class InstrumentContext(publisher.CommandPublisher):
                 "knows where it is."
             ) from e
 
-        if isinstance(target, validation.WellTarget):
-            move_to_location = target.location or target.well.bottom(
-                z=self._well_bottom_clearances.aspirate
-            )
-            well = target.well
-        if isinstance(target, validation.PointTarget):
-            move_to_location = target.location
         if isinstance(target, (TrashBin, WasteChute)):
             raise ValueError(
                 "Trash Bin and Waste Chute are not acceptable location parameters for Aspirate commands."
             )
+        move_to_location, well, is_meniscus = self._handle_aspirate_target(
+            target=target
+        )
         if self.api_version >= APIVersion(2, 11):
             instrument.validate_takes_liquid(
                 location=move_to_location,
@@ -287,6 +279,7 @@ class InstrumentContext(publisher.CommandPublisher):
                 rate=rate,
                 flow_rate=flow_rate,
                 in_place=target.in_place,
+                is_meniscus=is_meniscus,
             )
 
         return self
@@ -389,6 +382,7 @@ class InstrumentContext(publisher.CommandPublisher):
             )
         )
         well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
         last_location = self._get_last_location_by_api_version()
 
         try:
@@ -407,6 +401,7 @@ class InstrumentContext(publisher.CommandPublisher):
             well = target.well
             if target.location:
                 move_to_location = target.location
+                is_meniscus = target.location.is_meniscus
             elif well.parent._core.is_fixed_trash():
                 move_to_location = target.well.top()
             else:
@@ -472,6 +467,7 @@ class InstrumentContext(publisher.CommandPublisher):
                 flow_rate=flow_rate,
                 in_place=target.in_place,
                 push_out=push_out,
+                is_meniscus=is_meniscus,
             )
 
         return self
@@ -545,12 +541,12 @@ class InstrumentContext(publisher.CommandPublisher):
             ),
         ):
             self.aspirate(volume, location, rate)
-            while repetitions - 1 > 0:
-                self.dispense(volume, rate=rate, **dispense_kwargs)
-                self.aspirate(volume, rate=rate)
-                repetitions -= 1
-            self.dispense(volume, rate=rate)
-
+            with AutoProbeDisable(self):
+                while repetitions - 1 > 0:
+                    self.dispense(volume, rate=rate, **dispense_kwargs)
+                    self.aspirate(volume, rate=rate)
+                    repetitions -= 1
+                self.dispense(volume, rate=rate)
         return self
 
     @requires_version(2, 0)
@@ -2196,6 +2192,42 @@ class InstrumentContext(publisher.CommandPublisher):
                     )
             # SINGLE, QUADRANT and ALL are supported by all pipettes
 
+    def _handle_aspirate_target(
+        self, target: validation.ValidTarget
+    ) -> tuple[types.Location, Optional[labware.Well], Optional[bool]]:
+        move_to_location: types.Location
+        well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
+        if isinstance(target, validation.WellTarget):
+            well = target.well
+            if target.location:
+                move_to_location = target.location
+                is_meniscus = target.location.is_meniscus
+
+            else:
+                move_to_location = target.well.bottom(
+                    z=self._well_bottom_clearances.aspirate
+                )
+        if isinstance(target, validation.PointTarget):
+            move_to_location = target.location
+        return (move_to_location, well, is_meniscus)
+
+
+class AutoProbeDisable:
+    """Use this class to temporarily disable automatic liquid presence detection."""
+
+    def __init__(self, instrument: InstrumentContext):
+        self.instrument = instrument
+
+    def __enter__(self) -> None:
+        if self.instrument.api_version >= APIVersion(2, 21):
+            self.auto_presence = self.instrument.liquid_presence_detection
+            self.instrument.liquid_presence_detection = False
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        if self.instrument.api_version >= APIVersion(2, 21):
+            self.instrument.liquid_presence_detection = self.auto_presence
+
 
 def _raise_if_has_end_or_front_right_or_back_left(
     style: NozzleLayout,

opentrons/protocol_api/labware.py

@@ -30,7 +30,6 @@ from opentrons.hardware_control.nozzle_manager import NozzleMap
 # remove when their usage is no longer needed
 from opentrons.protocols.labware import (  # noqa: F401
     get_labware_definition as get_labware_definition,
-    get_all_labware_definitions as get_all_labware_definitions,
     verify_definition as verify_definition,
     save_definition as save_definition,
 )
@@ -222,6 +221,19 @@ class Well:
         """
         return Location(self._core.get_center(), self)
 
+    @requires_version(2, 21)
+    def meniscus(self, z: float = 0.0) -> Location:
+        """
+        :param z: An offset on the z-axis, in mm. Positive offsets are higher and
+            negative offsets are lower.
+        :return: A :py:class:`~opentrons.types.Location` that indicates location is meniscus and that holds the ``z`` offset in its point.z field.
+
+        :meta private:
+        """
+        return Location(
+            point=Point(x=0, y=0, z=z), labware=self, _ot_internal_is_meniscus=True
+        )
+
     @requires_version(2, 8)
     def from_center_cartesian(self, x: float, y: float, z: float) -> Point:
         """

opentrons/protocol_api/module_contexts.py

@@ -1,16 +1,16 @@
 from __future__ import annotations
 
 import logging
-from typing import List, Optional, Union, cast
+from typing import List, Dict, Optional, Union, cast
 
+from opentrons.protocol_engine.types import ABSMeasureMode
 from opentrons_shared_data.labware.types import LabwareDefinition
 from opentrons_shared_data.module.types import ModuleModel, ModuleType
 
 from opentrons.legacy_broker import LegacyBroker
-from opentrons.hardware_control.modules import ThermocyclerStep
 from opentrons.legacy_commands import module_commands as cmds
 from opentrons.legacy_commands.publisher import CommandPublisher, publish
-from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.types import APIVersion, ThermocyclerStep
 from opentrons.protocols.api_support.util import (
     APIVersionError,
     requires_version,
@@ -628,6 +628,13 @@ class ThermocyclerContext(ModuleContext):
             ``hold_time_minutes`` and ``hold_time_seconds`` must be defined
             and for each step.
 
+        .. note:
+
+            Before API Version 2.21, Thermocycler profiles run with this command
+            would be listed in the app as having a number of repetitions equal to
+            their step count. At or above API Version 2.21, the structure of the
+            Thermocycler cycles is preserved.
+
         """
         repetitions = validation.ensure_thermocycler_repetition_count(repetitions)
         validated_steps = validation.ensure_thermocycler_profile_steps(steps)
@@ -976,23 +983,71 @@ class AbsorbanceReaderContext(ModuleContext):
     It should not be instantiated directly; instead, it should be
     created through :py:meth:`.ProtocolContext.load_module`.
 
-    .. versionadded:: 2.18
+    .. versionadded:: 2.21
     """
 
     _core: AbsorbanceReaderCore
 
     @property
-    @requires_version(2, 18)
+    @requires_version(2, 21)
     def serial_number(self) -> str:
         """Get the module's unique hardware serial number."""
         return self._core.get_serial_number()
 
-    @requires_version(2, 18)
-    def initialize(self, wavelength: int) -> None:
-        """Initialize the Absorbance Reader by taking zero reading."""
-        self._core.initialize(wavelength)
+    @requires_version(2, 21)
+    def close_lid(self) -> None:
+        """Close the lid of the Absorbance Reader."""
+        self._core.close_lid()
+
+    @requires_version(2, 21)
+    def open_lid(self) -> None:
+        """Open the lid of the Absorbance Reader."""
+        self._core.open_lid()
+
+    @requires_version(2, 21)
+    def is_lid_on(self) -> bool:
+        """Return ``True`` if the Absorbance Reader's lid is currently closed."""
+        return self._core.is_lid_on()
+
+    @requires_version(2, 21)
+    def initialize(
+        self,
+        mode: ABSMeasureMode,
+        wavelengths: List[int],
+        reference_wavelength: Optional[int] = None,
+    ) -> None:
+        """Take a zero reading on the Absorbance Plate Reader Module.
+
+        :param mode: Either ``"single"`` or ``"multi"``.
+
+             - In single measurement mode, :py:meth:`.AbsorbanceReaderContext.read` uses
+               one sample wavelength and an optional reference wavelength.
+             - In multiple measurement mode, :py:meth:`.AbsorbanceReaderContext.read` uses
+               a list of up to six sample wavelengths.
+        :param wavelengths: A list of wavelengths, in mm, to measure.
+             - Must contain only one item when initializing a single measurement.
+             - Must contain one to six items when initializing a multiple measurement.
+        :param reference_wavelength: An optional reference wavelength, in mm. Cannot be
+             used with multiple measurements.
+        """
+        self._core.initialize(
+            mode, wavelengths, reference_wavelength=reference_wavelength
+        )
+
+    @requires_version(2, 21)
+    def read(
+        self, export_filename: Optional[str] = None
+    ) -> Dict[int, Dict[str, float]]:
+        """Initiate read on the Absorbance Reader.
 
-    @requires_version(2, 18)
-    def initiate_read(self) -> None:
-        """Initiate read on the Absorbance Reader."""
-        self._core.initiate_read()
+        Returns a dictionary of wavelengths to dictionary of values ordered by well name.
+
+        :param export_filename: Optional, if a filename is provided a CSV file will be saved
+             as a result of the read action containing measurement data. The filename will
+             be modified to include the wavelength used during measurement. If multiple
+             measurements are taken, then a file will be generated for each wavelength provided.
+
+        Example: If `export_filename="my_data"` and wavelengths 450 and 531 are used during
+        measurement, the output files will be "my_data_450.csv" and "my_data_531.csv".
+        """
+        return self._core.read(filename=export_filename)

opentrons/protocol_api/protocol_context.py

@@ -14,10 +14,15 @@ from typing import (
 
 from opentrons_shared_data.labware.types import LabwareDefinition
 from opentrons_shared_data.pipette.types import PipetteNameType
+from opentrons_shared_data.robot.types import RobotTypeEnum
 
 from opentrons.types import Mount, Location, DeckLocation, DeckSlotName, StagingSlotName
+from opentrons.config import feature_flags
 from opentrons.legacy_broker import LegacyBroker
-from opentrons.hardware_control.modules.types import MagneticBlockModel
+from opentrons.hardware_control.modules.types import (
+    MagneticBlockModel,
+    AbsorbanceReaderModel,
+)
 from opentrons.legacy_commands import protocol_commands as cmds, types as cmd_types
 from opentrons.legacy_commands.helpers import stringify_labware_movement_command
 from opentrons.legacy_commands.publisher import (
@@ -39,6 +44,7 @@ from opentrons.protocols.api_support.util import (
     RobotTypeError,
     UnsupportedAPIError,
 )
+from opentrons_shared_data.errors.exceptions import CommandPreconditionViolated
 
 from ._types import OffDeckType
 from .core.common import ModuleCore, LabwareCore, ProtocolCore
@@ -57,7 +63,7 @@ from .core.engine import ENGINE_CORE_API_VERSION
 from .core.legacy.legacy_protocol_core import LegacyProtocolCore
 
 from . import validation
-from ._liquid import Liquid
+from ._liquid import Liquid, LiquidClass
 from .disposal_locations import TrashBin, WasteChute
 from .deck import Deck
 from .instrument_context import InstrumentContext
@@ -205,8 +211,12 @@ class ProtocolContext(CommandPublisher):
         return self._api_version
 
     @property
-    @requires_version(2, 20)
+    @requires_version(2, 21)
     def robot(self) -> RobotContext:
+        """The :py:class:`.RobotContext` for the protocol.
+
+        :meta private:
+        """
         return self._robot
 
     @property
@@ -653,7 +663,6 @@ class ProtocolContext(CommandPublisher):
             if slot is not None
         }
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     @requires_version(2, 15)
     def move_labware(
         self,
@@ -704,6 +713,13 @@ class ProtocolContext(CommandPublisher):
                 f"Expected labware of type 'Labware' but got {type(labware)}."
             )
 
+        # Ensure that when moving to an absorbance reader than the lid is open
+        if isinstance(new_location, AbsorbanceReaderContext):
+            if new_location.is_lid_on():
+                raise CommandPreconditionViolated(
+                    f"Cannot move {labware.name} onto the Absorbance Reader Module when its lid is closed."
+                )
+
         location: Union[
             ModuleCore,
             LabwareCore,
@@ -827,6 +843,12 @@ class ProtocolContext(CommandPublisher):
                 until_version="2.15",
                 current_version=f"{self._api_version}",
             )
+        if isinstance(
+            requested_model, AbsorbanceReaderModel
+        ) and self._api_version < APIVersion(2, 21):
+            raise APIVersionError(
+                f"Module of type {module_name} is only available in versions 2.21 and above."
+            )
 
         deck_slot = (
             None
@@ -1264,6 +1286,18 @@ class ProtocolContext(CommandPublisher):
             display_color=display_color,
         )
 
+    def define_liquid_class(
+        self,
+        name: str,
+    ) -> LiquidClass:
+        """Define a liquid class for use in the protocol."""
+        if feature_flags.allow_liquid_classes(
+            robot_type=RobotTypeEnum.robot_literal_to_enum(self._core.robot_type)
+        ):
+            return self._core.define_liquid_class(name=name)
+        else:
+            raise NotImplementedError("This method is not implemented.")
+
     @property
     @requires_version(2, 5)
     def rail_lights_on(self) -> bool:

opentrons/protocol_api/validation.py

@@ -18,7 +18,7 @@ from opentrons_shared_data.labware.labware_definition import LabwareRole
 from opentrons_shared_data.pipette.types import PipetteNameType
 from opentrons_shared_data.robot.types import RobotType
 
-from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.types import APIVersion, ThermocyclerStep
 from opentrons.protocols.api_support.util import APIVersionError
 from opentrons.protocols.models import LabwareDefinition
 from opentrons.types import Mount, DeckSlotName, StagingSlotName, Location
@@ -30,7 +30,6 @@ from opentrons.hardware_control.modules.types import (
     HeaterShakerModuleModel,
     MagneticBlockModel,
     AbsorbanceReaderModel,
-    ThermocyclerStep,
 )
 
 from .disposal_locations import TrashBin, WasteChute
@@ -436,10 +435,13 @@ class LocationTypeError(TypeError):
     """Error representing that the location supplied is of different expected type."""
 
 
+ValidTarget = Union[WellTarget, PointTarget, TrashBin, WasteChute]
+
+
 def validate_location(
     location: Union[Location, Well, TrashBin, WasteChute, None],
     last_location: Optional[Location],
-) -> Union[WellTarget, PointTarget, TrashBin, WasteChute]:
+) -> ValidTarget:
     """Validate a given location for a liquid handling command.
 
     Args:

opentrons/protocol_engine/__init__.py

@@ -18,15 +18,10 @@ from .commands import (
     CommandType,
     CommandIntent,
 )
-from .state import (
-    State,
-    StateView,
-    StateSummary,
-    CommandSlice,
-    CommandPointer,
-    Config,
-    CommandErrorSlice,
-)
+from .state.state import State, StateView
+from .state.state_summary import StateSummary
+from .state.commands import CommandSlice, CommandErrorSlice, CommandPointer
+from .state.config import Config
 from .plugins import AbstractPlugin
 
 from .types import (
@@ -52,9 +47,12 @@ from .types import (
     LoadedPipette,
     MotorAxis,
     WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
     DropTipWellLocation,
     WellOrigin,
     DropTipWellOrigin,
+    PickUpTipWellOrigin,
     WellOffset,
     ModuleModel,
     ModuleDefinition,
@@ -114,9 +112,12 @@ __all__ = [
     "LoadedPipette",
     "MotorAxis",
     "WellLocation",
+    "LiquidHandlingWellLocation",
+    "PickUpTipWellLocation",
     "DropTipWellLocation",
     "WellOrigin",
     "DropTipWellOrigin",
+    "PickUpTipWellOrigin",
     "WellOffset",
     "ModuleModel",
     "ModuleDefinition",

opentrons/protocol_engine/actions/__init__.py

@@ -28,7 +28,9 @@ from .actions import (
     DoorChangeAction,
     ResetTipsAction,
     SetPipetteMovementSpeedAction,
+    AddAbsorbanceReaderLidAction,
 )
+from .get_state_update import get_state_updates
 
 __all__ = [
     # action pipeline interface
@@ -56,7 +58,10 @@ __all__ = [
     "DoorChangeAction",
     "ResetTipsAction",
     "SetPipetteMovementSpeedAction",
+    "AddAbsorbanceReaderLidAction",
     # action payload values
     "PauseSource",
     "FinishErrorDetails",
+    # helper functions
+    "get_state_updates",
 ]