opentrons 8.6.0__py3-none-any.whl

opentrons/motion_planning/errors.py

@@ -0,0 +1,35 @@
+"""Movement planning errors."""
+from opentrons.types import Point
+
+
+class MotionPlanningError(Exception):
+    """Sub-class for errors from the movement_planning module."""
+
+    def __init__(
+        self,
+        origin: Point,
+        dest: Point,
+        clearance: float,
+        min_travel_z: float,
+        max_travel_z: float,
+        message: str,
+    ) -> None:
+        """Initialize an error with properties of the planned motion."""
+        super().__init__(message)
+        self.origin = origin
+        self.dest = dest
+        self.clearance = clearance
+        self.min_travel_z = min_travel_z
+        self.max_travel_z = max_travel_z
+
+
+class DestinationOutOfBoundsError(MotionPlanningError, ValueError):
+    """An error raised when a requested destination is out of bounds."""
+
+    pass
+
+
+class ArcOutOfBoundsError(MotionPlanningError, ValueError):
+    """An error raised when a calculated movement arc is out of bounds."""
+
+    pass

opentrons/motion_planning/types.py

@@ -0,0 +1,42 @@
+"""Motion planning base interfaces."""
+from dataclasses import dataclass
+from enum import Enum, auto as auto_enum_value
+from typing import Optional
+from typing_extensions import final
+
+from opentrons.types import Point
+from opentrons.hardware_control.types import CriticalPoint
+
+
+@dataclass(frozen=True)
+@final
+class Waypoint:
+    """Motion waypoint with position and optional pipette critical point."""
+
+    position: Point
+    critical_point: Optional[CriticalPoint] = None
+
+
+@final
+class MoveType(Enum):
+    """Arc or direct movement type.
+
+    - GENERAL_ARC: an arc movement between two unrelated locations
+    - IN_LABWARE_ARC: an arc movement between two locations in the same labware
+    - DIRECT: a direct movement between two locations
+    """
+
+    GENERAL_ARC = auto_enum_value()
+    IN_LABWARE_ARC = auto_enum_value()
+    DIRECT = auto_enum_value()
+
+
+@dataclass(frozen=True)
+@final
+class GripperMovementWaypointsWithJawStatus:
+    """Gripper motion waypoint with expected jaw status while moving to the waypoint."""
+
+    position: Point
+    jaw_open: bool
+    dropping: bool
+    """This flag should only be set to True if this waypoint involves dropping a piece of labware."""

opentrons/motion_planning/waypoints.py

@@ -0,0 +1,218 @@
+"""Waypoint planning."""
+from typing import List, Optional, Sequence, Tuple
+from typing_extensions import Final
+
+from opentrons.types import Point
+from opentrons.hardware_control.types import CriticalPoint
+
+from .types import Waypoint, MoveType, GripperMovementWaypointsWithJawStatus
+from .errors import DestinationOutOfBoundsError, ArcOutOfBoundsError
+from ..protocol_engine.types import LabwareMovementOffsetData
+
+DEFAULT_GENERAL_ARC_Z_MARGIN: Final[float] = 10.0
+DEFAULT_IN_LABWARE_ARC_Z_MARGIN: Final[float] = 5.0
+MINIMUM_Z_MARGIN: Final[float] = 1.0
+
+
+def get_waypoints(
+    origin: Point,
+    dest: Point,
+    *,
+    max_travel_z: float,
+    min_travel_z: float,
+    move_type: MoveType = MoveType.GENERAL_ARC,
+    xy_waypoints: Sequence[Tuple[float, float]] = (),
+    origin_cp: Optional[CriticalPoint] = None,
+    dest_cp: Optional[CriticalPoint] = None,
+) -> List[Waypoint]:
+    """Get waypoints between an origin point and a destination point.
+
+    Given a move type and Z limits, which should be calculated according to
+    deck / labware / pipette geometry, creates waypoints with proper
+    z-clearances to move between `origin` and `dest`.
+
+    :param origin: The start point of the move.
+    :param dest: The end point of the move.
+    :param max_travel_z: The maximum allowed travel height of an arc move.
+    :param min_travel_z: The minimum allowed travel height of an arc move.
+    :param move_type: Direct move, in-labware arc, or general arc move type.
+    :param xy_waypoints: Extra XY destination waypoints to place in the path.
+    :param origin_cp: Pipette critical point override for origin waypoints.
+    :param dest_cp: Pipette critical point override for destination waypoints.
+
+    :returns: A list of :py:class:`.Waypoint` locations to move through.
+    """
+    # NOTE(mm, 2022-06-22):
+    # This function is used by v6+ JSON protocols and v3+
+    # Python API protocols, but not v2 Python API protocols.
+    #
+    # To experiment with using this module in PAPIv2,
+    # flip the default of `use_experimental_waypoint_planning` to True
+    # in opentrons.protocols.geometry.planning.plan_moves
+    dest_waypoint = Waypoint(dest, dest_cp)
+    waypoints: List[Waypoint] = []
+
+    # a direct move can ignore all arc and waypoint planning
+    if move_type == MoveType.DIRECT:
+        # TODO(mm, 2022-06-17): This will not raise an out-of-bounds error
+        # even if the destination is far out of bounds. A protocol can run into this by
+        # doing a direct move to bad coordinates. Should we raise in that case?
+        return [dest_waypoint]
+
+    # ensure destination is not out of bounds
+    if dest.z + MINIMUM_Z_MARGIN > max_travel_z:
+        raise DestinationOutOfBoundsError(
+            origin=origin,
+            dest=dest,
+            clearance=MINIMUM_Z_MARGIN,
+            min_travel_z=min_travel_z,
+            max_travel_z=max_travel_z,
+            message="Destination out of bounds in the Z-axis",
+        )
+
+    # ensure that the passed in min_travel_z and max_travel_z are compatible
+    if min_travel_z + MINIMUM_Z_MARGIN > max_travel_z:
+        raise ArcOutOfBoundsError(
+            origin=origin,
+            dest=dest,
+            clearance=MINIMUM_Z_MARGIN,
+            min_travel_z=min_travel_z,
+            max_travel_z=max_travel_z,
+            message="Arc out of bounds in the Z-axis",
+        )
+
+    # set the z clearance according to the arc type
+    travel_z_margin = (
+        DEFAULT_GENERAL_ARC_Z_MARGIN
+        if move_type == MoveType.GENERAL_ARC
+        else DEFAULT_IN_LABWARE_ARC_Z_MARGIN
+    )
+
+    # set the actual travel z according to:
+    # use the max of min_travel_z with clearance or dest height
+    # if either of those exceed max_travel_z, just use max_travel_z
+    # if max_travel_z does not provide enough clearance, check above would
+    # raise an ArcOutOfBoundsError
+    # if origin.z is higher than the selected travel z, travel at origin.z instead
+    travel_z = max(
+        min(max_travel_z, max(min_travel_z + travel_z_margin, dest.z)),
+        origin.z,
+    )
+
+    # if origin.z isn't the travel height: add waypoint to move to origin.z
+    if travel_z > origin.z:
+        waypoints.append(Waypoint(origin._replace(z=travel_z), origin_cp))
+
+    # add any additional waypoints along with critical point blending
+    # see https://github.com/Opentrons/opentrons/pull/5662
+    # TODO(mc, 2020-11-05): if any critical point transitions can move in the
+    # Z axis, an extra waypoint for that transition will be needed
+    for x, y in xy_waypoints:
+        waypoints.append(Waypoint(Point(x=x, y=y, z=travel_z), dest_cp))
+
+    # if dest.z isn't the travel height: add waypoint to move to dest.z
+    # TODO(mc, 2020-11-05): if any critical point transitions can move in the
+    # Z axis, this conditional will need to be revised
+    if travel_z > dest.z:
+        waypoints.append(Waypoint(dest._replace(z=travel_z), dest_cp))
+
+    waypoints.append(dest_waypoint)
+
+    return waypoints
+
+
+def get_gripper_labware_movement_waypoints(
+    from_labware_center: Point,
+    to_labware_center: Point,
+    gripper_home_z: float,
+    offset_data: LabwareMovementOffsetData,
+    post_drop_slide_offset: Optional[Point],
+    gripper_home_z_offset: Optional[float] = None,
+) -> List[GripperMovementWaypointsWithJawStatus]:
+    """Get waypoints for moving labware using a gripper."""
+    pick_up_offset = offset_data.pickUpOffset
+    drop_offset = offset_data.dropOffset
+
+    pick_up_location = from_labware_center + Point(
+        pick_up_offset.x, pick_up_offset.y, pick_up_offset.z
+    )
+    drop_location = to_labware_center + Point(
+        drop_offset.x, drop_offset.y, drop_offset.z
+    )
+
+    gripper_max_z_home = gripper_home_z - (gripper_home_z_offset or 0)
+
+    post_drop_home_pos = Point(drop_location.x, drop_location.y, gripper_home_z)
+
+    waypoints_with_jaw_status = [
+        GripperMovementWaypointsWithJawStatus(
+            position=Point(pick_up_location.x, pick_up_location.y, gripper_home_z),
+            jaw_open=False,
+            dropping=False,
+        ),
+        GripperMovementWaypointsWithJawStatus(
+            position=pick_up_location, jaw_open=True, dropping=False
+        ),
+        # Gripper grips the labware here
+        GripperMovementWaypointsWithJawStatus(
+            position=Point(pick_up_location.x, pick_up_location.y, gripper_max_z_home),
+            jaw_open=False,
+            dropping=False,
+        ),
+        GripperMovementWaypointsWithJawStatus(
+            position=Point(drop_location.x, drop_location.y, gripper_max_z_home),
+            jaw_open=False,
+            dropping=False,
+        ),
+        GripperMovementWaypointsWithJawStatus(
+            position=drop_location, jaw_open=False, dropping=False
+        ),
+        # Gripper ungrips here
+        GripperMovementWaypointsWithJawStatus(
+            position=post_drop_home_pos,
+            jaw_open=True,
+            dropping=True,
+        ),
+    ]
+    if post_drop_slide_offset is not None:
+        # IF it is specified, add one more step after homing the gripper
+        waypoints_with_jaw_status.append(
+            GripperMovementWaypointsWithJawStatus(
+                position=post_drop_home_pos + post_drop_slide_offset,
+                jaw_open=True,
+                dropping=False,
+            )
+        )
+    return waypoints_with_jaw_status
+
+
+def get_gripper_labware_placement_waypoints(
+    to_labware_center: Point,
+    gripper_home_z: float,
+    drop_offset: Optional[Point],
+) -> List[GripperMovementWaypointsWithJawStatus]:
+    """Get waypoints for placing labware using a gripper."""
+    drop_offset = drop_offset or Point()
+
+    drop_location = to_labware_center + Point(
+        drop_offset.x, drop_offset.y, drop_offset.z
+    )
+
+    post_drop_home_pos = Point(drop_location.x, drop_location.y, gripper_home_z)
+
+    return [
+        GripperMovementWaypointsWithJawStatus(
+            position=Point(drop_location.x, drop_location.y, gripper_home_z),
+            jaw_open=False,
+            dropping=False,
+        ),
+        GripperMovementWaypointsWithJawStatus(
+            position=drop_location, jaw_open=False, dropping=False
+        ),
+        # Gripper ungrips here
+        GripperMovementWaypointsWithJawStatus(
+            position=post_drop_home_pos,
+            jaw_open=True,
+            dropping=True,
+        ),
+    ]

opentrons/ordered_set.py

@@ -0,0 +1,138 @@
+"""A set that preserves the order in which elements are added."""
+
+from __future__ import annotations
+
+from typing import (
+    Dict,
+    Generic,
+    Hashable,
+    Iterable,
+    Iterator,
+    Set,
+    TypeVar,
+    Union,
+    overload,
+)
+from typing_extensions import Literal
+
+
+_SetElementT = TypeVar("_SetElementT", bound=Hashable)
+
+_DefaultValueT = TypeVar("_DefaultValueT")
+
+
+class _NOT_SPECIFIED:
+    """Value not specified sentinel."""
+
+
+# Implemented as a standalone class for clarity.
+# If this proves insufficient, we can get many methods for free
+# by subclassing collections.abc.MutableSet.
+class OrderedSet(Generic[_SetElementT]):
+    """A set that preserves the order in which elements are added.
+
+    Args:
+        source_iterable: An ordered iterable of initial elements.
+    """
+
+    def __init__(self, source_iterable: Iterable[_SetElementT] = tuple()) -> None:
+        self._elements: Dict[_SetElementT, Literal[True]] = {}
+
+        for element in source_iterable:
+            self.add(element)
+
+    def add(self, element: _SetElementT) -> None:
+        """Add ``element`` to the set.
+
+        If ``element`` is already in the set, it is not added again,
+        and its existing position in the set is retained.
+        """
+        self._elements[element] = True
+
+    def remove(self, element: _SetElementT) -> None:
+        """Remove ``element`` from the set.
+
+        Raises:
+            KeyError: If ``element`` is not in the set.
+        """
+        del self._elements[element]
+
+    def discard(self, element: _SetElementT) -> None:
+        """Remove ``element`` from the set, if it is present."""
+        try:
+            self.remove(element)
+        except KeyError:
+            pass
+
+    def clear(self) -> None:
+        """Remove all elements from the set."""
+        self._elements.clear()
+
+    @overload
+    def head(self) -> _SetElementT:
+        ...
+
+    @overload
+    def head(
+        self, default_value: _DefaultValueT
+    ) -> Union[_SetElementT, _DefaultValueT]:
+        ...
+
+    def head(
+        self, default_value: Union[_DefaultValueT, _NOT_SPECIFIED] = _NOT_SPECIFIED()
+    ) -> Union[_SetElementT, _DefaultValueT]:
+        """Get the head (oldest-added element) of the set.
+
+        Args:
+            default_value: A value to return if set is empty.
+
+        Returns:
+            The head of the set, or the default value, if specified.
+
+        Raises:
+            IndexError: set is empty and default was not specified.
+        """
+        try:
+            return next(iter(self._elements))
+        except StopIteration:
+            if isinstance(default_value, _NOT_SPECIFIED):
+                raise IndexError("Set is empty") from None
+            else:
+                return default_value
+
+    def __iter__(self) -> Iterator[_SetElementT]:
+        """Enable iteration over all elements in the set.
+
+        Elements are returned in the order they were added, oldest first.
+        """
+        return iter(self._elements)
+
+    def __len__(self) -> int:
+        """Return the number of unique elements added to the set."""
+        return len(self._elements)
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether this set is equal to another object.
+
+        True if the other object is also an ordered set,
+        and it contains the same elements in the same order.
+        """
+        if isinstance(other, OrderedSet):
+            return list(self) == list(other)
+        else:
+            return False
+
+    def __sub__(
+        self, other: Union[OrderedSet[_SetElementT], Set[_SetElementT]]
+    ) -> OrderedSet[_SetElementT]:
+        """Return this set, without any elements that appear in `other`.
+
+        The elements that aren't removed retain their original relative order.
+        """
+        return OrderedSet(e for e in self if e not in other)
+
+    def __repr__(self) -> str:  # noqa: D105
+        # Use repr() on the keys view in case it's super long and Python is smart
+        # enough to abbreviate it.
+        elements_str = repr(self._elements.keys())
+        return f"OrderedSet({elements_str})"

opentrons/protocol_api/__init__.py

@@ -0,0 +1,105 @@
+"""protocol_api: The user-facing API for Opentrons OT-2 and Opentrons Flex protocols.
+
+This package defines classes and functions for Python protocols to
+control an OT-2 or Flex robot.
+
+"""
+
+from opentrons.protocols.api_support.definitions import (
+    MAX_SUPPORTED_VERSION,
+    MIN_SUPPORTED_VERSION,
+    MIN_SUPPORTED_VERSION_FOR_FLEX,
+)
+from opentrons.protocols.parameters.exceptions import (
+    RuntimeParameterRequired as RuntimeParameterRequiredError,
+)
+from opentrons.protocols.parameters.csv_parameter_interface import CSVParameter
+
+from .protocol_context import ProtocolContext
+from .deck import Deck
+from .robot_context import RobotContext
+from .instrument_context import InstrumentContext
+from .labware import Labware, Well
+from .module_contexts import (
+    ModuleContext,
+    ThermocyclerContext,
+    MagneticModuleContext,
+    TemperatureModuleContext,
+    HeaterShakerContext,
+    MagneticBlockContext,
+    AbsorbanceReaderContext,
+    FlexStackerContext,
+)
+from .disposal_locations import TrashBin, WasteChute
+from ._liquid import Liquid, LiquidClass
+from ._types import (
+    OFF_DECK,
+    PLUNGER_BLOWOUT,
+    PLUNGER_TOP,
+    PLUNGER_BOTTOM,
+    PLUNGER_DROPTIP,
+    ASPIRATE_ACTION,
+    DISPENSE_ACTION,
+    BLOWOUT_ACTION,
+)
+from ._nozzle_layout import (
+    COLUMN,
+    PARTIAL_COLUMN,
+    SINGLE,
+    ROW,
+    ALL,
+)
+from ._parameters import Parameters
+from ._parameter_context import ParameterContext
+
+from .create_protocol_context import (
+    create_protocol_context,
+    ProtocolEngineCoreRequiredError,
+)
+
+__all__ = [
+    "MAX_SUPPORTED_VERSION",
+    "MIN_SUPPORTED_VERSION",
+    "MIN_SUPPORTED_VERSION_FOR_FLEX",
+    "ProtocolContext",
+    "Deck",
+    "ModuleContext",
+    "RobotContext",
+    "InstrumentContext",
+    "TemperatureModuleContext",
+    "MagneticModuleContext",
+    "ThermocyclerContext",
+    "HeaterShakerContext",
+    "MagneticBlockContext",
+    "AbsorbanceReaderContext",
+    "FlexStackerContext",
+    "ParameterContext",
+    "Labware",
+    "TrashBin",
+    "WasteChute",
+    "Well",
+    "Liquid",
+    "LiquidClass",
+    "Parameters",
+    # Partial Tip types
+    "COLUMN",
+    "PARTIAL_COLUMN",
+    "SINGLE",
+    "ROW",
+    "ALL",
+    # Deck location types
+    "OFF_DECK",
+    # Pipette plunger types
+    "PLUNGER_BLOWOUT",
+    "PLUNGER_TOP",
+    "PLUNGER_BOTTOM",
+    "PLUNGER_DROPTIP",
+    "ASPIRATE_ACTION",
+    "DISPENSE_ACTION",
+    "BLOWOUT_ACTION",
+    "RuntimeParameterRequiredError",
+    "CSVParameter",
+    # For internal Opentrons use only:
+    "create_protocol_context",
+    "ProtocolEngineCoreRequiredError",
+]

opentrons/protocol_api/_liquid.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Dict, Union, TYPE_CHECKING, Tuple
+
+from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    LiquidClassSchemaV1,
+)
+
+from opentrons.protocols.advanced_control.transfers.common import (
+    NoLiquidClassPropertyError,
+)
+
+from ._liquid_properties import (
+    TransferProperties,
+    build_transfer_properties,
+)
+
+if TYPE_CHECKING:
+    from . import InstrumentContext, Labware
+
+
+@dataclass(frozen=True)
+class Liquid:
+    """A liquid to load into a well.
+
+    Attributes:
+        name: A human-readable name for the liquid.
+        description: An optional description.
+        display_color: An optional display color for the liquid.
+
+    .. versionadded:: 2.14
+    """
+
+    _id: str
+    name: str
+    description: Optional[str]
+    display_color: Optional[str]
+
+
+@dataclass
+class LiquidClass:
+    """A data class that contains properties of a specific class of liquids."""
+
+    _name: str
+    _display_name: str
+    _by_pipette_setting: Dict[str, Dict[str, TransferProperties]]
+
+    @classmethod
+    def create(cls, liquid_class_definition: LiquidClassSchemaV1) -> "LiquidClass":
+        """Liquid class factory method."""
+
+        by_pipette_settings: Dict[str, Dict[str, TransferProperties]] = {}
+        for by_pipette in liquid_class_definition.byPipette:
+            tip_settings: Dict[str, TransferProperties] = {}
+            for tip_type in by_pipette.byTipType:
+                tip_settings[tip_type.tiprack] = build_transfer_properties(tip_type)
+            by_pipette_settings[by_pipette.pipetteModel] = tip_settings
+
+        return cls(
+            _name=liquid_class_definition.liquidClassName,
+            _display_name=liquid_class_definition.displayName,
+            _by_pipette_setting=by_pipette_settings,
+        )
+
+    @classmethod
+    def create_from(
+        cls,
+        name: str,
+        display_name: str,
+        by_pipette_setting: Dict[str, Dict[str, TransferProperties]],
+    ) -> "LiquidClass":
+        """Create a liquid class from the passed in args."""
+        return cls(
+            _name=name,
+            _display_name=display_name,
+            _by_pipette_setting=by_pipette_setting,
+        )
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def display_name(self) -> str:
+        return self._display_name
+
+    def update_for(
+        self,
+        pipette: Union[str, InstrumentContext],
+        tip_rack: Union[str, Labware],
+        transfer_properties: TransferProperties,
+    ) -> None:
+        """Update the transfer properties for the given pipette and tip combo.
+
+        If an entry does not exist, it will be created.
+        """
+        pipette_name, tiprack_uri = self._get_pipette_and_tiprack_names(
+            pipette, tip_rack
+        )
+        try:
+            self._by_pipette_setting[pipette_name].update(
+                {tiprack_uri: transfer_properties}
+            )
+        except KeyError:
+            self._by_pipette_setting[pipette_name] = {tiprack_uri: transfer_properties}
+
+    def get_for(
+        self, pipette: Union[str, InstrumentContext], tip_rack: Union[str, Labware]
+    ) -> TransferProperties:
+        """Get liquid class transfer properties for the specified pipette and tip."""
+        pipette_name, tiprack_uri = self._get_pipette_and_tiprack_names(
+            pipette, tip_rack
+        )
+
+        try:
+            settings_for_pipette = self._by_pipette_setting[pipette_name]
+        except KeyError:
+            raise NoLiquidClassPropertyError(
+                f"No properties found for {pipette_name} in {self._name} liquid class"
+            )
+        try:
+            transfer_properties = settings_for_pipette[tiprack_uri]
+        except KeyError:
+            raise NoLiquidClassPropertyError(
+                f"No properties found for {tiprack_uri} for {pipette_name} in {self._name} liquid class"
+            )
+        return transfer_properties
+
+    @staticmethod
+    def _get_pipette_and_tiprack_names(
+        pipette: Union[str, InstrumentContext],
+        tip_rack: Union[str, Labware],
+    ) -> Tuple[str, str]:
+        """Return the pipette and tip rack name strings from the given pipette and tip rack."""
+        from . import InstrumentContext, Labware
+
+        if isinstance(pipette, InstrumentContext):
+            pipette_name = pipette.name
+        elif isinstance(pipette, str):
+            pipette_name = pipette
+        else:
+            raise ValueError(
+                f"{pipette} should either be an InstrumentContext object"
+                f" or a pipette name string."
+            )
+
+        if isinstance(tip_rack, Labware):
+            tiprack_uri = tip_rack.uri
+        elif isinstance(tip_rack, str):
+            tiprack_uri = tip_rack
+        else:
+            raise ValueError(
+                f"{tip_rack} should either be a tiprack Labware object"
+                f" or a tiprack URI string."
+            )
+        return pipette_name, tiprack_uri