opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_api/core/labware.py

@@ -0,0 +1,151 @@
+"""The interface that implements InstrumentContext."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Generic, List, NamedTuple, Optional, TypeVar, Dict
+
+from opentrons_shared_data.labware.types import (
+    LabwareUri,
+    LabwareParameters2,
+    LabwareParameters3,
+    LabwareDefinition as LabwareDefinitionDict,
+)
+
+from opentrons.types import DeckSlotName, Point, NozzleMapInterface
+from .._liquid import Liquid
+
+from .well import WellCoreType
+
+
+_LabwareParametersDict = LabwareParameters2 | LabwareParameters3
+
+
+class LabwareLoadParams(NamedTuple):
+    """Unique load parameters of a labware."""
+
+    namespace: str
+    load_name: str
+    version: int
+
+    def as_uri(self) -> LabwareUri:
+        """Get the labware's definition URI from the load parameters."""
+        return LabwareUri(f"{self.namespace}/{self.load_name}/{self.version}")
+
+    @classmethod
+    def from_uri(cls, uri: LabwareUri) -> LabwareLoadParams:
+        namespace, load_name, version_str = uri.split("/")
+        return cls(namespace, load_name, int(version_str))
+
+
+class AbstractLabware(ABC, Generic[WellCoreType]):
+    """Labware implementation core interface."""
+
+    @property
+    @abstractmethod
+    def load_name(self) -> str:
+        """Get the labware's load name."""
+
+    @property
+    @abstractmethod
+    def highest_z(self) -> float:
+        """Get the Z coordinate of the labware's highest point"""
+
+    @abstractmethod
+    def get_uri(self) -> str:
+        """Get the URI string string of the labware's definition.
+
+        The URI is unique for a given namespace, load name, and definition version.
+        """
+
+    @abstractmethod
+    def get_load_params(self) -> LabwareLoadParams:
+        ...
+
+    @abstractmethod
+    def get_display_name(self) -> str:
+        """Get a display name for the labware, falling back to the definition."""
+
+    @abstractmethod
+    def get_user_display_name(self) -> Optional[str]:
+        """Get the user-specified display name of the labware, if set."""
+
+    @abstractmethod
+    def get_name(self) -> str:
+        ...
+
+    @abstractmethod
+    def get_definition(self) -> LabwareDefinitionDict:
+        """Get the labware's definition as a plain dictionary."""
+
+    @abstractmethod
+    def get_parameters(self) -> _LabwareParametersDict:
+        """Get the labware's definition's `parameters` field as a plain dictionary."""
+
+    @abstractmethod
+    def get_quirks(self) -> List[str]:
+        ...
+
+    @abstractmethod
+    def set_calibration(self, delta: Point) -> None:
+        ...
+
+    @abstractmethod
+    def get_calibrated_offset(self) -> Point:
+        ...
+
+    @abstractmethod
+    def is_tip_rack(self) -> bool:
+        """Whether the labware is a tip rack."""
+
+    @abstractmethod
+    def is_adapter(self) -> bool:
+        """Whether the labware is an adapter."""
+
+    @abstractmethod
+    def is_lid(self) -> bool:
+        """Whether the labware is a lid."""
+
+    @abstractmethod
+    def is_fixed_trash(self) -> bool:
+        """Whether the labware is a fixed trash."""
+
+    @abstractmethod
+    def get_tip_length(self) -> float:
+        ...
+
+    @abstractmethod
+    def reset_tips(self) -> None:
+        ...
+
+    @abstractmethod
+    def get_next_tip(
+        self,
+        num_tips: int,
+        starting_tip: Optional[WellCoreType],
+        nozzle_map: Optional[NozzleMapInterface],
+    ) -> Optional[str]:
+        """Get the name of the next available tip(s) in the rack, if available."""
+
+    @abstractmethod
+    def get_well_columns(self) -> List[List[str]]:
+        """Get the all well names, organized by column, from the labware's definition."""
+
+    @abstractmethod
+    def get_well_core(self, well_name: str) -> WellCoreType:
+        """Get a well core interface to a given well in this labware."""
+
+    @abstractmethod
+    def get_deck_slot(self) -> Optional[DeckSlotName]:
+        """Get the deck slot the labware or its parent is in, if any."""
+
+    @abstractmethod
+    def load_liquid(self, volumes: Dict[str, float], liquid: Liquid) -> None:
+        """Load liquid into wells of the labware."""
+
+    @abstractmethod
+    def load_empty(self, wells: List[str]) -> None:
+        """Mark wells of the labware as empty."""
+
+
+LabwareCoreType = TypeVar("LabwareCoreType", bound=AbstractLabware[Any])

opentrons/protocol_api/core/legacy/__init__.py

@@ -0,0 +1,11 @@
+"""The Protocol API v2 context implementation package."""
+# TODO(mc, 2022-08.22): uncomment when import cycles can be resolved
+# from .legacy_protocol_core import LegacyProtocolCore
+# from .legacy_instrument_core import LegacyInstrumentCore
+# from .legacy_labware_core.py import LegacyLabwareCore
+
+# __all__ = [
+#     "LegacyProtocolCore",
+#     "LegacyInstrumentCore",
+#     "LegacyLabwareCore",
+# ]

opentrons/protocol_api/core/legacy/_labware_geometry.py

@@ -0,0 +1,37 @@
+from opentrons.types import Location, Point
+from opentrons_shared_data.labware.types import LabwareDefinition2
+
+
+class LabwareGeometry:
+    """Convenience interface for accessing geometry properties of a labware."""
+
+    def __init__(self, definition: LabwareDefinition2, parent: Location):
+        """Constructor"""
+        self._parent = parent
+        offset = definition["cornerOffsetFromSlot"]
+        self._offset = Point(offset["x"], offset["y"], offset["z"]) + parent.point
+
+        dimensions = definition["dimensions"]
+        self._x_dimension = dimensions["xDimension"]
+        self._y_dimension = dimensions["yDimension"]
+        self._z_dimension = dimensions["zDimension"]
+
+    @property
+    def parent(self) -> Location:
+        return self._parent
+
+    @property
+    def offset(self) -> Point:
+        return self._offset
+
+    @property
+    def x_dimension(self) -> float:
+        return self._x_dimension
+
+    @property
+    def y_dimension(self) -> float:
+        return self._y_dimension
+
+    @property
+    def z_dimension(self) -> float:
+        return self._z_dimension

opentrons/protocol_api/core/legacy/deck.py

@@ -0,0 +1,369 @@
+# NOTE(mc, 2022-12-05): this module is deprecated;
+# do not add to it unless necessary and do not use in new code
+import functools
+import logging
+from collections import UserDict
+from typing import Dict, Optional, List, Union, Mapping
+from typing_extensions import Protocol, Final
+
+from opentrons_shared_data.deck import load as load_deck
+
+from opentrons_shared_data.deck.types import SlotDefV3
+from opentrons_shared_data.labware.types import LabwareUri
+
+from opentrons.hardware_control.modules.types import ModuleType
+from opentrons.motion_planning import deck_conflict
+from opentrons.protocols.api_support.labware_like import LabwareLike
+from opentrons.types import (
+    DeckLocation,
+    Location,
+    Mount,
+    Point,
+    DeckSlotName,
+    StagingSlotName,
+)
+
+from opentrons.protocol_api.core.labware import AbstractLabware
+from opentrons.protocol_api.deck import CalibrationPosition
+from opentrons.protocol_api.labware import load as load_lw, Labware
+
+from .legacy_labware_core import LegacyLabwareCore
+from .module_geometry import ModuleGeometry, HeaterShakerGeometry, ThermocyclerGeometry
+
+
+_log = logging.getLogger(__name__)
+
+
+# Amount of slots in a single deck row
+ROW_LENGTH = 3
+FIXED_TRASH_ID = "fixedTrash"
+
+
+DEFAULT_LEGACY_DECK_DEFINITION_VERSION: Final = 3
+
+
+class DeckItem(Protocol):
+    @property
+    def highest_z(self) -> float:
+        ...
+
+    @property
+    def load_name(self) -> str:
+        ...
+
+
+class Deck(UserDict):  # type: ignore[type-arg]
+    data: Dict[int, Optional[DeckItem]]
+
+    def __init__(self, deck_type: str) -> None:
+        super().__init__()
+        self._definition = load_deck(
+            name=deck_type, version=DEFAULT_LEGACY_DECK_DEFINITION_VERSION
+        )
+        self._positions = {}
+        for slot in self._definition["locations"]["orderedSlots"]:
+            self.data[int(slot["id"])] = None
+            self._positions[int(slot["id"])] = Point(*slot["position"])
+        self._highest_z = 0.0
+        self._load_fixtures()
+        self._thermocycler_present = False
+
+    def _load_fixtures(self) -> None:
+        for f in self._definition["locations"]["fixtures"]:
+            slot_name = self._check_name(f["slot"])  # type: ignore
+            # TODO(mc, 2022-06-15): this loads the fixed trash as an instance of
+            # `opentrons.protocol_api.labware.Labware`
+            # However, all other labware will be added to the `Deck` as instances of
+            # `opentrons.protocol_api.core.labware.AbstractLabware`
+            # And modules will be added as instances of
+            # `opentrons.protocols.geometry.module_geometry.ModuleGeometry`
+            # This mix of public and private interfaces as members of a public
+            # `Deck` interface is confusing and should be resolved.
+            # If `Deck` is public, all items in a `Deck` should be
+            # instances of other public APIs.
+            loaded_f = load_lw(
+                f["labware"], self.position_for(slot_name)  # type: ignore
+            )
+            self.__setitem__(slot_name, loaded_f)
+
+    @staticmethod
+    @functools.lru_cache(20)
+    def _assure_int(key: object) -> int:
+        if isinstance(key, str):
+            return int(key)
+        elif isinstance(key, int):
+            return key
+        else:
+            raise TypeError(type(key))
+
+    def _check_name(self, key: object) -> int:
+        should_raise = False
+        try:
+            key_int = Deck._assure_int(key)
+        except Exception:
+            _log.exception("Bad slot name: {}".format(key))
+            should_raise = True
+        should_raise = should_raise or key_int not in self.data
+        if should_raise:
+            raise ValueError("Unknown slot: {}".format(key))
+        else:
+            return key_int
+
+    @staticmethod
+    def _map_to_conflict_checker_item(item: DeckItem) -> deck_conflict.DeckItem:
+        name_for_errors = item.load_name
+
+        # We have to account for both Labware and AbstractLabware because this class
+        # inappropriately contains both internal and customer-facing types.
+        # See todo comment in self._load_fixtures().
+        if isinstance(item, Labware):
+            is_fixed_trash = "fixedTrash" in item.quirks
+            return deck_conflict.Labware(
+                highest_z=item.highest_z,
+                name_for_errors=name_for_errors,
+                # TODO(mm, 2023-02-16): Refactor item.uri to return LabwareUri.
+                uri=LabwareUri(item.uri),
+                is_fixed_trash=is_fixed_trash,
+            )
+
+        elif isinstance(item, AbstractLabware):
+            is_fixed_trash = "fixedTrash" in item.get_quirks()
+            return deck_conflict.Labware(
+                highest_z=item.highest_z,
+                name_for_errors=name_for_errors,
+                # TODO(mm, 2023-02-16): Refactor item.uri to return LabwareUri.
+                uri=LabwareUri(item.get_uri()),
+                is_fixed_trash=is_fixed_trash,
+            )
+
+        elif isinstance(item, HeaterShakerGeometry):
+            return deck_conflict.HeaterShakerModule(
+                highest_z_including_labware=item.highest_z,
+                name_for_errors=name_for_errors,
+            )
+
+        elif isinstance(item, ThermocyclerGeometry):
+            return deck_conflict.ThermocyclerModule(
+                highest_z_including_labware=item.highest_z,
+                name_for_errors=name_for_errors,
+                is_semi_configuration=item.is_semi_configuration,
+            )
+
+        elif isinstance(item, ModuleGeometry):
+            return deck_conflict.OtherModule(
+                highest_z_including_labware=item.highest_z,
+                name_for_errors=name_for_errors,
+            )
+
+        else:
+            assert False, f"Deck item {item} has an unknown type."
+
+    def __getitem__(self, key: DeckLocation) -> Optional[DeckItem]:
+        return self.data[self._check_name(key)]
+
+    def __delitem__(self, key: DeckLocation) -> None:
+        checked_key = self._check_name(key)
+        old = self.data[checked_key]
+        self.data[checked_key] = None
+        if old:
+            self.recalculate_high_z()
+            # Update the thermocycler present member
+            self._thermocycler_present = any(
+                isinstance(item, ThermocyclerGeometry) for item in self.data.values()
+            )
+
+    def __setitem__(self, key: DeckLocation, val: DeckItem) -> None:
+        slot_key_int = self._check_name(key)
+        existing_items: Mapping[
+            Union[DeckSlotName, StagingSlotName], deck_conflict.DeckItem
+        ] = {
+            DeckSlotName.from_primitive(slot): self._map_to_conflict_checker_item(item)
+            for slot, item in self.data.items()
+            if item is not None
+        }
+
+        # will raise DeckConflictError if items conflict
+        deck_conflict.check(
+            existing_items=existing_items,
+            new_location=DeckSlotName.from_primitive(slot_key_int),
+            new_item=self._map_to_conflict_checker_item(val),
+            robot_type=self._definition["robot"]["model"],
+        )
+
+        self.data[slot_key_int] = val
+        self.recalculate_high_z()
+        self._thermocycler_present = any(
+            isinstance(item, ThermocyclerGeometry) for item in self.data.values()
+        )
+
+    def __contains__(self, key: object) -> bool:
+        try:
+            key_int = self._check_name(key)
+        except ValueError:
+            return False
+        return key_int in self.data
+
+    def is_edge_move_unsafe(self, mount: Mount, target: "Labware") -> bool:
+        """
+        Check if slot next to target labware contains a module. Only relevant
+        depending on the mount you are using and the column you are moving
+        to inside of the labware.
+        """
+        slot = LabwareLike(target).first_parent()
+        if not slot:
+            return False
+        if mount is Mount.RIGHT:
+            other_labware = self.left_of(slot)
+        else:
+            other_labware = self.right_of(slot)
+
+        return isinstance(other_labware, ModuleGeometry)
+
+    def right_of(self, slot: str) -> Optional[DeckItem]:
+        if int(slot) % ROW_LENGTH == 0:
+            # We know we're at the right-most edge
+            # of the given row
+            return None
+        else:
+            idx = int(slot) + 1
+            return self[str(idx)]
+
+    def left_of(self, slot: str) -> Optional[DeckItem]:
+        if int(slot) - 1 % ROW_LENGTH == 0:
+            # We know we're at the left-most edge
+            # of the given row
+            return None
+        idx = int(slot) - 1
+        if idx < 1:
+            return None
+        return self[str(idx)]
+
+    def position_for(self, key: DeckLocation) -> Location:
+        key_int = self._check_name(key)
+        return Location(self._positions[key_int], str(key))
+
+    def recalculate_high_z(self) -> None:
+        self._highest_z = 0.0
+        for item in [lw for lw in self.data.values() if lw]:
+            self._highest_z = max(item.highest_z, self._highest_z)
+
+    def get_slot_definition(self, slot_name: str) -> SlotDefV3:
+        slots = self._definition["locations"]["orderedSlots"]
+        slot_def = next((slot for slot in slots if slot["id"] == slot_name), None)
+        if not slot_def:
+            slot_ids = [slot["id"] for slot in slots]
+            raise ValueError(
+                f"slot {slot_name} could not be found,"
+                f"valid deck slots are: {slot_ids}"
+            )
+        return slot_def
+
+    def get_slot_center(self, slot_name: str) -> Point:
+        defn = self.get_slot_definition(slot_name)
+        return Point(
+            defn["position"][0] + defn["boundingBox"]["xDimension"] / 2,
+            defn["position"][1] + defn["boundingBox"]["yDimension"] / 2,
+            defn["position"][2] + defn["boundingBox"]["zDimension"] / 2,
+        )
+
+    def resolve_module_location(
+        self, module_type: ModuleType, location: Optional[DeckLocation]
+    ) -> DeckLocation:
+        dn_from_type = {
+            ModuleType.MAGNETIC: "Magnetic Module",
+            ModuleType.THERMOCYCLER: "Thermocycler",
+            ModuleType.TEMPERATURE: "Temperature Module",
+            ModuleType.HEATER_SHAKER: "Heater-Shaker",
+        }
+        if isinstance(location, str) or isinstance(location, int):
+            slot_def = self.get_slot_definition(str(location))
+            compatible_modules = slot_def["compatibleModuleTypes"]
+            if module_type.value in compatible_modules:
+                return location
+            elif (
+                self._definition["robot"]["model"] == "OT-3 Standard"
+                and ModuleType.to_module_fixture_id(module_type) == slot_def["id"]
+            ):
+                return location
+            else:
+                raise ValueError(
+                    f"A {dn_from_type[module_type]} cannot be loaded"
+                    f" into slot {location}"
+                )
+        else:
+            valid_slots = [
+                slot["id"]
+                for slot in self.slots
+                if module_type.value in slot["compatibleModuleTypes"]
+            ]
+            if len(valid_slots) == 1:
+                return valid_slots[0]
+            elif not valid_slots:
+                raise ValueError(
+                    "A {dn_from_type[module_type]} cannot be used with this deck"
+                )
+            else:
+                raise ValueError(
+                    f"{dn_from_type[module_type]}s do not have default"
+                    " location, you must specify a slot"
+                )
+
+    @property
+    def highest_z(self) -> float:
+        """Return the tallest known point on the deck."""
+        return self._highest_z
+
+    @property
+    def slots(self) -> List[SlotDefV3]:
+        """Return the definition of the loaded robot deck."""
+        return self._definition["locations"]["orderedSlots"]
+
+    @property
+    def calibration_positions(self) -> List[CalibrationPosition]:
+        raw_positions = self._definition["locations"]["calibrationPoints"]
+        return [
+            CalibrationPosition(
+                id=raw_position["id"],
+                displayName=raw_position["displayName"],
+                position=(
+                    raw_position["position"][0],
+                    raw_position["position"][1],
+                    raw_position["position"][2],
+                ),
+            )
+            for raw_position in raw_positions
+        ]
+
+    def get_calibration_position(self, id: str) -> CalibrationPosition:
+        calibration_position = next(
+            (pos for pos in self.calibration_positions if pos.id == id), None
+        )
+        if not calibration_position:
+            pos_ids = [pos.id for pos in self.calibration_positions]
+            raise ValueError(
+                f"calibration position {id} "
+                "could not be found, "
+                f"valid calibration position ids are: {pos_ids}"
+            )
+        return calibration_position
+
+    def get_fixed_trash(self) -> Optional[Union[Labware, LegacyLabwareCore]]:
+        fixtures = self._definition["locations"]["fixtures"]
+        ft = next((f for f in fixtures if f["id"] == FIXED_TRASH_ID), None)
+
+        # NOTE(mc, 2022-12-06): type ignore below because this `Deck` is typed
+        # as contiaining `DeckItem` values, but the contents of slot 12
+        # will always be limited to either a `Labware` or `LegacyLabwareCore` object
+        return self.data[self._check_name(ft.get("slot"))] if ft else None  # type: ignore[return-value]
+
+    def get_non_fixture_slots(self) -> List[int]:
+        fixtures = self._definition["locations"]["fixtures"]
+        fixture_slots = {
+            self._check_name(f.get("slot")) for f in fixtures if f.get("slot")
+        }
+        return [s for s in self.data.keys() if s not in fixture_slots]
+
+    @property
+    def thermocycler_present(self) -> bool:
+        """Is a thermocycler present on the deck."""
+        return self._thermocycler_present

opentrons/protocol_api/core/legacy/labware_offset_provider.py

@@ -0,0 +1,108 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from opentrons.hardware_control.modules import ModuleModel as HardwareModuleModel
+from opentrons.protocol_engine import (
+    ProtocolEngine,
+    LegacyLabwareOffsetLocation,
+    ModuleModel,
+)
+from opentrons.types import DeckSlotName, Point
+
+from ..labware import LabwareLoadParams
+
+
+@dataclass
+class ProvidedLabwareOffset:
+    """A labware offset provided externally.
+
+    Parameters:
+        delta: The positional adjustment that should apply to all movements
+            to this labware. Measured in deck coordinates, from the nominal
+            position to the adjusted position.
+        offset_id: An ID referencing the relevant external offset resource.
+            `None` means no matching offset.
+    """
+
+    delta: Point
+    offset_id: Optional[str]
+
+
+class AbstractLabwareOffsetProvider(ABC):
+    @abstractmethod
+    def find(
+        self,
+        load_params: LabwareLoadParams,
+        requested_module_model: Optional[HardwareModuleModel],
+        deck_slot: DeckSlotName,
+    ) -> ProvidedLabwareOffset:
+        """Return the offset that should apply to a newly loaded labware.
+
+        An APIv2 protocol's `ProtocolContext` should call this once for each labware,
+        as it loads it.
+
+        Args:
+            labware_definition_uri: The labware's definition URI.
+            requested_module_model: If the labware is atop a module,
+                the model of that module.
+                To ensure stability between simulation and execution,
+                this is the model that the protocol requested,
+                not the model that was actually found via the hardware API.
+                (They can be different because of module compatibility.)
+            deck_slot: The deck slot that the labware occupies. Or, if the labware is
+                atop a module, the deck slot that the module occupies.
+        """
+        ...
+
+
+class NullLabwareOffsetProvider(AbstractLabwareOffsetProvider):
+    """Always provides (0, 0, 0)."""
+
+    def find(
+        self,
+        load_params: LabwareLoadParams,
+        requested_module_model: Optional[HardwareModuleModel],
+        deck_slot: DeckSlotName,
+    ) -> ProvidedLabwareOffset:
+        return ProvidedLabwareOffset(delta=Point(0, 0, 0), offset_id=None)
+
+
+class LabwareOffsetProvider(AbstractLabwareOffsetProvider):
+    """Provides a `ProtocolEngine`'s labware offsets."""
+
+    def __init__(self, engine: ProtocolEngine) -> None:
+        """Initialize an offset provider with access to ProtocolEngine state."""
+        self._labware_view = engine.state_view.labware
+
+    def find(
+        self,
+        load_params: LabwareLoadParams,
+        requested_module_model: Optional[HardwareModuleModel],
+        deck_slot: DeckSlotName,
+    ) -> ProvidedLabwareOffset:
+        """Look up an offset in ProtocolEngine state and return it, if one exists.
+
+        See the parent class for param details.
+        """
+        offset = self._labware_view.find_applicable_labware_offset_by_legacy_location(
+            definition_uri=load_params.as_uri(),
+            location=LegacyLabwareOffsetLocation(
+                slotName=deck_slot,
+                moduleModel=(
+                    None
+                    if requested_module_model is None
+                    else ModuleModel(requested_module_model.value)
+                ),
+            ),
+        )
+        if offset is None:
+            return ProvidedLabwareOffset(
+                delta=Point(x=0, y=0, z=0),
+                offset_id=None,
+            )
+        else:
+            return ProvidedLabwareOffset(
+                delta=Point(x=offset.vector.x, y=offset.vector.y, z=offset.vector.z),
+                offset_id=offset.id,
+            )