opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py

@@ -0,0 +1,231 @@
+"""Utility functions for transfer_liquid, consolidate_liquid and distribute_liquid"""
+from __future__ import annotations
+
+from typing import Literal, Sequence, List, Optional, TYPE_CHECKING
+from dataclasses import dataclass
+
+from opentrons.protocol_engine.errors import (
+    LiquidHeightUnknownError,
+    IncompleteLabwareDefinitionError,
+)
+from opentrons.protocol_engine.state._well_math import (
+    wells_covered_by_pipette_configuration,
+)
+from opentrons.types import NozzleMapInterface, NozzleConfigurationType
+
+if TYPE_CHECKING:
+    from logging import Logger
+    from opentrons.types import Location
+    from opentrons.protocol_api.core.engine import WellCore
+    from opentrons.protocol_api.labware import Well, Labware
+
+
+@dataclass
+class LocationCheckDescriptors:
+    location_type: Literal["submerge start", "retract end"]
+    pipetting_action: Literal["aspirate", "dispense"]
+
+
+def raise_if_location_inside_liquid(
+    location: Location,
+    well_core: WellCore,
+    location_check_descriptors: LocationCheckDescriptors,
+    logger: Logger,
+) -> None:
+    """Raise an error if the location in question would be inside the liquid.
+
+    This checker will raise an error if we can find the liquid height
+    AND the location in question is below this height.
+
+    If we can't find the liquid height, then we simply log the details and no error is raised.
+    """
+    try:
+        liquid_height_from_bottom = well_core.current_liquid_height()
+    except (IncompleteLabwareDefinitionError, LiquidHeightUnknownError):
+        # IncompleteLabwareDefinitionError is raised when there's no inner geometry
+        # defined for the well. So, we can't find the liquid height even if liquid volume is known.
+        # LiquidHeightUnknownError is raised when we don't have liquid volume info
+        # and no probing has been done either.
+        liquid_height_from_bottom = None
+    if isinstance(liquid_height_from_bottom, (int, float)):
+        if liquid_height_from_bottom + well_core.get_bottom(0).z > location.point.z:
+            raise RuntimeError(
+                f"{location_check_descriptors.location_type.capitalize()} location {location} is"
+                f" inside the liquid in well {well_core.get_display_name()} when it should be outside"
+                f"(above) the liquid."
+            )
+    else:
+        # We could raise an error here but that would restrict the use of
+        # liquid classes-based transfer to only when LPD is enabled or when liquids are
+        # loaded in protocols using `load_liquid`. This can be quite restrictive
+        # so we will not raise but just log the details.
+        logger.info(
+            f"Could not verify height of liquid in well {well_core.get_display_name()}, either"
+            f" because the liquid in this well has not been probed or"
+            f" liquid was not loaded in this well using `load_liquid` or"
+            f" inner geometry is not available for the target well."
+            f" Proceeding without verifying if {location_check_descriptors.location_type}"
+            f" location is outside the liquid."
+        )
+
+
+def group_wells_for_multi_channel_transfer(
+    targets: Sequence[Well],
+    nozzle_map: NozzleMapInterface,
+    target_name: Literal["source", "destination"],
+) -> List[Well]:
+    """Takes a list of wells and a nozzle map and returns a list of target wells to address every well given
+
+    This currently only supports 8-tip columns, 12-tip rows and full 96-channel configurations,
+    and only is used for 96 and 384 well plates. This assumes the wells are being given in a
+    contiguous order (or every other for 384), and will raise if a well is found that does not overlap
+    with the first target well given for a sequence, or if not all wells are given for that sequence.
+    """
+    configuration = nozzle_map.configuration
+    active_nozzles = nozzle_map.tip_count
+
+    if (
+        (
+            (
+                configuration == NozzleConfigurationType.COLUMN
+                or configuration == NozzleConfigurationType.FULL
+            )
+            and active_nozzles == 8
+        )
+        or (configuration == NozzleConfigurationType.ROW and active_nozzles == 12)
+        or active_nozzles == 96
+    ):
+        return _group_wells_for_nozzle_configuration(
+            list(targets), nozzle_map, target_name
+        )
+    else:
+        raise ValueError(
+            "Unsupported nozzle configuration for well grouping. Set group_wells to False"
+            " to only target wells with the primary nozzle for this configuration."
+        )
+
+
+def _group_wells_for_nozzle_configuration(  # noqa: C901
+    targets: List[Well],
+    nozzle_map: NozzleMapInterface,
+    target_name: Literal["source", "destination"],
+) -> List[Well]:
+    """Groups wells together for a column, row, or full 96 configuration and returns a reduced list of target wells."""
+    grouped_wells = []
+    active_wells_covered: List[str] = []
+    active_labware: Optional[Labware] = None
+    alternate_384_well_coverage_count = 0
+    labware_format: Optional[str] = None
+
+    # We are assuming the wells are ordered A1, B1, C1... A2, B2, C2..., for columns and
+    # A1, A2, A3... B1, B2, B3 for rows. So if the active nozzle is on H row/12 column,
+    # reverse the list so the correct primary nozzle is chosen
+    reverse_lookup = (
+        nozzle_map.starting_nozzle == "H12"
+        or (
+            nozzle_map.configuration == NozzleConfigurationType.COLUMN
+            and nozzle_map.starting_nozzle == "H1"
+        )
+        or (
+            nozzle_map.configuration == NozzleConfigurationType.ROW
+            and nozzle_map.starting_nozzle == "A12"
+        )
+    )
+    if reverse_lookup:
+        targets.reverse()
+
+    for well in targets:
+        # If we have wells that are covered by the pipette's nozzles while primary nozzle is over
+        # a target well that aren't accounted for, check if the current well is in that list
+        if active_wells_covered:
+            if well.parent != active_labware:
+                raise ValueError(
+                    f"Could not group {target_name} wells to match pipette's nozzle configuration. Ensure that the"
+                    " wells are ordered correctly (e.g. rows() for a row layout or columns() for a column layout), or"
+                    " set group_wells to False to only target wells with the primary nozzle."
+                )
+
+            if well.well_name in active_wells_covered:
+                active_wells_covered.remove(well.well_name)
+            # If it's a 384 well plate, contiguous wells are not covered by the pipette targeting the
+            # initial target well. To support these kinds of transfers given a list of contiguous wells,
+            # allow another target well (or up to 4 total for a full 96-tip config) and add those wells
+            # to the list of covered wells
+            elif labware_format == "384Standard" and (
+                alternate_384_well_coverage_count == 0
+                or (
+                    nozzle_map.tip_count == 96 and alternate_384_well_coverage_count < 3
+                )
+            ):
+                active_wells_covered.extend(
+                    list(
+                        wells_covered_by_pipette_configuration(
+                            nozzle_map,  # type: ignore[arg-type]
+                            well.well_name,
+                            labware_wells_by_column=[
+                                [labware_well.well_name for labware_well in column]
+                                for column in well.parent.columns()
+                            ],
+                        )
+                    )
+                )
+                active_wells_covered.remove(well.well_name)
+                grouped_wells.append(well)
+                alternate_384_well_coverage_count += 1
+            else:
+                raise ValueError(
+                    f"Could not group {target_name} wells to match pipette's nozzle configuration. Ensure that the"
+                    " wells are ordered correctly (e.g. rows() for a row layout or columns() for a column layout), or"
+                    " set group_wells to False to only target wells with the primary nozzle."
+                )
+        # If we have no active wells covered to account for, add a new target well and list of covered wells to check
+        else:
+            # If the labware is not a 96 or 384 well plate, add this well to the final result and move on to the next
+            labware_format = well.parent.parameters["format"]
+            if labware_format != "96Standard" and labware_format != "384Standard":
+                grouped_wells.append(well)
+                continue
+
+            active_wells_covered = list(
+                wells_covered_by_pipette_configuration(
+                    nozzle_map,  # type: ignore[arg-type]
+                    well.well_name,
+                    labware_wells_by_column=[
+                        [labware_well.well_name for labware_well in column]
+                        for column in well.parent.columns()
+                    ],
+                )
+            )
+            active_wells_covered.remove(well.well_name)
+            grouped_wells.append(well)
+            active_labware = well.parent
+            alternate_384_well_coverage_count = 0
+
+    if active_wells_covered:
+        raise ValueError(
+            f"Pipette will access {target_name} wells not provided in the liquid handling command."
+            f" Set group_wells to False or include these wells: {active_wells_covered}"
+        )
+
+    # If we reversed the lookup of wells, reverse the grouped wells we will return
+    if reverse_lookup:
+        grouped_wells.reverse()
+
+    return grouped_wells
+
+
+def check_current_volume_before_dispensing(
+    current_volume: float,
+    dispense_volume: float,
+) -> None:
+    """Check if the current volume is valid for dispensing the dispense volume."""
+    if current_volume < dispense_volume:
+        # Although this should never happen, we can get into an unexpected state
+        # following error recovery and not have the expected amount of liquid in the tip.
+        # If this happens, we want to raise a useful error so the user can understand
+        # the cause of the problem. If we don't make this check for current volume,
+        # an unhelpful error might get raised when a '..byVolume' property encounters
+        # a negative volume (current_volume - dispense_volume).
+        raise RuntimeError(
+            f"Cannot dispense {dispense_volume}uL when the tip has only {current_volume}uL."
+        )

opentrons/protocols/api_support/constants.py

@@ -0,0 +1,8 @@
+from pathlib import Path
+
+from opentrons.config import get_opentrons_path
+
+OPENTRONS_NAMESPACE = "opentrons"
+CUSTOM_NAMESPACE = "custom_beta"
+STANDARD_DEFS_PATH = Path("labware/definitions")
+USER_DEFS_PATH = get_opentrons_path("labware_user_definitions_dir_v2")

opentrons/protocols/api_support/deck_type.py

@@ -0,0 +1,110 @@
+from typing import Sequence, Dict, Optional, Any
+
+from opentrons_shared_data.robot.types import RobotType
+from opentrons_shared_data.errors import ErrorCodes
+from opentrons_shared_data.errors.exceptions import EnumeratedError
+
+from opentrons.config import feature_flags
+
+from opentrons.protocol_reader.protocol_source import (
+    ProtocolConfig,
+    PythonProtocolConfig,
+    JsonProtocolConfig,
+)
+from opentrons.protocols.api_support.types import APIVersion
+
+
+# TODO(mm, 2023-05-10): Deduplicate these constants with
+# opentrons.protocol_engine.types.DeckType and consider moving to shared-data.
+SHORT_TRASH_DECK = "ot2_short_trash"
+STANDARD_OT2_DECK = "ot2_standard"
+STANDARD_OT3_DECK = "ot3_standard"
+
+
+LOAD_FIXED_TRASH_GATE_VERSION_PYTHON = APIVersion(2, 15)
+LOAD_FIXED_TRASH_GATE_VERSION_JSON = 7
+
+
+class NoTrashDefinedError(EnumeratedError):
+    """
+    Error raised when a protocol attempts to automatically access a trash bin without one being loaded.
+    """
+
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        detail: Optional[Dict[str, Any]] = None,
+        wrapping: Optional[Sequence[EnumeratedError]] = None,
+    ) -> None:
+        """Build a ProtocolEngineError."""
+        super().__init__(
+            code=ErrorCodes.GENERAL_ERROR,
+            message=message,
+            detail=detail,
+            wrapping=wrapping,
+        )
+
+
+def should_load_fixed_trash_labware_for_python_protocol(
+    api_version: APIVersion,
+) -> bool:
+    """Whether to automatically load the fixed trash as a labware for a Python protocol at protocol start."""
+    return api_version <= LOAD_FIXED_TRASH_GATE_VERSION_PYTHON
+
+
+def should_load_fixed_trash_area_for_python_protocol(
+    api_version: APIVersion, robot_type: RobotType
+) -> bool:
+    """Whether to automatically load the fixed trash addressable area for OT-2 protocols on 2.16 and above."""
+    return (
+        api_version > LOAD_FIXED_TRASH_GATE_VERSION_PYTHON
+        and robot_type == "OT-2 Standard"
+    )
+
+
+def should_load_fixed_trash(protocol_config: ProtocolConfig) -> bool:
+    """Decide whether to automatically load fixed trash labware on the deck based on version."""
+    load_fixed_trash = False
+    if isinstance(protocol_config, PythonProtocolConfig):
+        return should_load_fixed_trash_labware_for_python_protocol(
+            protocol_config.api_version
+        )
+    # TODO(jbl 2023-10-27), when schema v8 is out, use a new deck version field to support fixed trash protocols
+    elif isinstance(protocol_config, JsonProtocolConfig):
+        load_fixed_trash = (
+            protocol_config.schema_version <= LOAD_FIXED_TRASH_GATE_VERSION_JSON
+        )
+
+    return load_fixed_trash
+
+
+def guess_from_global_config() -> str:
+    """Return the deck type that the host device physically has.
+
+    This only makes sense when the software is running on a real robot.
+
+    When simulating or analyzing a protocol, especially off-robot, don't use this, because it may
+    not match the protocol's declared robot type. Use `for_analysis` instead.
+    """
+    if feature_flags.enable_ot3_hardware_controller():
+        return STANDARD_OT3_DECK
+    elif feature_flags.short_fixed_trash():
+        return SHORT_TRASH_DECK
+    else:
+        return STANDARD_OT2_DECK
+
+
+def for_simulation(robot_type: RobotType) -> str:
+    """Return the deck type that should be used for simulating and analyzing a protocol.
+
+    Params:
+        robot_type: The robot type that the protocol is meant to run on.
+    """
+    if robot_type == "OT-2 Standard":
+        # OT-2 protocols don't have a way of defining whether they're meant to run on a short-trash
+        # or standard deck. So when we're simulating an OT-2 protocol, we need to make an
+        # arbitrary choice for which deck type to use.
+        return STANDARD_OT2_DECK
+    elif robot_type == "OT-3 Standard":
+        # OT-3s currently only have a single deck type.
+        return STANDARD_OT3_DECK

opentrons/protocols/api_support/definitions.py

@@ -0,0 +1,18 @@
+from .types import APIVersion
+
+MAX_SUPPORTED_VERSION = APIVersion(2, 25)
+"""The maximum supported protocol API version in this release."""
+
+MIN_SUPPORTED_VERSION = APIVersion(2, 0)
+"""The minimum supported protocol API version in this release, across all robot types."""
+
+MIN_SUPPORTED_VERSION_FOR_FLEX = APIVersion(2, 15)
+"""The minimum protocol API version supported by the Opentrons Flex.
+
+It's an infrastructural requirement for this to be at least newer than 2.14. Before then,
+the protocol API is backed by the legacy non-Protocol-engine backend, which is not prepared to
+handle anything but OT-2s.
+
+The additional bump to 2.15 is because that's what we tested on, and because it adds all the
+Flex-specific features.
+"""

opentrons/protocols/api_support/instrument.py

@@ -0,0 +1,151 @@
+import logging
+from typing import Optional, Any
+
+from opentrons_shared_data.labware.types import (
+    LabwareDefinition2 as LabwareDefinition2Dict,
+)
+
+from opentrons import types
+from opentrons.calibration_storage.helpers import uri_from_definition
+from opentrons.calibration_storage.types import TipLengthCalNotFound
+from opentrons.hardware_control.dev_types import PipetteDict
+
+# TODO (lc 09-26-2022) We should conditionally import ot2 or ot3 calibration
+from opentrons.hardware_control.instruments.ot2 import (
+    instrument_calibration as instr_cal,
+)
+from opentrons.protocol_api.labware import Labware
+from opentrons.protocols.api_support.types import APIVersion
+from opentrons_shared_data.protocol.types import (
+    LiquidHandlingCommand,
+    BlowoutLocation,
+)
+
+
+def validate_blowout_location(
+    api_version: APIVersion,
+    liquid_handling_command: LiquidHandlingCommand,
+    blowout_location: Optional[Any],
+) -> None:
+    """Validate the blowout location."""
+    if blowout_location and api_version < APIVersion(2, 8):
+        raise ValueError(
+            "Cannot specify blowout location when using api"
+            + " version below 2.8, current version is {api_version}".format(
+                api_version=api_version
+            )
+        )
+
+    elif liquid_handling_command == "consolidate" and blowout_location == "source well":
+        raise ValueError("blowout location for consolidate cannot be source well")
+    elif (
+        liquid_handling_command == "distribute"
+        and blowout_location == "destination well"
+    ):
+        raise ValueError("blowout location for distribute cannot be destination well")
+    elif (
+        liquid_handling_command == "transfer"
+        and blowout_location
+        and blowout_location not in [location.value for location in BlowoutLocation]
+    ):
+        raise ValueError(
+            "blowout location should be either 'source well', "
+            + " 'destination well', or 'trash'"
+            + f" but it is {blowout_location}"
+        )
+
+
+def tip_length_for(
+    pipette: PipetteDict, tip_rack_definition: LabwareDefinition2Dict
+) -> float:
+    """Get the tip length, including overlap, for a tip from this rack"""
+    try:
+        return instr_cal.load_tip_length_for_pipette(
+            pipette["pipette_id"], tip_rack_definition
+        ).tip_length
+    except TipLengthCalNotFound:
+        tip_overlap = pipette["tip_overlap"].get(
+            uri_from_definition(tip_rack_definition),
+            pipette["tip_overlap"]["default"],
+        )
+        tip_length = tip_rack_definition["parameters"]["tipLength"]
+        return tip_length - tip_overlap
+
+
+VALID_PIP_TIPRACK_VOL = {
+    "FLEX": {"p50": [50], "p200": [50, 200], "p1000": [50, 200, 1000]},
+    "OT2": {
+        "p10": [10, 20],
+        "p20": [10, 20],
+        "p50": [50, 200, 300],
+        "p300": [200, 300],
+        "p1000": [1000],
+    },
+}
+
+
+def validate_tiprack(
+    instrument_name: str, tip_rack: Labware, log: logging.Logger
+) -> None:
+    """Validate a tiprack logging a warning message."""
+    if not tip_rack.is_tiprack:
+        raise ValueError(f"Labware {tip_rack.load_name} is not a tip rack.")
+
+    # TODO AA 2020-06-24 - we should instead add the acceptable Opentrons
+    #  tipracks to the pipette as a refactor
+    if tip_rack.uri.startswith("opentrons/"):
+        tiprack_vol = tip_rack.wells()[0].max_volume
+        instr_metadata = instrument_name.split("_")
+        gen_lookup = (
+            "FLEX" if ("flex" in instr_metadata or "96" in instr_metadata) else "OT2"
+        )
+
+        # TODO (spp, 2025-01-30): do what AA's note above says or at least,
+        #  fetch the 'pip_type' below from the 'model' field in pipette definitions
+        #  so that we don't have to figure it out from pipette names
+        if instrument_name.split("_")[0] == "flex":
+            # Flex's API load names have the format 'flex_1channel_1000'
+            # From API v2.23 on, this is the name returned by InstrumentContext.name
+            pip_type = "p" + instrument_name.split("_")[2]
+        else:
+            # Until API v2.23, InstrumentContext.name returned the engine-specific names
+            # of Flex pipettes. These names, as well as OT2 pipette names,
+            # have the format- 'p1000_single_gen2' or 'p1000_single_flex'
+            pip_type = instrument_name.split("_")[0]
+        valid_vols = VALID_PIP_TIPRACK_VOL[gen_lookup][pip_type]
+        if tiprack_vol not in valid_vols:
+            log.warning(
+                f"The pipette {instrument_name} and its tip rack {tip_rack.load_name}"
+                " appear to be mismatched. Please check your protocol."
+            )
+
+
+def validate_takes_liquid(
+    location: types.Location, reject_module: bool, reject_adapter: bool
+) -> None:
+    """Validate that a location is a valid liquid handling target.
+
+    Args:
+        location: target location.
+        reject_module: if set to True, disallow liquid handling directly to module
+        reject_adapter: if set to True, check that labware is not an adapter
+
+    Raises:
+        ValueError: the given location is not a valid liquid handling target.
+    """
+    labware = None
+
+    if location.labware.is_labware:
+        labware = location.labware.as_labware()
+
+    if location.labware.is_well:
+        labware = location.labware.as_well().parent
+
+    if location.labware.is_module and reject_module:
+        raise ValueError("Cannot aspirate/dispense directly to a module")
+
+    if labware is not None and labware.is_tiprack:
+        raise ValueError("Cannot aspirate/dispense to a tip rack")
+
+    if reject_adapter and (labware is not None and labware.is_adapter):
+        raise ValueError("Cannot aspirate/dispense to an adapter")