opentrons 8.3.2__py2.py3-none-any.whl → 8.4.0__py2.py3-none-any.whl

opentrons/protocol_engine/types/tip.py

@@ -0,0 +1,18 @@
+"""Protocol Engine types to deal with tips."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TipGeometry:
+    """Tip geometry data.
+
+    Props:
+        length: The effective length (total length minus overlap) of a tip in mm.
+        diameter: Tip diameter in mm.
+        volume: Maximum volume in µL.
+    """
+
+    length: float
+    diameter: float
+    volume: float

opentrons/protocol_engine/types/util.py

@@ -0,0 +1,21 @@
+"""Protocol engine utility types for model components."""
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+
+@dataclass(frozen=True)
+class Dimensions:
+    """Dimensions of an object in deck-space."""
+
+    x: float
+    y: float
+    z: float
+
+
+class Vec3f(BaseModel):
+    """A 3D vector of floats."""
+
+    x: float
+    y: float
+    z: float

opentrons/protocol_engine/types/well_position.py

@@ -0,0 +1,124 @@
+"""Protocol engine types to do with positions inside wells."""
+from enum import Enum, auto
+from typing import Union, Literal
+
+from pydantic import BaseModel, Field
+
+
+class WellOrigin(str, Enum):
+    """Origin of WellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+        MENISCUS: the meniscus-center of the well
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+    MENISCUS = "meniscus"
+
+
+class PickUpTipWellOrigin(str, Enum):
+    """The origin of a PickUpTipWellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+
+
+class DropTipWellOrigin(str, Enum):
+    """The origin of a DropTipWellLocation offset.
+
+    Props:
+        TOP: the top-center of the well
+        BOTTOM: the bottom-center of the well
+        CENTER: the middle-center of the well
+        DEFAULT: the default drop-tip location of the well,
+            based on pipette configuration and length of the tip.
+    """
+
+    TOP = "top"
+    BOTTOM = "bottom"
+    CENTER = "center"
+    DEFAULT = "default"
+
+
+class WellLocationFunction(int, Enum):
+    """The type of well location object to be created."""
+
+    BASE = auto()
+    LIQUID_HANDLING = auto()
+    PICK_UP_TIP = auto()
+    DROP_TIP = auto()
+
+
+# This is deliberately a separate type from Vec3f to let components default to 0.
+class WellOffset(BaseModel):
+    """An offset vector in (x, y, z)."""
+
+    x: float = 0
+    y: float = 0
+    z: float = 0
+
+
+class WellLocation(BaseModel):
+    """A relative location in reference to a well's location."""
+
+    origin: WellOrigin = WellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+    volumeOffset: float = Field(
+        default=0.0,
+        description="""A volume of liquid, in µL, to offset the z-axis offset.""",
+    )
+
+
+class LiquidHandlingWellLocation(BaseModel):
+    """A relative location in reference to a well's location.
+
+    To be used with commands that handle liquids.
+    """
+
+    origin: WellOrigin = WellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+    volumeOffset: Union[float, Literal["operationVolume"]] = Field(
+        default=0.0,
+        description="""A volume of liquid, in µL, to offset the z-axis offset. When "operationVolume" is specified, this volume is pulled from the command volume parameter.""",
+    )
+
+
+class PickUpTipWellLocation(BaseModel):
+    """A relative location in reference to a well's location.
+
+    To be used for picking up tips.
+    """
+
+    origin: PickUpTipWellOrigin = PickUpTipWellOrigin.TOP
+    offset: WellOffset = Field(default_factory=WellOffset)
+
+
+class DropTipWellLocation(BaseModel):
+    """Like WellLocation, but for dropping tips.
+
+    Unlike a typical WellLocation, the location for a drop tip
+    defaults to location based on the tip length rather than the well's top.
+    """
+
+    origin: DropTipWellOrigin = DropTipWellOrigin.DEFAULT
+    offset: WellOffset = Field(default_factory=WellOffset)
+
+
+WellLocationType = Union[
+    WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
+    DropTipWellLocation,
+]

opentrons/protocol_reader/extract_labware_definitions.py

@@ -6,7 +6,10 @@ from typing import List
 
 import anyio
 
-from opentrons.protocols.models import LabwareDefinition
+from opentrons_shared_data.labware.labware_definition import (
+    LabwareDefinition,
+    labware_definition_type_adapter,
+)
 
 from .protocol_source import ProtocolFileRole, ProtocolSource, ProtocolType
 
@@ -42,7 +45,7 @@ async def extract_labware_definitions(
 
 async def _extract_from_labware_file(path: Path) -> LabwareDefinition:
     def _do_parse() -> LabwareDefinition:
-        return LabwareDefinition.model_validate_json(path.read_bytes())
+        return labware_definition_type_adapter.validate_json(path.read_bytes())
 
     return await anyio.to_thread.run_sync(_do_parse)
 
@@ -55,7 +58,8 @@ async def _extract_from_json_protocol_file(path: Path) -> List[LabwareDefinition
             # which require this labwareDefinitions key.
             unvalidated_definitions = json_contents["labwareDefinitions"].values()
             validated_definitions = [
-                LabwareDefinition.model_validate(u) for u in unvalidated_definitions
+                labware_definition_type_adapter.validate_python(u)
+                for u in unvalidated_definitions
             ]
             return validated_definitions
 

opentrons/protocol_reader/file_format_validator.py

@@ -6,7 +6,9 @@ from typing import Iterable
 import anyio
 from pydantic import ValidationError as PydanticValidationError
 
-from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons_shared_data.labware.labware_definition import (
+    labware_definition_type_adapter,
+)
 from opentrons_shared_data.protocol.models import (
     ProtocolSchemaV6 as JsonProtocolV6,
     ProtocolSchemaV7 as JsonProtocolV7,
@@ -14,7 +16,7 @@ from opentrons_shared_data.protocol.models import (
 )
 from opentrons_shared_data.errors.exceptions import PythonException
 
-from opentrons.protocols.models import JsonProtocol as JsonProtocolUpToV5
+from opentrons.protocols.models.json_protocol import Model as JsonProtocolUpToV5
 
 from .file_identifier import (
     IdentifiedFile,
@@ -60,7 +62,7 @@ class FileFormatValidator:
 async def _validate_labware_definition(info: IdentifiedLabwareDefinition) -> None:
     def validate_sync() -> None:
         try:
-            LabwareDefinition.model_validate(info.unvalidated_json)
+            labware_definition_type_adapter.validate_python(info.unvalidated_json)
         except PydanticValidationError as e:
             raise FileFormatValidationError(
                 message=f"{info.original_file.name} could not be read as a labware definition.",

opentrons/protocol_runner/json_translator.py

@@ -20,7 +20,7 @@ from opentrons_shared_data.errors.exceptions import InvalidProtocolData, PythonE
 from opentrons.types import MountType
 from opentrons.protocol_engine import (
     commands as pe_commands,
-    LabwareLocation,
+    LoadableLabwareLocation,
     ModuleModel,
     DeckSlotLocation,
     Liquid,
@@ -37,7 +37,9 @@ class CommandTranslatorError(Exception):
 # Each time a TypeAdapter is instantiated, it will construct a new validator and
 # serializer. To improve performance, TypeAdapters are instantiated once.
 # See https://docs.pydantic.dev/latest/concepts/performance/#typeadapter-instantiated-once
-LabwareLocationAdapter: TypeAdapter[LabwareLocation] = TypeAdapter(LabwareLocation)
+LabwareLocationAdapter: TypeAdapter[LoadableLabwareLocation] = TypeAdapter(
+    LoadableLabwareLocation
+)
 CommandAnnotationAdapter: TypeAdapter[CommandAnnotation] = TypeAdapter(
     CommandAnnotation
 )

opentrons/protocol_runner/legacy_command_mapper.py

@@ -38,7 +38,9 @@ from opentrons.protocol_engine.state.update_types import (
     StateUpdate,
 )
 
-from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons_shared_data.labware.labware_definition import (
+    labware_definition_type_adapter,
+)
 from opentrons_shared_data.errors import ErrorCodes, EnumeratedError, PythonException
 
 
@@ -659,10 +661,12 @@ class LegacyCommandMapper:
             notes=[],
             result=pe_commands.LoadLabwareResult.model_construct(
                 labwareId=labware_id,
-                definition=LabwareDefinition.model_validate(
+                definition=labware_definition_type_adapter.validate_python(
                     labware_load_info.labware_definition
                 ),
                 offsetId=labware_load_info.offset_id,
+                # These legacy json protocols don't get location sequences because
+                # to do so we'd have to go back and look up where the module gets loaded
             ),
         )
         queue_action = pe_actions.QueueCommandAction(

opentrons/protocol_runner/run_orchestrator.py

@@ -32,6 +32,7 @@ from ..protocol_engine.types import (
     PostRunHardwareState,
     EngineStatus,
     LabwareOffsetCreate,
+    LegacyLabwareOffsetCreate,
     LabwareOffset,
     DeckConfigurationType,
     RunTimeParameter,
@@ -346,7 +347,9 @@ class RunOrchestrator:
         """Get whether the run has stopped."""
         return self._protocol_engine.state_view.commands.get_is_stopped()
 
-    def add_labware_offset(self, request: LabwareOffsetCreate) -> LabwareOffset:
+    def add_labware_offset(
+        self, request: LabwareOffsetCreate | LegacyLabwareOffsetCreate
+    ) -> LabwareOffset:
         """Add a new labware offset to state."""
         return self._protocol_engine.add_labware_offset(request)
 

opentrons/protocols/advanced_control/transfers/common.py

@@ -1,6 +1,11 @@
 """Common functions between v1 transfer and liquid-class-based transfer."""
 import enum
-from typing import Iterable, Generator, Tuple, TypeVar, Literal
+import math
+from typing import Iterable, Generator, Tuple, TypeVar, Literal, List
+
+
+class NoLiquidClassPropertyError(ValueError):
+    """An error raised when a liquid class property cannot be found for a pipette/tip combination"""
 
 
 class TransferTipPolicyV2(enum.Enum):
@@ -33,6 +38,23 @@ def check_valid_volume_parameters(
         )
 
 
+def check_valid_liquid_class_volume_parameters(
+    aspirate_volume: float, air_gap: float, disposal_volume: float, max_volume: float
+) -> None:
+    if air_gap + aspirate_volume > max_volume:
+        raise ValueError(
+            f"Cannot have an air gap of {air_gap} µL for an aspiration of {aspirate_volume} µL"
+            f" with a max volume of {max_volume} µL. Please adjust the retract air gap to fit within"
+            f" the bounds of the tip."
+        )
+    elif disposal_volume + aspirate_volume > max_volume:
+        raise ValueError(
+            f"Cannot have a dispense volume of {disposal_volume} µL for an aspiration of {aspirate_volume} µL"
+            f" with a max volume of {max_volume} µL. Please adjust the dispense volume to fit within"
+            f" the bounds of the tip."
+        )
+
+
 def expand_for_volume_constraints(
     volumes: Iterable[float],
     targets: Iterable[Target],
@@ -54,3 +76,28 @@ def expand_for_volume_constraints(
             volume /= 2
             yield volume, target
         yield volume, target
+
+
+def _split_volume_equally(volume: float, max_volume: float) -> List[float]:
+    """
+    Splits a given volume into a list of volumes that are all less than or equal to max volume.
+
+    If volume provided is more than the max volume, the volumes will be split evenly.
+    """
+    if volume <= max_volume:
+        return [volume]
+    else:
+        iterations = math.ceil(volume / max_volume)
+        return [volume / iterations for _ in range(iterations)]
+
+
+def expand_for_volume_constraints_for_liquid_classes(
+    volumes: Iterable[float],
+    targets: Iterable[Target],
+    max_volume: float,
+) -> Generator[Tuple[float, "Target"], None, None]:
+    """Split a sequence of proposed transfers to keep each under the max volume, splitting larger ones equally."""
+    assert max_volume > 0
+    for volume, target in zip(volumes, targets):
+        for split_volume in _split_volume_equally(volume, max_volume):
+            yield split_volume, target

opentrons/protocols/advanced_control/transfers/transfer_liquid_utils.py

@@ -0,0 +1,204 @@
+"""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
+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_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:
+    - the location in question is below the target well location during aspirate/dispense or,
+    - 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 a warning and no error is raised.
+    """
+    if location.point.z < well_location.point.z:
+        raise RuntimeError(
+            f"Received {location_check_descriptors.location_type} location of {location}"
+            f" and {location_check_descriptors.pipetting_action} location of {well_location}."
+            f" {location_check_descriptors.location_type.capitalize()} location z should not be lower"
+            f" than the {location_check_descriptors.pipetting_action} location z."
+        )
+    try:
+        liquid_height_from_bottom = well_core.current_liquid_height()
+    except LiquidHeightUnknownError:
+        liquid_height_from_bottom = None
+    if liquid_height_from_bottom is not None:
+        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 a warning.
+        logger.warning(
+            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 because"
+            f" liquid was not loaded in this well using `load_liquid`."
+            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,
+) -> 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)
+    else:
+        raise ValueError("Unsupported tip configuration for well grouping")
+
+
+def _group_wells_for_nozzle_configuration(  # noqa: C901
+    targets: List[Well], nozzle_map: NozzleMapInterface
+) -> 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(
+                    "Could not resolve wells provided to pipette's nozzle configuration. "
+                    "Please ensure wells are ordered to match pipette's nozzle layout."
+                )
+
+            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(
+                    "Could not resolve wells provided to pipette's nozzle configuration. "
+                    "Please ensure wells are ordered to match pipette's nozzle layout."
+                )
+        # 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(
+            "Could not target all wells provided without aspirating or dispensing from other wells. "
+            f"Other wells that would be targeted: {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

opentrons/protocols/api_support/definitions.py

@@ -1,6 +1,6 @@
 from .types import APIVersion
 
-MAX_SUPPORTED_VERSION = APIVersion(2, 22)
+MAX_SUPPORTED_VERSION = APIVersion(2, 23)
 """The maximum supported protocol API version in this release."""
 
 MIN_SUPPORTED_VERSION = APIVersion(2, 0)

opentrons/protocols/api_support/instrument.py

@@ -2,7 +2,7 @@ import logging
 from typing import Optional, Any
 
 from opentrons_shared_data.labware.types import (
-    LabwareDefinition as LabwareDefinitionDict,
+    LabwareDefinition2 as LabwareDefinition2Dict,
 )
 
 from opentrons import types
@@ -56,7 +56,7 @@ def validate_blowout_location(
 
 
 def tip_length_for(
-    pipette: PipetteDict, tip_rack_definition: LabwareDefinitionDict
+    pipette: PipetteDict, tip_rack_definition: LabwareDefinition2Dict
 ) -> float:
     """Get the tip length, including overlap, for a tip from this rack"""
     try:
@@ -99,7 +99,20 @@ def validate_tiprack(
         gen_lookup = (
             "FLEX" if ("flex" in instr_metadata or "96" in instr_metadata) else "OT2"
         )
-        valid_vols = VALID_PIP_TIPRACK_VOL[gen_lookup][instrument_name.split("_")[0]]
+
+        # 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}"