opentrons 8.3.1a1__py2.py3-none-any.whl → 8.4.0a1__py2.py3-none-any.whl

opentrons/protocol_engine/types/labware.py

@@ -0,0 +1,110 @@
+"""Protocol engine types to do with labware."""
+
+from __future__ import annotations
+
+from typing import Optional
+from dataclasses import dataclass
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from .location import LabwareLocation
+from .labware_offset_location import (
+    LegacyLabwareOffsetLocation,
+    LabwareOffsetLocationSequence,
+)
+from .labware_offset_vector import LabwareOffsetVector
+from .util import Vec3f
+
+
+class OverlapOffset(Vec3f):
+    """Offset representing overlap space of one labware on top of another labware or module."""
+
+
+class LabwareOffset(BaseModel):
+    """An offset that the robot adds to a pipette's position when it moves to a labware.
+
+    During the run, if a labware is loaded whose definition URI and location
+    both match what's found here, the given offset will be added to all
+    pipette movements that use that labware as a reference point.
+    """
+
+    id: str = Field(..., description="Unique labware offset record identifier.")
+    createdAt: datetime = Field(..., description="When this labware offset was added.")
+    definitionUri: str = Field(..., description="The URI for the labware's definition.")
+    location: LegacyLabwareOffsetLocation = Field(
+        ...,
+        description="Where the labware is located on the robot. Deprecated and present only for backwards compatibility; cannot represent certain locations. Use locationSequence instead.",
+    )
+    locationSequence: Optional[LabwareOffsetLocationSequence] = Field(
+        default=None,
+        description="Where the labware is located on the robot. Can represent all locations, but may not be present for older runs.",
+    )
+    vector: LabwareOffsetVector = Field(
+        ...,
+        description="The offset applied to matching labware.",
+    )
+
+
+class LegacyLabwareOffsetCreate(BaseModel):
+    """Create request data for a labware offset with a legacy location field."""
+
+    definitionUri: str = Field(..., description="The URI for the labware's definition.")
+    location: LegacyLabwareOffsetLocation = Field(
+        ...,
+        description="Where the labware is located on the robot.",
+    )
+    vector: LabwareOffsetVector = Field(
+        ...,
+        description="The offset applied to matching labware.",
+    )
+
+
+class LabwareOffsetCreate(BaseModel):
+    """Create request data for a labware offset with a modern location sequence."""
+
+    definitionUri: str = Field(..., description="The URI for the labware's definition.")
+    locationSequence: LabwareOffsetLocationSequence = Field(
+        ..., description="Where the labware is located on the robot."
+    )
+    vector: LabwareOffsetVector = Field(
+        ..., description="The offset applied to matching labware."
+    )
+
+
+@dataclass(frozen=True)
+class LabwareOffsetCreateInternal:
+    """An internal-only labware offset creator that captures both old and new location arguments."""
+
+    definitionUri: str
+    locationSequence: LabwareOffsetLocationSequence
+    legacyLocation: LegacyLabwareOffsetLocation
+    vector: LabwareOffsetVector
+
+
+class LoadedLabware(BaseModel):
+    """A labware that has been loaded."""
+
+    id: str
+    loadName: str
+    definitionUri: str
+    location: LabwareLocation = Field(
+        ..., description="The labware's current location."
+    )
+    lid_id: Optional[str] = Field(
+        None,
+        description=("Labware ID of a Lid currently loaded on top of the labware."),
+    )
+    offsetId: Optional[str] = Field(
+        None,
+        description=(
+            "An ID referencing the labware offset"
+            " that applies to this labware placement."
+            " Null or undefined means no offset was provided for this load,"
+            " so the default of (0, 0, 0) will be used."
+        ),
+    )
+    displayName: Optional[str] = Field(
+        None,
+        description="A user-specified display name for this labware, if provided.",
+    )

opentrons/protocol_engine/types/labware_movement.py

@@ -0,0 +1,22 @@
+"""Protocol Engine types to do with moving labware."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+from .labware_offset_vector import LabwareOffsetVector
+
+
+class LabwareMovementStrategy(str, Enum):
+    """Strategy to use for labware movement."""
+
+    USING_GRIPPER = "usingGripper"
+    MANUAL_MOVE_WITH_PAUSE = "manualMoveWithPause"
+    MANUAL_MOVE_WITHOUT_PAUSE = "manualMoveWithoutPause"
+
+
+class LabwareMovementOffsetData(BaseModel):
+    """Offsets to be used during labware movement."""
+
+    pickUpOffset: LabwareOffsetVector
+    dropOffset: LabwareOffsetVector

opentrons/protocol_engine/types/labware_offset_location.py

@@ -0,0 +1,108 @@
+"""Protocol engine types for legacy labware offset locations.
+
+This is its own module to fix circular imports.
+"""
+
+from typing import Optional, Literal, Annotated
+
+from pydantic import BaseModel, Field
+
+from opentrons.types import DeckSlotName
+
+from .module import ModuleModel
+
+
+class OnLabwareOffsetLocationSequenceComponent(BaseModel):
+    """Offset location sequence component for a labware on another labware."""
+
+    kind: Literal["onLabware"] = "onLabware"
+    labwareUri: str = Field(
+        ...,
+        description="The definition URI of a labware that a labware can be loaded onto.",
+    )
+
+
+class OnModuleOffsetLocationSequenceComponent(BaseModel):
+    """Offset location sequence component for a labware on a module."""
+
+    kind: Literal["onModule"] = "onModule"
+    moduleModel: ModuleModel = Field(
+        ..., description="The model of a module that a labware can be loaded on to."
+    )
+
+
+class OnAddressableAreaOffsetLocationSequenceComponent(BaseModel):
+    """Offset location sequence component for a labware on an addressable area."""
+
+    kind: Literal["onAddressableArea"] = "onAddressableArea"
+    addressableAreaName: str = Field(
+        ...,
+        description=(
+            'The ID of an addressable area that a labware or module can be loaded onto, such as (on the OT-2) "2" '
+            'or (on the Flex) "C1". '
+            "\n\n"
+            "On the Flex, this field must be correct for the kind of entity it hosts. For instance, if the prior entity "
+            "in the location sequence is an `OnModuleOffsetLocationSequenceComponent(moduleModel=temperatureModuleV2)`, "
+            "this entity must be temperatureModuleV2NN where NN is the slot name in which the module resides. "
+        ),
+    )
+
+
+LabwareOffsetLocationSequenceComponentsUnion = (
+    OnLabwareOffsetLocationSequenceComponent
+    | OnModuleOffsetLocationSequenceComponent
+    | OnAddressableAreaOffsetLocationSequenceComponent
+)
+
+LabwareOffsetLocationSequenceComponents = Annotated[
+    LabwareOffsetLocationSequenceComponentsUnion, Field(discriminator="kind")
+]
+
+LabwareOffsetLocationSequence = list[LabwareOffsetLocationSequenceComponents]
+
+
+class LegacyLabwareOffsetLocation(BaseModel):
+    """Parameters describing when a given offset may apply to a given labware load."""
+
+    slotName: DeckSlotName = Field(
+        ...,
+        description=(
+            "The deck slot where the protocol will load the labware."
+            " Or, if the protocol will load the labware on a module,"
+            " the deck slot where the protocol will load that module."
+            "\n\n"
+            # This description should be kept in sync with DeckSlotLocation.slotName.
+            'The plain numbers like `"5"` are for the OT-2,'
+            ' and the coordinates like `"C2"` are for the Flex.'
+            "\n\n"
+            "When you provide one of these values, you can use either style."
+            " It will automatically be converted to match the robot."
+            "\n\n"
+            "When one of these values is returned, it will always match the robot."
+        ),
+    )
+    moduleModel: Optional[ModuleModel] = Field(
+        None,
+        description=(
+            "The model of the module that the labware will be loaded onto,"
+            " if applicable."
+            "\n\n"
+            "Because of module compatibility, the model that the protocol requests"
+            " may not be exactly the same"
+            " as what it will find physically connected during execution."
+            " For this labware offset to apply,"
+            " this field must be the *requested* model, not the connected one."
+            " You can retrieve this from a `loadModule` command's `params.model`"
+            " in the protocol's analysis."
+        ),
+    )
+    definitionUri: Optional[str] = Field(
+        None,
+        description=(
+            "The definition URI of a labware that a labware can be loaded onto,"
+            " if applicable."
+            "\n\n"
+            "This can be combined with moduleModel if the labware is loaded on top of"
+            " an adapter that is loaded on a module."
+        ),
+    )

opentrons/protocol_engine/types/labware_offset_vector.py

@@ -0,0 +1,33 @@
+"""Protocol engine types for labware offset vectors.
+
+This is a separate module to avoid circular imports.
+"""
+from __future__ import annotations
+from typing import Any
+
+from pydantic import BaseModel
+
+
+# TODO(mm, 2022-11-07): Deduplicate with Vec3f.
+class LabwareOffsetVector(BaseModel):
+    """Offset, in deck coordinates from nominal to actual position."""
+
+    x: float
+    y: float
+    z: float
+
+    def __add__(self, other: Any) -> LabwareOffsetVector:
+        """Adds two vectors together."""
+        if not isinstance(other, LabwareOffsetVector):
+            return NotImplemented
+        return LabwareOffsetVector(
+            x=self.x + other.x, y=self.y + other.y, z=self.z + other.z
+        )
+
+    def __sub__(self, other: Any) -> LabwareOffsetVector:
+        """Subtracts two vectors."""
+        if not isinstance(other, LabwareOffsetVector):
+            return NotImplemented
+        return LabwareOffsetVector(
+            x=self.x - other.x, y=self.y - other.y, z=self.z - other.z
+        )

opentrons/protocol_engine/types/liquid.py

@@ -0,0 +1,40 @@
+"""Protocol engine types to do with liquids."""
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal, Optional
+
+from pydantic import RootModel, BaseModel, Field
+
+
+class HexColor(RootModel[str]):
+    """Hex color representation."""
+
+    root: str = Field(pattern=r"^#(?:[0-9a-fA-F]{3,4}){1,2}$")
+
+
+EmptyLiquidId = Literal["EMPTY"]
+LiquidId = str | EmptyLiquidId
+
+
+class Liquid(BaseModel):
+    """Payload required to create a liquid."""
+
+    id: str
+    displayName: str
+    description: str
+    displayColor: Optional[HexColor] = None
+
+
+class FluidKind(str, Enum):
+    """A kind of fluid that can be inside a pipette."""
+
+    LIQUID = "LIQUID"
+    AIR = "AIR"
+
+
+@dataclass(frozen=True)
+class AspiratedFluid:
+    """Fluid inside a pipette."""
+
+    kind: FluidKind
+    volume: float

opentrons/protocol_engine/types/liquid_class.py

@@ -0,0 +1,59 @@
+"""Protocol engine types to do with liquid classes."""
+from typing import Any
+from pydantic import Field
+
+from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    ByTipTypeSetting,
+)
+
+
+class LiquidClassRecord(ByTipTypeSetting, frozen=True):
+    """LiquidClassRecord is our internal representation of an (immutable) liquid class.
+
+    Conceptually, a liquid class record is the tuple (name, pipette, tip, transfer properties).
+    We consider two liquid classes to be the same if every entry in that tuple is the same; and liquid
+    classes are different if any entry in the tuple is different.
+
+    This class defines the tuple via inheritance so that we can reuse the definitions from shared_data.
+    """
+
+    liquidClassName: str = Field(
+        ...,
+        description="Identifier for the liquid of this liquid class, e.g. glycerol50.",
+    )
+    pipetteModel: str = Field(
+        ...,
+        description="Identifier for the pipette of this liquid class.",
+    )
+    # The other fields like tiprack ID, aspirate properties, etc. are pulled in from ByTipTypeSetting.
+
+    def __hash__(self) -> int:
+        """Hash function for LiquidClassRecord."""
+        # Within the Protocol Engine, LiquidClassRecords are immutable, and we'd like to be able to
+        # look up LiquidClassRecords by value, which involves hashing. However, Pydantic does not
+        # generate a usable hash function if any of the subfields (like Coordinate) are not frozen.
+        # So we have to implement the hash function ourselves.
+        # Our strategy is to recursively convert this object into a list of (key, value) tuples.
+        def dict_to_tuple(d: dict[str, Any]) -> tuple[tuple[str, Any], ...]:
+            return tuple(
+                (
+                    field_name,
+                    dict_to_tuple(value)
+                    if isinstance(value, dict)
+                    else tuple(value)
+                    if isinstance(value, list)
+                    else value,
+                )
+                for field_name, value in d.items()
+            )
+
+        return hash(dict_to_tuple(self.model_dump()))
+
+
+class LiquidClassRecordWithId(LiquidClassRecord, frozen=True):
+    """A LiquidClassRecord with its ID, for use in summary lists."""
+
+    liquidClassId: str = Field(
+        ...,
+        description="Unique identifier for this liquid class.",
+    )

opentrons/protocol_engine/types/liquid_handling.py

@@ -0,0 +1,13 @@
+"""Protocol engine types to do with liquid handling."""
+
+from dataclasses import dataclass
+from typing import Dict
+
+
+@dataclass
+class FlowRates:
+    """Default and current flow rates for a pipette."""
+
+    default_blow_out: Dict[str, float]
+    default_aspirate: Dict[str, float]
+    default_dispense: Dict[str, float]

opentrons/protocol_engine/types/liquid_level_detection.py

@@ -0,0 +1,137 @@
+"""Protocol Engine types to do with liquid level detection."""
+from __future__ import annotations
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Optional, List
+from pydantic import BaseModel, model_serializer, field_validator
+
+
+class SimulatedProbeResult(BaseModel):
+    """A sentinel value to substitute for the resulting volume/height of a liquid probe during simulation."""
+
+    operations_after_probe: List[float] = []
+    net_liquid_exchanged_after_probe: float = 0.0
+
+    @model_serializer
+    def serialize_model(self) -> str:
+        """Serialize instances of this class as a string."""
+        return "SimulatedProbeResult"
+
+    def __add__(
+        self, other: float | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass addition and just return self."""
+        return self
+
+    def __sub__(
+        self, other: float | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass subtraction and just return self."""
+        return self
+
+    def __radd__(
+        self, other: float | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass addition and just return self."""
+        return self
+
+    def __rsub__(
+        self, other: float | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass subtraction and just return self."""
+        return self
+
+    def __gt__(self, other: float | SimulatedProbeResult) -> bool:
+        """Bypass 'greater than' and just return self."""
+        return True
+
+    def __lt__(self, other: float | SimulatedProbeResult) -> bool:
+        """Bypass 'less than' and just return self."""
+        return False
+
+    def __ge__(self, other: float | SimulatedProbeResult) -> bool:
+        """Bypass 'greater than or eaqual to' and just return self."""
+        return True
+
+    def __le__(self, other: float | SimulatedProbeResult) -> bool:
+        """Bypass 'less than or equal to' and just return self."""
+        return False
+
+    def __eq__(self, other: object) -> bool:
+        """A SimulatedProbeResult should only be equal to the same instance of its class."""
+        if not isinstance(other, SimulatedProbeResult):
+            return False
+        return self is other
+
+    def __neq__(self, other: object) -> bool:
+        """A SimulatedProbeResult should only be equal to the same instance of its class."""
+        if not isinstance(other, SimulatedProbeResult):
+            return True
+        return self is not other
+
+    def simulate_probed_aspirate_dispense(self, volume: float) -> None:
+        """Record the current state of aspirate/dispense calls."""
+        self.net_liquid_exchanged_after_probe += volume
+        self.operations_after_probe.append(volume)
+
+
+LiquidTrackingType = SimulatedProbeResult | float
+
+
+class LoadedVolumeInfo(BaseModel):
+    """A well's liquid volume, initialized by a LoadLiquid, updated by Aspirate and Dispense."""
+
+    volume: LiquidTrackingType | None = None
+    last_loaded: datetime
+    operations_since_load: int
+
+
+class ProbedHeightInfo(BaseModel):
+    """A well's liquid height, initialized by a LiquidProbe, cleared by Aspirate and Dispense."""
+
+    height: LiquidTrackingType | None = None
+    last_probed: datetime
+
+
+class ProbedVolumeInfo(BaseModel):
+    """A well's liquid volume, initialized by a LiquidProbe, updated by Aspirate and Dispense."""
+
+    volume: LiquidTrackingType | None = None
+    last_probed: datetime
+    operations_since_probe: int
+
+
+class WellInfoSummary(BaseModel):
+    """Payload for a well's liquid info in StateSummary."""
+
+    # TODO(cm): 3/21/25: refactor SimulatedLiquidProbe in a way that
+    # doesn't require models like this one that are just using it to
+    # need a custom validator
+    @field_validator("probed_height", "probed_volume", mode="before")
+    @classmethod
+    def validate_simulated_probe_result(
+        cls, input_val: object
+    ) -> LiquidTrackingType | None:
+        """Return the appropriate input to WellInfoSummary from json data."""
+        if input_val is None:
+            return None
+        if isinstance(input_val, LiquidTrackingType):
+            return input_val
+        if isinstance(input_val, str) and input_val == "SimulatedProbeResult":
+            return SimulatedProbeResult()
+        raise ValueError(f"Invalid input value {input_val} to WellInfoSummary")
+
+    labware_id: str
+    well_name: str
+    loaded_volume: Optional[float] = None
+    probed_height: LiquidTrackingType | None = None
+    probed_volume: LiquidTrackingType | None = None
+
+
+@dataclass
+class WellLiquidInfo:
+    """Tracked and sensed information about liquid in a well."""
+
+    probed_height: Optional[ProbedHeightInfo]
+    loaded_volume: Optional[LoadedVolumeInfo]
+    probed_volume: Optional[ProbedVolumeInfo]