opentrons 8.6.0a1__py3-none-any.whl

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,191 @@
+"""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, Any
+from pydantic import BaseModel, model_serializer, model_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"
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_model(cls, data: object) -> Any:
+        """Handle deserializing from a simulated probe result."""
+        if isinstance(data, str) and data == "SimulatedProbeResult":
+            return {}
+        return data
+
+    def __add__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass addition and just return self."""
+        return self
+
+    def __sub__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass subtraction and just return self."""
+        return self
+
+    def __radd__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass addition and just return self."""
+        return self
+
+    def __rsub__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass subtraction and just return self."""
+        return self
+
+    def __mul__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass multiplication and just return self."""
+        return self
+
+    def __rmul__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass multiplication and just return self."""
+        return self
+
+    def __truediv__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass division and just return self."""
+        return self
+
+    def __rtruediv__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass division and just return self."""
+        return self
+
+    def __pow__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass exponent math and just return self."""
+        return self
+
+    def __rpow__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass exponent math and just return self."""
+        return self
+
+    def __mod__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass modulus and just return self."""
+        return self
+
+    def __rmod__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass modulus and just return self."""
+        return self
+
+    def __floordiv__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass floor division and just return self."""
+        return self
+
+    def __rfloordiv__(
+        self, other: float | int | SimulatedProbeResult
+    ) -> float | SimulatedProbeResult:
+        """Bypass floor division and just return self."""
+        return self
+
+    def __gt__(self, other: float | int | SimulatedProbeResult) -> bool:
+        """Bypass 'greater than' and just return self."""
+        return True
+
+    def __lt__(self, other: float | int | SimulatedProbeResult) -> bool:
+        """Bypass 'less than' and just return self."""
+        return False
+
+    def __ge__(self, other: float | int | SimulatedProbeResult) -> bool:
+        """Bypass 'greater than or eaqual to' and just return self."""
+        return True
+
+    def __le__(self, other: float | int | 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)
+
+
+# Work around https://github.com/pydantic/pydantic/issues/6830 - do not change the order of
+# this union
+LiquidTrackingType = float | SimulatedProbeResult
+
+
+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."""
+
+    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]

opentrons/protocol_engine/types/location.py

@@ -0,0 +1,194 @@
+"""Protocol engine types to deal with locating things on the deck."""
+
+from __future__ import annotations
+from typing import Literal, Union, TypeGuard
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.types import DeckSlotName, StagingSlotName
+
+
+class DeckSlotLocation(BaseModel):
+    """The location of something placed in a single deck slot."""
+
+    slotName: DeckSlotName = Field(
+        ...,
+        description=(
+            # This description should be kept in sync with LegacyLabwareOffsetLocation.slotName.
+            "A slot on the robot's deck."
+            "\n\n"
+            '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."
+        ),
+    )
+
+
+class StagingSlotLocation(BaseModel):
+    """The location of something placed in a single staging slot."""
+
+    slotName: StagingSlotName = Field(
+        ...,
+        description=(
+            # This description should be kept in sync with LegacyLabwareOffsetLocation.slotName.
+            "A slot on the robot's staging area."
+            "\n\n"
+            "These apply only to the Flex. The OT-2 has no staging slots."
+        ),
+    )
+
+
+class AddressableAreaLocation(BaseModel):
+    """The location of something place in an addressable area. This is a superset of deck slots."""
+
+    addressableAreaName: str = Field(
+        ...,
+        description=(
+            "The name of the addressable area that you want to use."
+            " Valid values are the `id`s of `addressableArea`s in the"
+            " [deck definition](https://github.com/Opentrons/opentrons/tree/edge/shared-data/deck)."
+        ),
+    )
+
+
+class ModuleLocation(BaseModel):
+    """The location of something placed atop a hardware module."""
+
+    moduleId: str = Field(
+        ...,
+        description="The ID of a loaded module from a prior `loadModule` command.",
+    )
+
+
+class OnLabwareLocation(BaseModel):
+    """The location of something placed atop another labware."""
+
+    labwareId: str = Field(
+        ...,
+        description="The ID of a loaded Labware from a prior `loadLabware` command.",
+    )
+
+
+class InStackerHopperLocation(BaseModel):
+    """The location of a labware in a stacker hopper."""
+
+    kind: Literal["inStackerHopper"] = "inStackerHopper"
+    moduleId: str = Field(
+        ..., description="The ID of the stacker in which this labware is."
+    )
+
+
+_OffDeckLocationType = Literal["offDeck"]
+_SystemLocationType = Literal["systemLocation"]
+OFF_DECK_LOCATION: _OffDeckLocationType = "offDeck"
+SYSTEM_LOCATION: _SystemLocationType = "systemLocation"
+
+
+def labware_location_is_off_deck(
+    location: LabwareLocation,
+) -> TypeGuard[_OffDeckLocationType]:
+    """Check if a location is an off deck location."""
+    return isinstance(location, str) and location == OFF_DECK_LOCATION
+
+
+def labware_location_is_system(
+    location: LabwareLocation,
+) -> TypeGuard[_SystemLocationType]:
+    """Check if a location is the system location."""
+    return isinstance(location, str) and location == SYSTEM_LOCATION
+
+
+class OnLabwareLocationSequenceComponent(BaseModel):
+    """Labware on another labware."""
+
+    kind: Literal["onLabware"] = "onLabware"
+    labwareId: str
+    lidId: str | SkipJsonSchema[None] = Field(None)
+
+
+class OnModuleLocationSequenceComponent(BaseModel):
+    """Labware on a module."""
+
+    kind: Literal["onModule"] = "onModule"
+    moduleId: str
+
+
+class OnAddressableAreaLocationSequenceComponent(BaseModel):
+    """Labware on an addressable area."""
+
+    kind: Literal["onAddressableArea"] = "onAddressableArea"
+    addressableAreaName: str
+
+
+class OnCutoutFixtureLocationSequenceComponent(BaseModel):
+    """Something on a deck cutout fixture."""
+
+    kind: Literal["onCutoutFixture"] = "onCutoutFixture"
+    possibleCutoutFixtureIds: list[str]
+    cutoutId: str
+
+
+class NotOnDeckLocationSequenceComponent(BaseModel):
+    """Labware on a system location."""
+
+    kind: Literal["notOnDeck"] = "notOnDeck"
+    logicalLocationName: _OffDeckLocationType | _SystemLocationType
+
+
+LabwareLocationSequence = list[
+    OnLabwareLocationSequenceComponent
+    | OnModuleLocationSequenceComponent
+    | OnAddressableAreaLocationSequenceComponent
+    | NotOnDeckLocationSequenceComponent
+    | OnCutoutFixtureLocationSequenceComponent
+    | InStackerHopperLocation
+]
+"""Labware location specifier."""
+
+LabwareLocation = Union[
+    DeckSlotLocation,
+    ModuleLocation,
+    OnLabwareLocation,
+    _OffDeckLocationType,
+    _SystemLocationType,
+    AddressableAreaLocation,
+    InStackerHopperLocation,
+]
+"""Union of all locations where it's legal to keep a labware."""
+
+LoadableLabwareLocation = Union[
+    DeckSlotLocation,
+    ModuleLocation,
+    OnLabwareLocation,
+    _OffDeckLocationType,
+    _SystemLocationType,
+    AddressableAreaLocation,
+]
+"""Union of all locations where it's legal to load a labware."""
+
+OnDeckLabwareLocation = Union[
+    DeckSlotLocation, ModuleLocation, OnLabwareLocation, AddressableAreaLocation
+]
+
+NonStackedLocation = Union[
+    DeckSlotLocation,
+    AddressableAreaLocation,
+    ModuleLocation,
+    _OffDeckLocationType,
+    _SystemLocationType,
+]
+"""Union of all locations where it's legal to keep a labware that can't be stacked on another labware"""
+
+
+# TODO(mm, 2022-11-07): Deduplicate with Vec3f.
+class DeckPoint(BaseModel):
+    """Coordinates of a point in deck space."""
+
+    x: float
+    y: float
+    z: float

opentrons/protocol_engine/types/module.py

@@ -0,0 +1,303 @@
+"""Protocol engine types to do with modules."""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from enum import Enum
+from typing import (
+    TypeGuard,
+    Literal,
+    Optional,
+    List,
+    Dict,
+    Any,
+    NamedTuple,
+)
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition, Extents
+from opentrons_shared_data.labware.types import LocatingFeatures
+
+from opentrons.hardware_control.modules import (
+    ModuleType as ModuleType,
+)
+
+from .location import DeckSlotLocation
+from .labware_offset_vector import LabwareOffsetVector
+from .labware_movement import LabwareMovementOffsetData
+
+
+# TODO(mc, 2022-01-18): use opentrons_shared_data.module.types.ModuleModel
+class ModuleModel(str, Enum):
+    """All available modules' models."""
+
+    TEMPERATURE_MODULE_V1 = "temperatureModuleV1"
+    TEMPERATURE_MODULE_V2 = "temperatureModuleV2"
+    MAGNETIC_MODULE_V1 = "magneticModuleV1"
+    MAGNETIC_MODULE_V2 = "magneticModuleV2"
+    THERMOCYCLER_MODULE_V1 = "thermocyclerModuleV1"
+    THERMOCYCLER_MODULE_V2 = "thermocyclerModuleV2"
+    HEATER_SHAKER_MODULE_V1 = "heaterShakerModuleV1"
+    MAGNETIC_BLOCK_V1 = "magneticBlockV1"
+    ABSORBANCE_READER_V1 = "absorbanceReaderV1"
+    FLEX_STACKER_MODULE_V1 = "flexStackerModuleV1"
+
+    def as_type(self) -> ModuleType:
+        """Get the ModuleType of this model."""
+        if ModuleModel.is_temperature_module_model(self):
+            return ModuleType.TEMPERATURE
+        elif ModuleModel.is_magnetic_module_model(self):
+            return ModuleType.MAGNETIC
+        elif ModuleModel.is_thermocycler_module_model(self):
+            return ModuleType.THERMOCYCLER
+        elif ModuleModel.is_heater_shaker_module_model(self):
+            return ModuleType.HEATER_SHAKER
+        elif ModuleModel.is_magnetic_block(self):
+            return ModuleType.MAGNETIC_BLOCK
+        elif ModuleModel.is_absorbance_reader(self):
+            return ModuleType.ABSORBANCE_READER
+        elif ModuleModel.is_flex_stacker(self):
+            return ModuleType.FLEX_STACKER
+
+        assert False, f"Invalid ModuleModel {self}"
+
+    @classmethod
+    def is_temperature_module_model(
+        cls, model: ModuleModel
+    ) -> TypeGuard[TemperatureModuleModel]:
+        """Whether a given model is a Temperature Module."""
+        return model in [cls.TEMPERATURE_MODULE_V1, cls.TEMPERATURE_MODULE_V2]
+
+    @classmethod
+    def is_magnetic_module_model(
+        cls, model: ModuleModel
+    ) -> TypeGuard[MagneticModuleModel]:
+        """Whether a given model is a Magnetic Module."""
+        return model in [cls.MAGNETIC_MODULE_V1, cls.MAGNETIC_MODULE_V2]
+
+    @classmethod
+    def is_thermocycler_module_model(
+        cls, model: ModuleModel
+    ) -> TypeGuard[ThermocyclerModuleModel]:
+        """Whether a given model is a Thermocycler Module."""
+        return model in [cls.THERMOCYCLER_MODULE_V1, cls.THERMOCYCLER_MODULE_V2]
+
+    @classmethod
+    def is_heater_shaker_module_model(
+        cls, model: ModuleModel
+    ) -> TypeGuard[HeaterShakerModuleModel]:
+        """Whether a given model is a Heater-Shaker Module."""
+        return model == cls.HEATER_SHAKER_MODULE_V1
+
+    @classmethod
+    def is_magnetic_block(cls, model: ModuleModel) -> TypeGuard[MagneticBlockModel]:
+        """Whether a given model is a Magnetic block."""
+        return model == cls.MAGNETIC_BLOCK_V1
+
+    @classmethod
+    def is_absorbance_reader(
+        cls, model: ModuleModel
+    ) -> TypeGuard[AbsorbanceReaderModel]:
+        """Whether a given model is an Absorbance Plate Reader."""
+        return model == cls.ABSORBANCE_READER_V1
+
+    @classmethod
+    def is_flex_stacker(cls, model: ModuleModel) -> TypeGuard[FlexStackerModuleModel]:
+        """Whether a given model is a Flex Stacker.."""
+        return model == cls.FLEX_STACKER_MODULE_V1
+
+
+TemperatureModuleModel = Literal[
+    ModuleModel.TEMPERATURE_MODULE_V1, ModuleModel.TEMPERATURE_MODULE_V2
+]
+MagneticModuleModel = Literal[
+    ModuleModel.MAGNETIC_MODULE_V1, ModuleModel.MAGNETIC_MODULE_V2
+]
+ThermocyclerModuleModel = Literal[
+    ModuleModel.THERMOCYCLER_MODULE_V1, ModuleModel.THERMOCYCLER_MODULE_V2
+]
+HeaterShakerModuleModel = Literal[ModuleModel.HEATER_SHAKER_MODULE_V1]
+MagneticBlockModel = Literal[ModuleModel.MAGNETIC_BLOCK_V1]
+AbsorbanceReaderModel = Literal[ModuleModel.ABSORBANCE_READER_V1]
+FlexStackerModuleModel = Literal[ModuleModel.FLEX_STACKER_MODULE_V1]
+
+
+class ModuleDimensions(BaseModel):
+    """Dimension type for modules."""
+
+    bareOverallHeight: float
+    overLabwareHeight: float
+    labwareInterfaceXDimension: Optional[float] = None
+    labwareInterfaceYDimension: Optional[float] = None
+    lidHeight: Optional[float] = None
+    maxStackerFillHeight: Optional[float] = None
+    maxStackerRetrievableHeight: Optional[float] = None
+
+
+# TODO(mm, 2022-11-07): Deduplicate with Vec3f.
+class ModuleCalibrationPoint(BaseModel):
+    """Calibration Point type for module definition."""
+
+    x: float
+    y: float
+    z: float
+
+
+# TODO(mm, 2023-04-13): Move to shared-data, so this binding can be maintained alongside the JSON
+# schema that it's sourced from. We already do that for labware definitions and JSON protocols.
+
+
+# See underlying JSON schema for documentation.
+class ModuleDefinition(BaseModel):
+    """A module definition conforming to module definition schema v3."""
+
+    # Note: This field is misleading.
+    #
+    # This class only models v3 definitions ("module/schemas/3"), not v2 ("module/schemas/2").
+    # labwareOffset is required to have a z-component, for example.
+    #
+    # When parsing from a schema v3 JSON definition into this model,
+    # the definition's `"$otSharedSchema": "module/schemas/3"` field will be thrown away
+    # because it has a dollar sign, which doesn't match this field.
+    # Then, this field will default to "module/schemas/2", because no value was provided.
+    #
+    # We should fix this field once Jira RSS-221 is resolved. RSS-221 makes it difficult to fix
+    # because robot-server has been storing and loading these bad fields in its database.
+    otSharedSchema: str = Field("module/schemas/2", description="The current schema.")
+
+    moduleType: ModuleType = Field(...)
+
+    model: ModuleModel = Field(...)
+
+    labwareOffset: LabwareOffsetVector = Field(...)
+
+    dimensions: ModuleDimensions = Field(...)
+
+    calibrationPoint: ModuleCalibrationPoint = Field(
+        ...,
+    )
+
+    displayName: str = Field(...)
+
+    quirks: List[str] = Field(...)
+
+    # In releases prior to https://github.com/Opentrons/opentrons/pull/11873 (v6.3.0),
+    # the matrices in slotTransforms were 3x3.
+    # After, they are 4x4, even though there was no schema version bump.
+    #
+    # Because old objects of this class, with the 3x3 matrices, were stored in robot-server's
+    # database, this field needs to stay typed loosely enough to support both sizes.
+    # We can fix this once Jira RSS-221 is resolved.
+    slotTransforms: Dict[str, Any] = Field(
+        ...,
+    )
+
+    compatibleWith: List[ModuleModel] = Field(
+        ...,
+    )
+    gripperOffsets: Optional[Dict[str, LabwareMovementOffsetData]] = Field(
+        default_factory=lambda: {},
+    )
+
+    features: LocatingFeatures = Field(
+        ...,
+    )
+
+    extents: Extents = Field(
+        ...,
+    )
+
+
+class LoadedModule(BaseModel):
+    """A module that has been loaded."""
+
+    id: str
+    model: ModuleModel
+    location: Optional[DeckSlotLocation] = None
+    serialNumber: Optional[str] = None
+
+
+class SpeedRange(NamedTuple):
+    """Minimum and maximum allowed speeds for a shaking module."""
+
+    min: int
+    max: int
+
+
+class TemperatureRange(NamedTuple):
+    """Minimum and maximum allowed temperatures for a heating module."""
+
+    min: float
+    max: float
+
+
+class HeaterShakerLatchStatus(Enum):
+    """Heater-Shaker latch status for determining pipette and labware movement errors."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class HeaterShakerMovementRestrictors:
+    """Shaking status, latch status and slot location for determining movement restrictions."""
+
+    plate_shaking: bool
+    latch_status: HeaterShakerLatchStatus
+    deck_slot: int
+
+
+ABSMeasureMode = Literal["single", "multi"]
+
+
+# TODO(mm, 2022-11-07): Deduplicate with Vec3f.
+class ModuleOffsetVector(BaseModel):
+    """Offset, in deck coordinates, from nominal to actual position of labware on a module."""
+
+    x: float
+    y: float
+    z: float
+
+
+@dataclass
+class ModuleOffsetData:
+    """Module calibration offset data."""
+
+    moduleOffsetVector: ModuleOffsetVector
+    location: DeckSlotLocation
+
+
+class StackerFillEmptyStrategy(str, Enum):
+    """Strategy to use for filling or emptying a stacker."""
+
+    MANUAL_WITH_PAUSE = "manualWithPause"
+    LOGICAL = "logical"
+
+
+class StackerStoredLabwareGroup(BaseModel):
+    """Represents one group of labware stored in a stacker hopper."""
+
+    primaryLabwareId: str
+    adapterLabwareId: str | SkipJsonSchema[None] = None
+    lidLabwareId: str | SkipJsonSchema[None] = None
+
+
+@dataclass
+class StackerPoolDefinition:
+    """Represents an internal configuraiton of stored labware."""
+
+    primaryLabwareDefinition: LabwareDefinition
+    adapterLabwareDefinition: LabwareDefinition | SkipJsonSchema[None] = None
+    lidLabwareDefinition: LabwareDefinition | SkipJsonSchema[None] = None
+
+
+class IdentifyColor(str, Enum):
+    """Module identify color."""
+
+    WHITE = "white"
+    RED = "red"
+    GREEN = "green"
+    BLUE = "blue"
+    YELLOW = "yellow"