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

opentrons/protocol_engine/types/location.py

@@ -0,0 +1,193 @@
+"""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 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 | 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,269 @@
+"""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 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
+    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.
+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(
+        ...,
+        description="Module type (Temperature/Magnetic/Thermocycler)",
+    )
+
+    model: ModuleModel = Field(..., description="Model name of the module")
+
+    labwareOffset: LabwareOffsetVector = Field(
+        ...,
+        description="Labware offset in x, y, z.",
+    )
+
+    dimensions: ModuleDimensions = Field(..., description="Module dimension")
+
+    calibrationPoint: ModuleCalibrationPoint = Field(
+        ...,
+        description="Calibration point of module.",
+    )
+
+    displayName: str = Field(..., description="Display name.")
+
+    quirks: List[str] = Field(..., description="Module quirks")
+
+    # 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(
+        ...,
+        description="Dictionary of transforms for each slot.",
+    )
+
+    compatibleWith: List[ModuleModel] = Field(
+        ...,
+        description="List of module models this model is compatible with.",
+    )
+    gripperOffsets: Optional[Dict[str, LabwareMovementOffsetData]] = Field(
+        default_factory=dict,
+        description="Offsets to use for labware movement using gripper",
+    )
+
+
+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"

opentrons/protocol_engine/types/partial_tip_configuration.py

@@ -0,0 +1,76 @@
+"""Protocol engine types to do with partial tip configurations."""
+
+from typing import Literal, Union
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+NOZZLE_NAME_REGEX = r"[A-Z]\d{1,2}"
+PRIMARY_NOZZLE_LITERAL = Literal["A1", "H1", "A12", "H12"]
+
+
+class AllNozzleLayoutConfiguration(BaseModel):
+    """All basemodel to represent a reset to the nozzle configuration. Sending no parameters resets to default."""
+
+    style: Literal["ALL"] = "ALL"
+
+
+class SingleNozzleLayoutConfiguration(BaseModel):
+    """Minimum information required for a new nozzle configuration."""
+
+    style: Literal["SINGLE"] = "SINGLE"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class RowNozzleLayoutConfiguration(BaseModel):
+    """Minimum information required for a new nozzle configuration."""
+
+    style: Literal["ROW"] = "ROW"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class ColumnNozzleLayoutConfiguration(BaseModel):
+    """Information required for nozzle configurations of type ROW and COLUMN."""
+
+    style: Literal["COLUMN"] = "COLUMN"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+
+
+class QuadrantNozzleLayoutConfiguration(BaseModel):
+    """Information required for nozzle configurations of type QUADRANT."""
+
+    style: Literal["QUADRANT"] = "QUADRANT"
+    primaryNozzle: PRIMARY_NOZZLE_LITERAL = Field(
+        ...,
+        description="The primary nozzle to use in the layout configuration. This nozzle will update the critical point of the current pipette. For now, this is also the back left corner of your rectangle.",
+    )
+    frontRightNozzle: str = Field(
+        ...,
+        pattern=NOZZLE_NAME_REGEX,
+        description="The front right nozzle in your configuration.",
+    )
+    backLeftNozzle: str = Field(
+        ...,
+        pattern=NOZZLE_NAME_REGEX,
+        description="The back left nozzle in your configuration.",
+    )
+
+
+NozzleLayoutConfigurationType = Union[
+    AllNozzleLayoutConfiguration,
+    SingleNozzleLayoutConfiguration,
+    ColumnNozzleLayoutConfiguration,
+    RowNozzleLayoutConfiguration,
+    QuadrantNozzleLayoutConfiguration,
+]

opentrons/protocol_engine/types/run_time_parameters.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+
+"""Protocol Engine types that have to do with runtime parameters."""
+
+from pathlib import Path
+from typing import Optional, Mapping, Union, Literal, Dict, List
+from pydantic import (
+    BaseModel,
+    Field,
+    StrictBool,
+    StrictFloat,
+    StrictInt,
+    StrictStr,
+)
+
+
+# TODO (spp, 2024-04-02): move all RTP types to runner
+class RTPBase(BaseModel):
+    """Parameters defined in a protocol."""
+
+    displayName: StrictStr = Field(..., description="Display string for the parameter.")
+    variableName: StrictStr = Field(
+        ..., description="Python variable name of the parameter."
+    )
+    description: Optional[StrictStr] = Field(
+        None, description="Detailed description of the parameter."
+    )
+    suffix: Optional[StrictStr] = Field(
+        None,
+        description="Units (like mL, mm/sec, etc) or a custom suffix for the parameter.",
+    )
+
+
+class NumberParameter(RTPBase):
+    """An integer parameter defined in a protocol."""
+
+    type: Literal["int", "float"] = Field(
+        ..., description="String specifying whether the number is an int or float type."
+    )
+    min: Union[StrictInt, StrictFloat] = Field(
+        ..., description="Minimum value that the number param is allowed to have."
+    )
+    max: Union[StrictInt, StrictFloat] = Field(
+        ..., description="Maximum value that the number param is allowed to have."
+    )
+    value: Union[StrictInt, StrictFloat] = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: Union[StrictInt, StrictFloat] = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class BooleanParameter(RTPBase):
+    """A boolean parameter defined in a protocol."""
+
+    type: Literal["bool"] = Field(
+        default="bool", description="String specifying the type of this parameter"
+    )
+    value: StrictBool = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: StrictBool = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class EnumChoice(BaseModel):
+    """Components of choices used in RTP Enum Parameters."""
+
+    displayName: StrictStr = Field(
+        ..., description="Display string for the param's choice."
+    )
+    value: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ..., description="Enum value of the param's choice."
+    )
+
+
+class EnumParameter(RTPBase):
+    """A string enum defined in a protocol."""
+
+    type: Literal["int", "float", "str"] = Field(
+        ...,
+        description="String specifying whether the parameter is an int or float or string type.",
+    )
+    choices: List[EnumChoice] = Field(
+        ..., description="List of valid choices for this parameter."
+    )
+    value: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ...,
+        description="The value assigned to the parameter; if not supplied by the client, will be assigned the default value.",
+    )
+    default: Union[StrictInt, StrictFloat, StrictStr] = Field(
+        ...,
+        description="Default value of the parameter, to be used when there is no client-specified value.",
+    )
+
+
+class FileInfo(BaseModel):
+    """A file UUID descriptor."""
+
+    id: str = Field(
+        ...,
+        description="The UUID identifier of the file stored on the robot.",
+    )
+    name: str = Field(..., description="Name of the file, including the extension.")
+
+
+class CSVParameter(RTPBase):
+    """A CSV file parameter defined in a protocol."""
+
+    type: Literal["csv_file"] = Field(
+        default="csv_file", description="String specifying the type of this parameter"
+    )
+    file: Optional[FileInfo] = Field(
+        default=None,
+        description="ID of the CSV file stored on the robot; to be used for fetching the CSV file."
+        " For local analysis this will most likely be empty.",
+    )
+
+
+RunTimeParameter = Union[NumberParameter, EnumParameter, BooleanParameter, CSVParameter]
+
+PrimitiveRunTimeParamValuesType = Mapping[
+    StrictStr, Union[StrictInt, StrictFloat, StrictBool, StrictStr]
+]  # update value types as more RTP types are added
+
+CSVRunTimeParamFilesType = Mapping[StrictStr, StrictStr]
+CSVRuntimeParamPaths = Dict[str, Path]

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