opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_api/core/protocol.py

@@ -0,0 +1,311 @@
+"""The interface that implements ProtocolContext."""
+
+from __future__ import annotations
+
+from abc import abstractmethod, ABC
+from typing import Generic, List, Optional, Union, Tuple, Dict, TYPE_CHECKING
+
+from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
+from opentrons_shared_data.pipette.types import PipetteNameType
+from opentrons_shared_data.labware.types import LabwareDefinition
+from opentrons_shared_data.robot.types import RobotType
+
+from opentrons.types import (
+    DeckSlotName,
+    StagingSlotName,
+    Location,
+    Mount,
+    Point,
+)
+from opentrons.hardware_control import SyncHardwareAPI
+from opentrons.hardware_control.modules.types import ModuleModel
+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, LiquidClass
+from .robot import AbstractRobot
+from .._types import OffDeckType
+from ..disposal_locations import TrashBin, WasteChute
+
+if TYPE_CHECKING:
+    from ..labware import Labware
+
+
+class AbstractProtocol(
+    ABC, Generic[InstrumentCoreType, LabwareCoreType, ModuleCoreType]
+):
+    @property
+    @abstractmethod
+    def fixed_trash(self) -> Optional[LabwareCoreType]:
+        """Get the fixed trash labware core."""
+        ...
+
+    @property
+    @abstractmethod
+    def robot_type(self) -> RobotType:
+        ...
+
+    @abstractmethod
+    def get_max_speeds(self) -> AxisMaxSpeeds:
+        ...
+
+    @abstractmethod
+    def get_hardware(self) -> SyncHardwareAPI:
+        ...
+
+    @abstractmethod
+    def is_simulating(self) -> bool:
+        ...
+
+    @abstractmethod
+    def add_labware_definition(
+        self,
+        definition: LabwareDefinition,
+    ) -> LabwareLoadParams:
+        """Add a labware definition to the set of loadable definitions."""
+        ...
+
+    @abstractmethod
+    def append_disposal_location(
+        self,
+        disposal_location: Union[Labware, TrashBin, WasteChute],
+    ) -> None:
+        """Append a disposal location object to the core"""
+        ...
+
+    @abstractmethod
+    def load_labware(
+        self,
+        load_name: str,
+        location: Union[
+            DeckSlotName, StagingSlotName, LabwareCoreType, ModuleCoreType, OffDeckType
+        ],
+        label: Optional[str],
+        namespace: Optional[str],
+        version: Optional[int],
+    ) -> LabwareCoreType:
+        """Load a labware using its identifying parameters."""
+        ...
+
+    @abstractmethod
+    def load_adapter(
+        self,
+        load_name: str,
+        location: Union[DeckSlotName, StagingSlotName, ModuleCoreType, OffDeckType],
+        namespace: Optional[str],
+        version: Optional[int],
+    ) -> LabwareCoreType:
+        """Load an adapter using its identifying parameters"""
+        ...
+
+    @abstractmethod
+    def load_lid(
+        self,
+        load_name: str,
+        location: LabwareCoreType,
+        namespace: Optional[str],
+        version: Optional[int],
+    ) -> LabwareCoreType:
+        """Load an individual lid labware using its identifying parameters. Must be loaded on a labware."""
+        ...
+
+    @abstractmethod
+    def move_labware(
+        self,
+        labware_core: LabwareCoreType,
+        new_location: Union[
+            DeckSlotName,
+            StagingSlotName,
+            LabwareCoreType,
+            ModuleCoreType,
+            OffDeckType,
+            WasteChute,
+            TrashBin,
+        ],
+        use_gripper: bool,
+        pause_for_manual_move: bool,
+        pick_up_offset: Optional[Tuple[float, float, float]],
+        drop_offset: Optional[Tuple[float, float, float]],
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def move_lid(
+        self,
+        source_location: Union[DeckSlotName, StagingSlotName, LabwareCoreType],
+        new_location: Union[
+            DeckSlotName,
+            StagingSlotName,
+            LabwareCoreType,
+            OffDeckType,
+            WasteChute,
+            TrashBin,
+        ],
+        use_gripper: bool,
+        pause_for_manual_move: bool,
+        pick_up_offset: Optional[Tuple[float, float, float]],
+        drop_offset: Optional[Tuple[float, float, float]],
+    ) -> LabwareCoreType | None:
+        ...
+
+    @abstractmethod
+    def load_module(
+        self,
+        model: ModuleModel,
+        deck_slot: Optional[DeckSlotName],
+        configuration: Optional[str],
+    ) -> ModuleCoreType:
+        ...
+
+    @abstractmethod
+    def load_instrument(
+        self,
+        instrument_name: PipetteNameType,
+        mount: Mount,
+        liquid_presence_detection: bool = False,
+    ) -> InstrumentCoreType:
+        ...
+
+    @abstractmethod
+    def load_trash_bin(self, slot_name: DeckSlotName, area_name: str) -> TrashBin:
+        ...
+
+    @abstractmethod
+    def load_ot2_fixed_trash_bin(self) -> None:
+        ...
+
+    @abstractmethod
+    def load_waste_chute(self) -> WasteChute:
+        ...
+
+    @abstractmethod
+    def pause(self, msg: Optional[str]) -> None:
+        ...
+
+    @abstractmethod
+    def comment(self, msg: str) -> None:
+        ...
+
+    @abstractmethod
+    def delay(self, seconds: float, msg: Optional[str]) -> None:
+        ...
+
+    @abstractmethod
+    def home(self) -> None:
+        ...
+
+    @abstractmethod
+    def set_rail_lights(self, on: bool) -> None:
+        ...
+
+    @abstractmethod
+    def get_disposal_locations(self) -> List[Union[Labware, TrashBin, WasteChute]]:
+        ...
+
+    @abstractmethod
+    def get_rail_lights_on(self) -> bool:
+        ...
+
+    @abstractmethod
+    def door_closed(self) -> bool:
+        ...
+
+    @abstractmethod
+    def get_last_location(
+        self,
+        mount: Optional[Mount] = None,
+    ) -> Optional[Union[Location, TrashBin, WasteChute]]:
+        ...
+
+    @abstractmethod
+    def set_last_location(
+        self,
+        location: Optional[Location],
+        mount: Optional[Mount] = None,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def load_lid_stack(
+        self,
+        load_name: str,
+        location: Union[DeckSlotName, StagingSlotName, LabwareCoreType],
+        quantity: int,
+        namespace: Optional[str],
+        version: Optional[int],
+    ) -> LabwareCoreType:
+        ...
+
+    @abstractmethod
+    def get_deck_definition(self) -> DeckDefinitionV5:
+        """Get the geometry definition of the robot's deck."""
+
+    @abstractmethod
+    def get_slot_definition(
+        self, slot: Union[DeckSlotName, StagingSlotName]
+    ) -> SlotDefV3:
+        """Get the slot definition from the robot's deck."""
+
+    @abstractmethod
+    def get_slot_definitions(self) -> Dict[str, SlotDefV3]:
+        """Get all standard slot definitions available in the deck definition."""
+
+    @abstractmethod
+    def get_staging_slot_definitions(self) -> Dict[str, SlotDefV3]:
+        """Get all staging slot definitions available in the deck definition."""
+
+    @abstractmethod
+    def get_slot_item(
+        self, slot_name: Union[DeckSlotName, StagingSlotName]
+    ) -> Union[LabwareCoreType, ModuleCoreType, None]:
+        """Get the contents of a given slot, if any."""
+
+    @abstractmethod
+    def get_labware_on_module(
+        self, module_core: ModuleCoreType
+    ) -> Optional[LabwareCoreType]:
+        """Get the labware on a given module, if any."""
+
+    @abstractmethod
+    def get_labware_on_labware(
+        self, labware_core: LabwareCoreType
+    ) -> Optional[LabwareCoreType]:
+        """Get the labware on a given labware, if any."""
+
+    @abstractmethod
+    def get_slot_center(self, slot_name: Union[DeckSlotName, StagingSlotName]) -> Point:
+        """Get the absolute coordinate of a slot's center."""
+
+    @abstractmethod
+    def get_highest_z(self) -> float:
+        """Get the highest Z point of all deck items."""
+
+    @abstractmethod
+    def get_labware_cores(self) -> List[LabwareCoreType]:
+        """Get all loaded labware cores."""
+
+    @abstractmethod
+    def get_module_cores(self) -> List[ModuleCoreType]:
+        """Get all loaded module cores."""
+
+    @abstractmethod
+    def define_liquid(
+        self, name: str, description: Optional[str], display_color: Optional[str]
+    ) -> Liquid:
+        """Define a liquid to load into a well."""
+
+    @abstractmethod
+    def get_liquid_class(self, name: str, version: int) -> LiquidClass:
+        """Get an instance of a built-in liquid class."""
+
+    @abstractmethod
+    def get_labware_location(
+        self, labware_core: LabwareCoreType
+    ) -> Union[str, LabwareCoreType, ModuleCoreType, OffDeckType]:
+        """Get labware parent location."""
+
+    @abstractmethod
+    def load_robot(self) -> AbstractRobot:
+        """Load a Robot Core context into a protocol"""

opentrons/protocol_api/core/robot.py

@@ -0,0 +1,51 @@
+from abc import abstractmethod, ABC
+from typing import Optional, Union
+
+from opentrons.types import AxisMapType, Mount, Point
+from opentrons_shared_data.pipette.types import PipetteNameType
+from opentrons.protocol_api._types import PlungerPositionTypes, PipetteActionTypes
+
+
+class AbstractRobot(ABC):
+    @abstractmethod
+    def get_pipette_type_from_engine(
+        self, mount: Union[Mount, str]
+    ) -> Optional[PipetteNameType]:
+        ...
+
+    @abstractmethod
+    def get_plunger_position_from_volume(
+        self, mount: Mount, volume: float, action: PipetteActionTypes, robot_type: str
+    ) -> float:
+        ...
+
+    @abstractmethod
+    def get_plunger_position_from_name(
+        self, mount: Mount, position_name: PlungerPositionTypes
+    ) -> float:
+        ...
+
+    @abstractmethod
+    def move_to(self, mount: Mount, destination: Point, speed: Optional[float]) -> None:
+        ...
+
+    @abstractmethod
+    def move_axes_to(
+        self,
+        axis_map: AxisMapType,
+        critical_point: Optional[AxisMapType],
+        speed: Optional[float],
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def move_axes_relative(self, axis_map: AxisMapType, speed: Optional[float]) -> None:
+        ...
+
+    @abstractmethod
+    def release_grip(self) -> None:
+        ...
+
+    @abstractmethod
+    def close_gripper(self, force: Optional[float] = None) -> None:
+        ...

opentrons/protocol_api/core/well.py

@@ -0,0 +1,116 @@
+"""Abstract interface for Well core implementations."""
+
+from abc import ABC, abstractmethod
+from typing import TypeVar, Optional, Union
+
+from opentrons.types import Point, Mount
+from opentrons.protocol_engine.types import LiquidTrackingType
+
+from .._liquid import Liquid
+
+
+class AbstractWellCore(ABC):
+    """Well core interface."""
+
+    @property
+    @abstractmethod
+    def diameter(self) -> Optional[float]:
+        """Get the well's diameter, if circular."""
+
+    @property
+    @abstractmethod
+    def length(self) -> Optional[float]:
+        """Get the well's length, if rectangular."""
+
+    @property
+    @abstractmethod
+    def width(self) -> Optional[float]:
+        """Get the well's width, if rectangular."""
+
+    @property
+    @abstractmethod
+    def depth(self) -> float:
+        """Get the well's depth."""
+
+    @abstractmethod
+    def has_tip(self) -> bool:
+        """Whether the well contains a tip."""
+
+    @abstractmethod
+    def set_has_tip(self, value: bool) -> None:
+        """Set the well as containing or not containing a tip."""
+
+    @abstractmethod
+    def get_display_name(self) -> str:
+        """Get the full display name of the well (e.g. "A1 of Some Labware on 5")."""
+
+    @abstractmethod
+    def get_name(self) -> str:
+        """Get the name of the well (e.g. "A1")."""
+
+    @abstractmethod
+    def get_column_name(self) -> str:
+        """Get the column portion of the well name (e.g. "1")."""
+
+    @abstractmethod
+    def get_row_name(self) -> str:
+        """Get the row portion of the well name (e.g. "A")."""
+
+    @abstractmethod
+    def get_max_volume(self) -> float:
+        """Get the well's maximum liquid volume."""
+
+    @abstractmethod
+    def get_top(self, z_offset: float) -> Point:
+        """Get the coordinate of the well's top, with an z-offset."""
+
+    @abstractmethod
+    def get_bottom(self, z_offset: float) -> Point:
+        """Get the coordinate of the well's bottom, with an z-offset."""
+
+    @abstractmethod
+    def get_center(self) -> Point:
+        """Get the coordinate of the well's center."""
+
+    @abstractmethod
+    def get_meniscus(self) -> Union[Point, LiquidTrackingType]:
+        """Get the coordinate of the well's meniscus."""
+
+    @abstractmethod
+    def load_liquid(
+        self,
+        liquid: Liquid,
+        volume: float,
+    ) -> None:
+        """Load liquid into a well."""
+
+    @abstractmethod
+    def from_center_cartesian(self, x: float, y: float, z: float) -> Point:
+        """Gets point in deck coordinates based on percentage of the radius of each axis."""
+
+    @abstractmethod
+    def estimate_liquid_height_after_pipetting(
+        self,
+        mount: Mount | str,
+        operation_volume: float,
+    ) -> LiquidTrackingType:
+        """Estimate what the liquid height will be after pipetting, without raising an error."""
+
+    @abstractmethod
+    def current_liquid_height(self) -> LiquidTrackingType:
+        """Get the current liquid height."""
+
+    @abstractmethod
+    def get_liquid_volume(self) -> LiquidTrackingType:
+        """Get the current volume within a well."""
+
+    @abstractmethod
+    def height_from_volume(self, volume: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the height in a well corresponding to a given volume."""
+
+    @abstractmethod
+    def volume_from_height(self, height: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the volume contained in a well at any height."""
+
+
+WellCoreType = TypeVar("WellCoreType", bound=AbstractWellCore)

opentrons/protocol_api/core/well_grid.py

@@ -0,0 +1,45 @@
+"""Well grid information."""
+import collections
+from dataclasses import dataclass
+from typing import Dict, List
+
+from opentrons_shared_data.labware.constants import WELL_NAME_PATTERN
+
+
+@dataclass(frozen=True)
+class WellGrid:
+    """Well grid information.
+
+    Attributes:
+        columns_by_name: An ordered mapping of well names, keyed by column names.
+        rows_by_name: An ordered mapping of well names, keyed by row names.
+    """
+
+    rows_by_name: Dict[str, List[str]]
+    columns_by_name: Dict[str, List[str]]
+
+
+# NOTE(mc, 2022-11-11): to preserve historical behavior,
+# this function organizes rows and columns using the well name,
+# rather than the well's position in the labware definition's `ordering` field.
+# Logic originally added in https://github.com/Opentrons/opentrons/pull/2418
+def create(columns: List[List[str]]) -> WellGrid:
+    columns_by_name = collections.defaultdict(list)
+    rows_by_name = collections.defaultdict(list)
+
+    for column in columns:
+        for well_name in column:
+            well_name_match = WELL_NAME_PATTERN.match(well_name)
+
+            assert (
+                well_name_match is not None
+            ), "Well name did not match required pattern; please check labware definition."
+
+            row_name, column_name = well_name_match.group(1, 2)
+            rows_by_name[row_name].append(well_name)
+            columns_by_name[column_name].append(well_name)
+
+    return WellGrid(
+        columns_by_name=columns_by_name,
+        rows_by_name=rows_by_name,
+    )

opentrons/protocol_api/create_protocol_context.py

@@ -0,0 +1,177 @@
+"""ProtocolContext factory."""
+import asyncio
+from typing import Any, Dict, Optional, Union, cast
+
+from opentrons_shared_data.labware.types import LabwareDefinition
+
+from opentrons.hardware_control import (
+    HardwareControlAPI,
+    ThreadManager,
+    SynchronousAdapter,
+)
+from opentrons.legacy_broker import LegacyBroker
+from opentrons.util.broker import Broker
+from opentrons.protocol_engine import ProtocolEngine
+from opentrons.protocol_engine.clients import SyncClient, ChildThreadTransport
+from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.deck_type import (
+    should_load_fixed_trash_area_for_python_protocol,
+)
+from opentrons.protocols.api_support.definitions import MAX_SUPPORTED_VERSION
+
+from .protocol_context import ProtocolContext
+from .deck import Deck
+from .disposal_locations import TrashBin
+
+from .core.common import ProtocolCore as AbstractProtocolCore
+from .core.legacy.deck import Deck as LegacyDeck
+from .core.legacy.legacy_protocol_core import LegacyProtocolCore
+from .core.legacy.labware_offset_provider import (
+    AbstractLabwareOffsetProvider,
+    LabwareOffsetProvider,
+    NullLabwareOffsetProvider,
+)
+from .core.legacy_simulator.legacy_protocol_core import LegacyProtocolCoreSimulator
+from .core.engine import ENGINE_CORE_API_VERSION, ProtocolCore
+
+
+class ProtocolEngineCoreRequiredError(Exception):
+    """Raised when a Protocol Engine core was required, but not provided.
+
+    This can happen when creating a ProtocolContext with a high api_version.
+    """
+
+
+def create_protocol_context(
+    api_version: APIVersion,
+    *,
+    hardware_api: Union[HardwareControlAPI, ThreadManager[HardwareControlAPI]],
+    deck_type: str,
+    protocol_engine: Optional[ProtocolEngine] = None,
+    protocol_engine_loop: Optional[asyncio.AbstractEventLoop] = None,
+    broker: Optional[LegacyBroker] = None,
+    equipment_broker: Optional[Broker[Any]] = None,
+    use_simulating_core: bool = False,
+    extra_labware: Optional[Dict[str, LabwareDefinition]] = None,
+    bundled_labware: Optional[Dict[str, LabwareDefinition]] = None,
+    bundled_data: Optional[Dict[str, bytes]] = None,
+) -> ProtocolContext:
+    """Create a ProtocolContext for use in a Python protocol.
+
+    Args:
+        api_version: The API version to target.
+        hardware_api: Control interface to the device's hardware.
+        deck_type: What kind of deck the device has.
+            This must match the deck type in `protocol_engine`'s config, if there is one.
+        protocol_engine: A ProtocolEngine to use for labware offsets
+            and core protocol logic. If omitted, labware offsets will
+            all be (0, 0, 0) and ProtocolEngine-based core will not work.
+        protocol_engine_loop: An event loop running in the thread where
+            ProtocolEngine mutations must occur.
+        broker: A message broker for protocol command event publishing.
+        equipment_broker: A message broker for equipment load event publishing.
+        use_simulating_core: For pre-ProtocolEngine API versions,
+            use a simulating protocol core that will skip _most_ calls
+            to the `hardware_api`.
+        extra_labware: Extra labware definitions to include in
+            labware definition lookup paths.
+        bundled_labware: Do not use in new code. Leftover from
+            experimental ZIP protocol bundles.
+        bundled_data: Do not use in new code. Leftover from
+            experimental ZIP protocol bundles.
+
+    Returns:
+        A ready-to-use ProtocolContext.
+    """
+    if api_version > MAX_SUPPORTED_VERSION:
+        raise ValueError(
+            f"API version {api_version} is not supported by this robot software."
+            f" Please reduce your API version to {MAX_SUPPORTED_VERSION} or below"
+            f" or update your robot."
+        )
+
+    sync_hardware: SynchronousAdapter[HardwareControlAPI]
+    labware_offset_provider: AbstractLabwareOffsetProvider
+    core: Union[ProtocolCore, LegacyProtocolCoreSimulator, LegacyProtocolCore]
+
+    if isinstance(hardware_api, ThreadManager):
+        sync_hardware = hardware_api.sync
+    else:
+        sync_hardware = SynchronousAdapter(hardware_api)
+
+    if protocol_engine is not None:
+        assert deck_type == protocol_engine.state_view.config.deck_type.value
+        labware_offset_provider = LabwareOffsetProvider(engine=protocol_engine)
+    else:
+        labware_offset_provider = NullLabwareOffsetProvider()
+
+    if api_version >= ENGINE_CORE_API_VERSION:
+        # TODO(mc, 2022-8-22): replace raise with strict typing
+        if protocol_engine is None or protocol_engine_loop is None:
+            raise ProtocolEngineCoreRequiredError(
+                "ProtocolEngine PAPI core is enabled, but no ProtocolEngine given."
+            )
+
+        engine_client_transport = ChildThreadTransport(
+            engine=protocol_engine, loop=protocol_engine_loop
+        )
+        engine_client = SyncClient(transport=engine_client_transport)
+        core = ProtocolCore(
+            engine_client=engine_client,
+            api_version=api_version,
+            sync_hardware=sync_hardware,
+        )
+
+    elif use_simulating_core:
+        legacy_deck = LegacyDeck(deck_type=deck_type)
+        core = LegacyProtocolCoreSimulator(
+            sync_hardware=sync_hardware,
+            labware_offset_provider=labware_offset_provider,
+            deck_layout=legacy_deck,
+            equipment_broker=equipment_broker,
+            api_version=api_version,
+            bundled_labware=bundled_labware,
+            extra_labware=extra_labware,
+        )
+
+    else:
+        legacy_deck = LegacyDeck(deck_type=deck_type)
+        core = LegacyProtocolCore(
+            sync_hardware=sync_hardware,
+            labware_offset_provider=labware_offset_provider,
+            deck_layout=legacy_deck,
+            equipment_broker=equipment_broker,
+            api_version=api_version,
+            bundled_labware=bundled_labware,
+            extra_labware=extra_labware,
+        )
+
+    # TODO(mc, 2022-12-06): add API version guard in addition to instance check
+    # this swap may happen once `ctx.move_labware` off-deck is implemented
+    deck = None if isinstance(core, ProtocolCore) else cast(Deck, core.get_deck())
+
+    context = ProtocolContext(
+        api_version=api_version,
+        # TODO(mm, 2023-05-11): This cast shouldn't be necessary.
+        # Fix this by making the appropriate TypeVars covariant?
+        # https://peps.python.org/pep-0484/#covariance-and-contravariance
+        core=cast(AbstractProtocolCore, core),
+        broker=broker,
+        deck=deck,
+        bundled_data=bundled_data,
+    )
+    # If we're loading an engine based core into the context, and we're on api level 2.16 or above, on an OT-2 we need
+    # to insert a fixed trash addressable area into the protocol engine, for correctness in anything that relies on
+    # knowing what addressable areas have been loaded (and any checks involving trash geometry). Because the method
+    # that uses this in the core relies on the sync client and this code will run in the main thread (which if called
+    # will cause a deadlock), we're directly calling the protocol engine method here where we have access to it.
+    if (
+        protocol_engine is not None
+        and should_load_fixed_trash_area_for_python_protocol(
+            api_version=api_version,
+            robot_type=protocol_engine.state_view.config.robot_type,
+        )
+    ):
+        assert isinstance(context.fixed_trash, TrashBin)
+        protocol_engine.add_addressable_area(context.fixed_trash.area_name)
+    return context