opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_api/core/engine/well.py

@@ -0,0 +1,241 @@
+"""ProtocolEngine-based Well core implementations."""
+from typing import Optional, Union
+
+from opentrons_shared_data.labware.constants import WELL_NAME_PATTERN
+
+from opentrons.types import Point, Mount, MountType
+
+from opentrons.protocol_engine import WellLocation, WellOrigin, WellOffset
+from opentrons.protocol_engine import commands as cmd
+from opentrons.protocol_engine.clients import SyncClient as EngineClient
+from opentrons.protocols.api_support.util import UnsupportedAPIError
+from opentrons.protocol_engine.types.liquid_level_detection import (
+    SimulatedProbeResult,
+    LiquidTrackingType,
+)
+from opentrons.protocol_engine.errors import PipetteNotAttachedError
+
+from . import point_calculations
+from . import stringify
+from ..well import AbstractWellCore
+from ..._liquid import Liquid
+
+
+class WellCore(AbstractWellCore):
+    """Well API core using a ProtocolEngine.
+
+    Args:
+        name: The well's name in the labware, e.g. `A1`.
+        labware_id: The ProtocolEngine ID of the well's parent labware.
+        engine_client: Synchronous ProtocolEngine client.
+    """
+
+    def __init__(self, name: str, labware_id: str, engine_client: EngineClient) -> None:
+        self._labware_id = labware_id
+        self._engine_client = engine_client
+        self._definition = engine_client.state.labware.get_well_definition(
+            labware_id=labware_id, well_name=name
+        )
+
+        name_match = WELL_NAME_PATTERN.match(name)
+        self._name = name
+        self._row_name = name_match.group(1) if name_match is not None else ""
+        self._column_name = name_match.group(2) if name_match is not None else ""
+
+    @property
+    def labware_id(self) -> str:
+        """Get the ID of the well's parent labware."""
+        return self._labware_id
+
+    @property
+    def diameter(self) -> Optional[float]:
+        """Get the well's diameter, if circular."""
+        return (
+            self._definition.diameter if self._definition.shape == "circular" else None
+        )
+
+    @property
+    def length(self) -> Optional[float]:
+        """Get the well's length, if rectangular."""
+        return (
+            self._definition.xDimension
+            if self._definition.shape == "rectangular"
+            else None
+        )
+
+    @property
+    def width(self) -> Optional[float]:
+        """Get the well's width, if rectangular."""
+        return (
+            self._definition.yDimension
+            if self._definition.shape == "rectangular"
+            else None
+        )
+
+    @property
+    def depth(self) -> float:
+        """Get the well's depth."""
+        return self._definition.depth
+
+    def has_tip(self) -> bool:
+        """Whether the well contains a tip."""
+        return self._engine_client.state.tips.has_clean_tip(
+            self._labware_id, self._name
+        )
+
+    def set_has_tip(self, value: bool) -> None:
+        """Set the well as containing or not containing a tip."""
+        raise UnsupportedAPIError(
+            api_element="Manually setting the tip state of a well in a tip rack",
+        )
+
+    def get_display_name(self) -> str:
+        """Get the full display name of the well (e.g. "A1 of Some Labware on 5")."""
+        return stringify.well(
+            engine_client=self._engine_client,
+            well_name=self._name,
+            labware_id=self._labware_id,
+        )
+
+    def get_name(self) -> str:
+        """Get the name of the well (e.g. "A1")."""
+        return self._name
+
+    def get_column_name(self) -> str:
+        """Get the column portion of the well name (e.g. "1")."""
+        return self._column_name
+
+    def get_row_name(self) -> str:
+        """Get the row portion of the well name (e.g. "A")."""
+        return self._row_name
+
+    def get_max_volume(self) -> float:
+        """Get the well's maximum liquid volume."""
+        return self._definition.totalLiquidVolume
+
+    def get_top(self, z_offset: float) -> Point:
+        """Get the coordinate of the well's top, with a z-offset."""
+        return self._engine_client.state.geometry.get_well_position(
+            well_name=self._name,
+            labware_id=self._labware_id,
+            well_location=WellLocation(
+                origin=WellOrigin.TOP, offset=WellOffset(x=0, y=0, z=z_offset)
+            ),
+        )
+
+    def get_bottom(self, z_offset: float) -> Point:
+        """Get the coordinate of the well's bottom, with a z-offset."""
+        return self._engine_client.state.geometry.get_well_position(
+            well_name=self._name,
+            labware_id=self._labware_id,
+            well_location=WellLocation(
+                origin=WellOrigin.BOTTOM, offset=WellOffset(x=0, y=0, z=z_offset)
+            ),
+        )
+
+    def get_center(self) -> Point:
+        """Get the coordinate of the well's center."""
+        return self._engine_client.state.geometry.get_well_position(
+            well_name=self._name,
+            labware_id=self._labware_id,
+            well_location=WellLocation(origin=WellOrigin.CENTER),
+        )
+
+    def get_meniscus(self) -> Union[Point, SimulatedProbeResult]:
+        """Get the coordinate of the well's meniscus."""
+        current_liquid_height = self.current_liquid_height()
+        if isinstance(current_liquid_height, float):
+            return self.get_bottom(z_offset=current_liquid_height)
+        else:
+            return current_liquid_height
+
+    def load_liquid(
+        self,
+        liquid: Liquid,
+        volume: float,
+    ) -> None:
+        """Load liquid into a well.
+
+        If the well is known to be empty, use ``load_empty()`` instead of calling this with a 0.0 volume.
+        """
+        self._engine_client.execute_command(
+            cmd.LoadLiquidParams(
+                labwareId=self._labware_id,
+                liquidId=liquid._id,
+                volumeByWell={self._name: volume},
+            )
+        )
+
+    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."""
+        well_size = self._engine_client.state.labware.get_well_size(
+            labware_id=self.labware_id, well_name=self._name
+        )
+
+        return point_calculations.get_relative_offset(
+            point=self.get_center(),
+            size=well_size,
+            x_ratio=x,
+            y_ratio=y,
+            z_ratio=z,
+        )
+
+    def estimate_liquid_height_after_pipetting(
+        self,
+        mount: Mount | str,
+        operation_volume: float,
+    ) -> LiquidTrackingType:
+        """Return an estimate of liquid height after pipetting without raising an error."""
+        labware_id = self.labware_id
+        well_name = self._name
+        if isinstance(mount, Mount):
+            mount_type = MountType.from_hw_mount(mount)
+        else:
+            mount_type = MountType(mount)
+        pipette_from_mount = self._engine_client.state.pipettes.get_by_mount(mount_type)
+        if pipette_from_mount is None:
+            raise PipetteNotAttachedError(f"No pipette present on mount {mount}")
+        pipette_id = pipette_from_mount.id
+        starting_liquid_height = self.current_liquid_height()
+        projected_final_height = (
+            self._engine_client.state.geometry.get_well_height_after_liquid_handling(
+                labware_id=labware_id,
+                well_name=well_name,
+                pipette_id=pipette_id,
+                initial_height=starting_liquid_height,
+                volume=operation_volume,
+            )
+        )
+        return projected_final_height
+
+    def current_liquid_height(self) -> LiquidTrackingType:
+        """Return the current liquid height within a well."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_meniscus_height(
+            labware_id=labware_id, well_name=well_name
+        )
+
+    def get_liquid_volume(self) -> LiquidTrackingType:
+        """Return the current volume in a well."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_current_well_volume(
+            labware_id=labware_id, well_name=well_name
+        )
+
+    def height_from_volume(self, volume: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the height in a well corresponding to a given volume."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_well_height_at_volume(
+            labware_id=labware_id, well_name=well_name, volume=volume
+        )
+
+    def volume_from_height(self, height: LiquidTrackingType) -> LiquidTrackingType:
+        """Return the volume contained in a well at any height."""
+        labware_id = self.labware_id
+        well_name = self._name
+        return self._engine_client.state.geometry.get_well_volume_at_height(
+            labware_id=labware_id, well_name=well_name, height=height
+        )

opentrons/protocol_api/core/instrument.py

@@ -0,0 +1,459 @@
+"""The interface that implements InstrumentContext."""
+
+from __future__ import annotations
+
+from abc import abstractmethod, ABC
+from typing import Any, Generic, Optional, TypeVar, Union, List, Tuple, Literal
+
+from opentrons import types
+from opentrons.hardware_control.dev_types import PipetteDict
+from opentrons.protocols.api_support.util import FlowRates
+from opentrons.protocols.advanced_control.transfers.common import TransferTipPolicyV2
+from opentrons.protocol_api._nozzle_layout import NozzleLayout
+from opentrons.protocol_api._liquid import LiquidClass
+from opentrons.protocol_engine.types import LiquidTrackingType
+
+from ..disposal_locations import TrashBin, WasteChute
+from .well import WellCoreType
+from .labware import LabwareCoreType
+
+
+class AbstractInstrument(ABC, Generic[WellCoreType, LabwareCoreType]):
+    @abstractmethod
+    def get_default_speed(self) -> float:
+        ...
+
+    @abstractmethod
+    def set_default_speed(self, speed: float) -> None:
+        ...
+
+    @abstractmethod
+    def air_gap_in_place(
+        self, volume: float, flow_rate: float, correction_volume: Optional[float] = None
+    ) -> None:
+        """Aspirate a given volume of air from the current location of the pipette.
+        Args:
+            volume: The volume of air to aspirate, in microliters.
+            flow_rate: The flow rate of air into the pipette, in microliters.
+            correction_volume: The correction volume in uL.
+        """
+
+    @abstractmethod
+    def aspirate(
+        self,
+        location: types.Location,
+        well_core: Optional[WellCoreType],
+        volume: float,
+        rate: float,
+        flow_rate: float,
+        in_place: bool,
+        meniscus_tracking: Optional[types.MeniscusTrackingTarget] = None,
+        correction_volume: Optional[float] = None,
+    ) -> None:
+        """Aspirate a given volume of liquid from the specified location.
+        Args:
+            volume: The volume of liquid to aspirate, in microliters.
+            location: The exact location to aspirate from.
+            well_core: The well to aspirate from, if applicable.
+            rate: The rate for how quickly to aspirate.
+            flow_rate: The flow rate in µL/s to aspirate at.
+            in_place: Whether this is in-place.
+            meniscus_tracking: Optional data about where to aspirate from.
+            correction_volume: The correction volume in uL
+        """
+        ...
+
+    @abstractmethod
+    def dispense(
+        self,
+        location: Union[types.Location, TrashBin, WasteChute],
+        well_core: Optional[WellCoreType],
+        volume: float,
+        rate: float,
+        flow_rate: float,
+        in_place: bool,
+        push_out: Optional[float],
+        meniscus_tracking: Optional[types.MeniscusTrackingTarget] = None,
+        correction_volume: Optional[float] = None,
+    ) -> None:
+        """Dispense a given volume of liquid into the specified location.
+        Args:
+            volume: The volume of liquid to dispense, in microliters.
+            location: The exact location to dispense to.
+            well_core: The well to dispense to, if applicable.
+            rate: The rate for how quickly to dispense.
+            flow_rate: The flow rate in µL/s to dispense at.
+            in_place: Whether this is in-place.
+            push_out: The amount to push the plunger below bottom position.
+            correction_volume: The correction volume in uL
+            meniscus_tracking: Optional data about where to dispense from.
+        """
+        ...
+
+    @abstractmethod
+    def blow_out(
+        self,
+        location: Union[types.Location, TrashBin, WasteChute],
+        well_core: Optional[WellCoreType],
+        in_place: bool,
+    ) -> None:
+        """Blow liquid out of the tip.
+
+        Args:
+            location: The location to blow out into.
+            well_core: The well to blow out into.
+            in_place: Whether this is in-place.
+        """
+        ...
+
+    @abstractmethod
+    def touch_tip(
+        self,
+        location: types.Location,
+        well_core: WellCoreType,
+        radius: float,
+        z_offset: float,
+        speed: float,
+        mm_from_edge: Optional[float] = None,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def pick_up_tip(
+        self,
+        location: types.Location,
+        well_core: WellCoreType,
+        presses: Optional[int],
+        increment: Optional[float],
+        prep_after: bool = True,
+    ) -> None:
+        """Move to and pick up a tip from a given well.
+
+        Args:
+            location: The location of the well we're picking up from.
+            well_core: The well to pick up from.
+            presses: Customize the number of presses the pipette does.
+            increment: Customize the movement "distance" of the pipette to press harder.
+            prep_after: Move plunger to the "ready to aspirate" position after pick up.
+        """
+        ...
+
+    @abstractmethod
+    def drop_tip(
+        self,
+        location: Optional[types.Location],
+        well_core: WellCoreType,
+        home_after: Optional[bool],
+        alternate_drop_location: Optional[bool] = False,
+    ) -> None:
+        """Move to and drop a tip into a given well.
+
+        Args:
+            location: The location of the well we're dropping to.
+                If unspecified, the default drop location of the well will be used.
+            well_core: The well we're dropping into
+            home_after: Whether to home the pipette after the tip is dropped.
+            alternate_drop_location: Whether to randomize the exact location to drop tip
+                within the specified well.
+        """
+        ...
+
+    @abstractmethod
+    def drop_tip_in_disposal_location(
+        self,
+        disposal_location: Union[TrashBin, WasteChute],
+        home_after: Optional[bool],
+        alternate_tip_drop: bool = False,
+    ) -> None:
+        """Move to and drop tip into a TrashBin or WasteChute.
+
+        Args:
+            disposal_location: The disposal location object we're dropping to.
+            home_after: Whether to home the pipette after the tip is dropped.
+            alternate_tip_drop: Whether to alternate tip drop location in a trash bin.
+        """
+        ...
+
+    @abstractmethod
+    def home(self) -> None:
+        ...
+
+    @abstractmethod
+    def home_plunger(self) -> None:
+        ...
+
+    @abstractmethod
+    def move_to(
+        self,
+        location: Union[types.Location, TrashBin, WasteChute],
+        well_core: Optional[WellCoreType],
+        force_direct: bool,
+        minimum_z_height: Optional[float],
+        speed: Optional[float],
+        check_for_movement_conflicts: bool,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def resin_tip_seal(
+        self,
+        location: types.Location,
+        well_core: WellCoreType,
+        in_place: Optional[bool] = False,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def resin_tip_unseal(
+        self,
+        location: types.Location | None,
+        well_core: WellCoreType,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def resin_tip_dispense(
+        self,
+        location: types.Location,
+        well_core: WellCoreType,
+        volume: Optional[float] = None,
+        flow_rate: Optional[float] = None,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def get_mount(self) -> types.Mount:
+        ...
+
+    @abstractmethod
+    def get_pipette_name(self) -> str:
+        ...
+
+    @abstractmethod
+    def get_model(self) -> str:
+        ...
+
+    @abstractmethod
+    def get_display_name(self) -> str:
+        ...
+
+    @abstractmethod
+    def get_min_volume(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_max_volume(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_working_volume(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_current_volume(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_has_clean_tip(self) -> bool:
+        ...
+
+    @abstractmethod
+    def get_available_volume(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_minimum_liquid_sense_height(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_hardware_state(self) -> PipetteDict:
+        """Get the current state of the pipette hardware as a dictionary."""
+        ...
+
+    @abstractmethod
+    def get_channels(self) -> int:
+        ...
+
+    @abstractmethod
+    def get_active_channels(self) -> int:
+        ...
+
+    @abstractmethod
+    def get_nozzle_map(self) -> types.NozzleMapInterface:
+        ...
+
+    @abstractmethod
+    def has_tip(self) -> bool:
+        ...
+
+    @abstractmethod
+    def get_return_height(self) -> float:
+        ...
+
+    @abstractmethod
+    def get_flow_rate(self) -> FlowRates:
+        ...
+
+    @abstractmethod
+    def get_aspirate_flow_rate(self, rate: float = 1.0) -> float:
+        ...
+
+    @abstractmethod
+    def get_dispense_flow_rate(self, rate: float = 1.0) -> float:
+        ...
+
+    @abstractmethod
+    def get_blow_out_flow_rate(self, rate: float = 1.0) -> float:
+        ...
+
+    @abstractmethod
+    def get_liquid_presence_detection(self) -> bool:
+        ...
+
+    @abstractmethod
+    def get_tip_origin(
+        self,
+    ) -> Optional[Tuple[LabwareCoreType, WellCoreType]]:
+        ...
+
+    @abstractmethod
+    def _pressure_supported_by_pipette(self) -> bool:
+        ...
+
+    @abstractmethod
+    def set_liquid_presence_detection(self, enable: bool) -> None:
+        ...
+
+    @abstractmethod
+    def set_flow_rate(
+        self,
+        aspirate: Optional[float] = None,
+        dispense: Optional[float] = None,
+        blow_out: Optional[float] = None,
+    ) -> None:
+        ...
+
+    @abstractmethod
+    def configure_for_volume(self, volume: float) -> None:
+        """Configure the pipette for a specific volume.
+
+        Args:
+            volume: The volume to prepare to handle.
+        """
+        ...
+
+    @abstractmethod
+    def prepare_to_aspirate(self) -> None:
+        """Prepare the pipette to aspirate."""
+        ...
+
+    @abstractmethod
+    def configure_nozzle_layout(
+        self,
+        style: NozzleLayout,
+        primary_nozzle: Optional[str],
+        front_right_nozzle: Optional[str],
+        back_left_nozzle: Optional[str],
+    ) -> None:
+        """Configure the pipette to a specific nozzle layout.
+
+        Args:
+            style: The type of configuration you wish to build.
+            primary_nozzle: The nozzle that will determine a pipette's critical point.
+            front_right_nozzle: The front right most nozzle in the requested layout.
+            back_left_nozzle: The back left most nozzle in the requested layout.
+        """
+        ...
+
+    @abstractmethod
+    def transfer_with_liquid_class(
+        self,
+        liquid_class: LiquidClass,
+        volume: float,
+        source: List[Tuple[types.Location, WellCoreType]],
+        dest: Union[List[Tuple[types.Location, WellCoreType]], TrashBin, WasteChute],
+        new_tip: TransferTipPolicyV2,
+        tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
+        trash_location: Union[types.Location, TrashBin, WasteChute],
+        return_tip: bool,
+        keep_last_tip: bool,
+    ) -> None:
+        """Transfer a liquid from source to dest according to liquid class properties."""
+        ...
+
+    @abstractmethod
+    def distribute_with_liquid_class(
+        self,
+        liquid_class: LiquidClass,
+        volume: float,
+        source: Tuple[types.Location, WellCoreType],
+        dest: List[Tuple[types.Location, WellCoreType]],
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
+        tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
+        trash_location: Union[types.Location, TrashBin, WasteChute],
+        return_tip: bool,
+        keep_last_tip: bool,
+    ) -> None:
+        """
+        Distribute a liquid from single source to multiple destinations
+        according to liquid class properties.
+        """
+        ...
+
+    @abstractmethod
+    def consolidate_with_liquid_class(
+        self,
+        liquid_class: LiquidClass,
+        volume: float,
+        source: List[Tuple[types.Location, WellCoreType]],
+        dest: Union[Tuple[types.Location, WellCoreType], TrashBin, WasteChute],
+        new_tip: Literal[TransferTipPolicyV2.NEVER, TransferTipPolicyV2.ONCE],
+        tip_racks: List[Tuple[types.Location, LabwareCoreType]],
+        starting_tip: Optional[WellCoreType],
+        trash_location: Union[types.Location, TrashBin, WasteChute],
+        return_tip: bool,
+        keep_last_tip: bool,
+    ) -> None:
+        """
+        Consolidate liquid from multiple sources to a single destination
+        using the specified liquid class properties.
+        """
+        ...
+
+    @abstractmethod
+    def is_tip_tracking_available(self) -> bool:
+        """Return whether auto tip tracking is available for the pipette's current nozzle configuration."""
+
+    @abstractmethod
+    def retract(self) -> None:
+        """Retract this instrument to the top of the gantry."""
+        ...
+
+    @abstractmethod
+    def detect_liquid_presence(
+        self, well_core: WellCoreType, loc: types.Location
+    ) -> bool:
+        """Do a liquid probe to detect whether there is liquid in the well."""
+
+    @abstractmethod
+    def liquid_probe_with_recovery(
+        self, well_core: WellCoreType, loc: types.Location
+    ) -> None:
+        """Do a liquid probe to detect the presence of liquid in the well."""
+        ...
+
+    @abstractmethod
+    def liquid_probe_without_recovery(
+        self, well_core: WellCoreType, loc: types.Location
+    ) -> LiquidTrackingType:
+        """Do a liquid probe to find the level of the liquid in the well."""
+        ...
+
+    @abstractmethod
+    def nozzle_configuration_valid_for_lld(self) -> bool:
+        """Check if the nozzle configuration currently supports LLD."""
+
+
+InstrumentCoreType = TypeVar("InstrumentCoreType", bound=AbstractInstrument[Any, Any])