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

opentrons/protocol_engine/types/__init__.py

@@ -0,0 +1,300 @@
+"""Public protocol engine value types and models."""
+
+from __future__ import annotations
+
+
+from opentrons_shared_data.pipette.types import LabwareUri
+from opentrons.hardware_control.modules import ModuleType
+
+
+from .run_time_parameters import (
+    NumberParameter,
+    BooleanParameter,
+    EnumParameter,
+    CSVParameter,
+    RunTimeParameter,
+    PrimitiveRunTimeParamValuesType,
+    CSVRunTimeParamFilesType,
+    CSVRuntimeParamPaths,
+    FileInfo,
+    EnumChoice,
+)
+
+from .command_annotations import (
+    SecondOrderCommandAnnotation,
+    CustomCommandAnnotation,
+    CommandAnnotation,
+)
+from .partial_tip_configuration import (
+    AllNozzleLayoutConfiguration,
+    SingleNozzleLayoutConfiguration,
+    RowNozzleLayoutConfiguration,
+    ColumnNozzleLayoutConfiguration,
+    QuadrantNozzleLayoutConfiguration,
+    NozzleLayoutConfigurationType,
+    PRIMARY_NOZZLE_LITERAL,
+)
+from .automatic_tip_selection import NextTipInfo, NoTipReason, NoTipAvailable
+from .instrument_sensors import InstrumentSensorId, TipPresenceStatus
+from .deck_configuration import (
+    AddressableOffsetVector,
+    PotentialCutoutFixture,
+    AreaType,
+    AddressableArea,
+    DeckConfigurationType,
+    DeckType,
+)
+from .liquid_class import LiquidClassRecord, LiquidClassRecordWithId
+from .module import (
+    ModuleModel,
+    TemperatureModuleModel,
+    MagneticModuleModel,
+    ThermocyclerModuleModel,
+    HeaterShakerModuleModel,
+    MagneticBlockModel,
+    AbsorbanceReaderModel,
+    FlexStackerModuleModel,
+    ModuleDimensions,
+    ModuleCalibrationPoint,
+    ModuleDefinition,
+    LoadedModule,
+    SpeedRange,
+    TemperatureRange,
+    HeaterShakerLatchStatus,
+    HeaterShakerMovementRestrictors,
+    ABSMeasureMode,
+    ModuleOffsetVector,
+    ModuleOffsetData,
+    StackerFillEmptyStrategy,
+)
+from .location import (
+    DeckSlotLocation,
+    StagingSlotLocation,
+    AddressableAreaLocation,
+    ModuleLocation,
+    OnLabwareLocation,
+    OFF_DECK_LOCATION,
+    SYSTEM_LOCATION,
+    LabwareLocation,
+    OnDeckLabwareLocation,
+    NonStackedLocation,
+    DeckPoint,
+    InStackerHopperLocation,
+    OnLabwareLocationSequenceComponent,
+    OnModuleLocationSequenceComponent,
+    OnAddressableAreaLocationSequenceComponent,
+    NotOnDeckLocationSequenceComponent,
+    OnCutoutFixtureLocationSequenceComponent,
+    LabwareLocationSequence,
+    LoadableLabwareLocation,
+    labware_location_is_system,
+    labware_location_is_off_deck,
+)
+from .labware import (
+    OverlapOffset,
+    LabwareOffset,
+    LabwareOffsetCreate,
+    LegacyLabwareOffsetCreate,
+    LabwareOffsetCreateInternal,
+    LoadedLabware,
+)
+from .liquid import HexColor, EmptyLiquidId, LiquidId, Liquid, FluidKind, AspiratedFluid
+from .labware_offset_location import (
+    LegacyLabwareOffsetLocation,
+    LabwareOffsetLocationSequence,
+    OnLabwareOffsetLocationSequenceComponent,
+    OnModuleOffsetLocationSequenceComponent,
+    OnAddressableAreaOffsetLocationSequenceComponent,
+    LabwareOffsetLocationSequenceComponents,
+)
+from .labware_offset_vector import LabwareOffsetVector
+from .well_position import (
+    WellOrigin,
+    PickUpTipWellOrigin,
+    DropTipWellOrigin,
+    WellOffset,
+    WellLocation,
+    LiquidHandlingWellLocation,
+    PickUpTipWellLocation,
+    DropTipWellLocation,
+    WellLocationType,
+    WellLocationFunction,
+)
+from .instrument import (
+    LoadedPipette,
+    CurrentAddressableArea,
+    CurrentWell,
+    CurrentPipetteLocation,
+    InstrumentOffsetVector,
+)
+from .execution import EngineStatus, PostRunHardwareState
+from .liquid_level_detection import (
+    LoadedVolumeInfo,
+    ProbedHeightInfo,
+    ProbedVolumeInfo,
+    WellInfoSummary,
+    WellLiquidInfo,
+    LiquidTrackingType,
+    SimulatedProbeResult,
+)
+from .liquid_handling import FlowRates
+from .labware_movement import LabwareMovementStrategy, LabwareMovementOffsetData
+from .tip import TipGeometry
+from .hardware_passthrough import MovementAxis, MotorAxis
+from .util import Vec3f, Dimensions
+
+__all__ = [
+    # Runtime parameters
+    "NumberParameter",
+    "BooleanParameter",
+    "EnumParameter",
+    "EnumChoice",
+    "CSVParameter",
+    "PrimitiveRunTimeParamValuesType",
+    "CSVRunTimeParamFilesType",
+    "CSVRuntimeParamPaths",
+    "FileInfo",
+    "RunTimeParameter",
+    # Command annotations
+    "SecondOrderCommandAnnotation",
+    "CustomCommandAnnotation",
+    "CommandAnnotation",
+    # Partial tip handling
+    "AllNozzleLayoutConfiguration",
+    "SingleNozzleLayoutConfiguration",
+    "RowNozzleLayoutConfiguration",
+    "ColumnNozzleLayoutConfiguration",
+    "QuadrantNozzleLayoutConfiguration",
+    "NozzleLayoutConfigurationType",
+    "PRIMARY_NOZZLE_LITERAL",
+    # Automatic tip selection
+    "NextTipInfo",
+    "NoTipReason",
+    "NoTipAvailable",
+    # Instrument sensors
+    "InstrumentSensorId",
+    "TipPresenceStatus",
+    # Deck configuration
+    "AddressableOffsetVector",
+    "PotentialCutoutFixture",
+    "AreaType",
+    "AddressableArea",
+    "DeckConfigurationType",
+    "DeckType",
+    # Liquid classes
+    "LiquidClassRecord",
+    "LiquidClassRecordWithId",
+    # Modules
+    "ModuleModel",
+    "ModuleType",
+    "TemperatureModuleModel",
+    "MagneticModuleModel",
+    "ThermocyclerModuleModel",
+    "HeaterShakerModuleModel",
+    "MagneticBlockModel",
+    "AbsorbanceReaderModel",
+    "FlexStackerModuleModel",
+    "ModuleDimensions",
+    "ModuleCalibrationPoint",
+    "ModuleDefinition",
+    "LoadedModule",
+    "SpeedRange",
+    "TemperatureRange",
+    "HeaterShakerLatchStatus",
+    "HeaterShakerMovementRestrictors",
+    "ABSMeasureMode",
+    "ModuleOffsetVector",
+    "ModuleOffsetData",
+    "StackerFillEmptyStrategy",
+    # Locations of things on deck
+    "DeckSlotLocation",
+    "StagingSlotLocation",
+    "AddressableAreaLocation",
+    "ModuleLocation",
+    "OnLabwareLocation",
+    "OFF_DECK_LOCATION",
+    "SYSTEM_LOCATION",
+    "LabwareLocation",
+    "OnDeckLabwareLocation",
+    "NonStackedLocation",
+    "DeckPoint",
+    "OffDeckLocationType",
+    "SystemLocationType",
+    "InStackerHopperLocation",
+    "OnLabwareLocationSequenceComponent",
+    "OnModuleLocationSequenceComponent",
+    "OnAddressableAreaLocationSequenceComponent",
+    "NotOnDeckLocationSequenceComponent",
+    "OnCutoutFixtureLocationSequenceComponent",
+    "LabwareLocationSequence",
+    "LoadableLabwareLocation",
+    "labware_location_is_off_deck",
+    "labware_location_is_system",
+    # Labware offset location
+    "LegacyLabwareOffsetLocation",
+    "LabwareOffsetLocationSequence",
+    "LabwareOffsetLocationSequenceComponents",
+    "OnLabwareOffsetLocationSequenceComponent",
+    "OnModuleOffsetLocationSequenceComponent",
+    "OnAddressableAreaOffsetLocationSequenceComponent",
+    # Labware offset vector
+    "LabwareOffsetVector",
+    # Labware
+    "OverlapOffset",
+    "LabwareOffset",
+    "LabwareOffsetCreate",
+    "LegacyLabwareOffsetCreate",
+    "LabwareOffsetCreateInternal",
+    "LoadedLabware",
+    "LabwareOffsetVector",
+    # Liquids
+    "HexColor",
+    "EmptyLiquidId",
+    "LiquidId",
+    "Liquid",
+    "FluidKind",
+    "AspiratedFluid",
+    # Well locations
+    "WellOrigin",
+    "PickUpTipWellOrigin",
+    "DropTipWellOrigin",
+    "WellOffset",
+    "WellLocation",
+    "LiquidHandlingWellLocation",
+    "PickUpTipWellLocation",
+    "DropTipWellLocation",
+    "WellLocationType",
+    "WellLocationFunction",
+    # Execution
+    "EngineStatus",
+    "PostRunHardwareState",
+    # Instruments
+    "LoadedPipette",
+    "CurrentAddressableArea",
+    "CurrentWell",
+    "CurrentPipetteLocation",
+    "InstrumentOffsetVector",
+    # Liquid level detection types
+    "LoadedVolumeInfo",
+    "ProbedHeightInfo",
+    "ProbedVolumeInfo",
+    "WellInfoSummary",
+    "WellLiquidInfo",
+    "LiquidTrackingType",
+    "SimulatedProbeResult",
+    # Liquid handling
+    "FlowRates",
+    # Labware movement
+    "LabwareMovementStrategy",
+    "LabwareMovementOffsetData",
+    # Tips
+    "TipGeometry",
+    # Hardware passthrough
+    "MovementAxis",
+    "MotorAxis",
+    # Utility types
+    "Vec3f",
+    "Dimensions",
+    # Convenience re-export
+    "LabwareUri",
+]

opentrons/protocol_engine/types/automatic_tip_selection.py

@@ -0,0 +1,39 @@
+"""Protocol engine types dealing with automatic tip selection."""
+from enum import Enum
+from typing import Optional
+
+from pydantic import (
+    BaseModel,
+    Field,
+)
+
+
+class NextTipInfo(BaseModel):
+    """Next available tip labware and well name data."""
+
+    labwareId: str = Field(
+        ...,
+        description="The labware ID of the tip rack where the next available tip(s) are located.",
+    )
+    tipStartingWell: str = Field(
+        ..., description="The (starting) well name of the next available tip(s)."
+    )
+
+
+class NoTipReason(Enum):
+    """The cause of no tip being available for a pipette and tip rack(s)."""
+
+    NO_AVAILABLE_TIPS = "noAvailableTips"
+    STARTING_TIP_WITH_PARTIAL = "startingTipWithPartial"
+    INCOMPATIBLE_CONFIGURATION = "incompatibleConfiguration"
+
+
+class NoTipAvailable(BaseModel):
+    """No available next tip data."""
+
+    noTipReason: NoTipReason = Field(
+        ..., description="The reason why no next available tip could be provided."
+    )
+    message: Optional[str] = Field(
+        None, description="Optional message explaining why a tip wasn't available."
+    )

opentrons/protocol_engine/types/command_annotations.py

@@ -0,0 +1,53 @@
+"""Protocol Engine types dealing with command annotations."""
+
+from typing import List, Literal, Dict, Any, Optional, Union
+from pydantic import (
+    ConfigDict,
+    BaseModel,
+    Field,
+)
+
+
+class BaseCommandAnnotation(BaseModel):
+    """Optional annotations for protocol engine commands."""
+
+    commandKeys: List[str] = Field(
+        ..., description="Command keys to which this annotation applies"
+    )
+    annotationType: str = Field(
+        ..., description="The type of annotation (for machine parsing)"
+    )
+
+
+class SecondOrderCommandAnnotation(BaseCommandAnnotation):
+    """Annotates a group of atomic commands which were the direct result of a second order command.
+
+    Examples of second order commands would be transfer, consolidate, mix, etc.
+    """
+
+    annotationType: Literal["secondOrderCommand"] = "secondOrderCommand"
+    params: Dict[str, Any] = Field(
+        ...,
+        description="Key value pairs of the parameters passed to the second order command that this annotates.",
+    )
+    machineReadableName: str = Field(
+        ...,
+        description="The name of the second order command in the form that the generating software refers to it",
+    )
+    userSpecifiedName: Optional[str] = Field(
+        None, description="The optional user-specified name of the second order command"
+    )
+    userSpecifiedDescription: Optional[str] = Field(
+        None,
+        description="The optional user-specified description of the second order command",
+    )
+
+
+class CustomCommandAnnotation(BaseCommandAnnotation):
+    """Annotates a group of atomic commands in some manner that Opentrons software does not anticipate or originate."""
+
+    annotationType: Literal["custom"] = "custom"
+    model_config = ConfigDict(extra="allow")
+
+
+CommandAnnotation = Union[SecondOrderCommandAnnotation, CustomCommandAnnotation]

opentrons/protocol_engine/types/deck_configuration.py

@@ -0,0 +1,72 @@
+"""Protocol engine types to do with deck configuration."""
+
+from dataclasses import dataclass
+from typing import FrozenSet, List, Tuple, Optional
+from enum import Enum
+
+from opentrons.types import DeckSlotName
+
+from opentrons_shared_data.module.types import ModuleType as SharedDataModuleType
+
+from .util import Vec3f, Dimensions
+
+
+class AddressableOffsetVector(Vec3f):
+    """Offset, in deck coordinates, from nominal to actual position of an addressable area."""
+
+
+@dataclass(frozen=True)
+class PotentialCutoutFixture:
+    """Cutout and cutout fixture id associated with a potential cutout fixture that can be on the deck."""
+
+    cutout_id: str
+    cutout_fixture_id: str
+    provided_addressable_areas: FrozenSet[str]
+
+
+class AreaType(Enum):
+    """The type of addressable area."""
+
+    SLOT = "slot"
+    STAGING_SLOT = "stagingSlot"
+    MOVABLE_TRASH = "movableTrash"
+    FIXED_TRASH = "fixedTrash"
+    WASTE_CHUTE = "wasteChute"
+    THERMOCYCLER = "thermocycler"
+    HEATER_SHAKER = "heaterShaker"
+    TEMPERATURE = "temperatureModule"
+    MAGNETICBLOCK = "magneticBlock"
+    ABSORBANCE_READER = "absorbanceReader"
+    FLEX_STACKER = "flexStacker"
+    LID_DOCK = "lidDock"
+
+
+@dataclass(frozen=True)
+class AddressableArea:
+    """Addressable area that has been loaded."""
+
+    area_name: str
+    area_type: AreaType
+    base_slot: DeckSlotName
+    display_name: str
+    bounding_box: Dimensions
+    position: AddressableOffsetVector
+    compatible_module_types: List[SharedDataModuleType]
+
+
+# TODO make the below some sort of better type
+# TODO This should instead contain a proper cutout fixture type
+DeckConfigurationType = List[
+    Tuple[str, str, Optional[str]]
+]  # cutout_id, cutout_fixture_id, opentrons_module_serial_number
+
+
+# TODO(mm, 2023-05-10): Deduplicate with constants in
+# opentrons.protocols.api_support.deck_type
+# and consider moving to shared-data.
+class DeckType(str, Enum):
+    """Types of deck available."""
+
+    OT2_STANDARD = "ot2_standard"
+    OT2_SHORT_TRASH = "ot2_short_trash"
+    OT3_STANDARD = "ot3_standard"

opentrons/protocol_engine/types/execution.py

@@ -0,0 +1,96 @@
+"""Protocol engine types to do with engine execution."""
+from enum import Enum
+
+
+# todo(mm, 2024-06-24): This monolithic status field is getting to be a bit much.
+# We should consider splitting this up into multiple fields.
+class EngineStatus(str, Enum):
+    """Current execution status of a ProtocolEngine.
+
+    This is a high-level summary of what the robot is doing and what interactions are
+    appropriate.
+    """
+
+    # Statuses for an ongoing run:
+
+    IDLE = "idle"
+    """The protocol has not been started yet.
+
+    The robot may truly be idle, or it may be executing commands with `intent: "setup"`.
+    """
+
+    RUNNING = "running"
+    """The engine is actively running the protocol."""
+
+    PAUSED = "paused"
+    """A pause has been requested. Activity is paused, or will pause soon.
+
+    (There is currently no way to tell which.)
+    """
+
+    BLOCKED_BY_OPEN_DOOR = "blocked-by-open-door"
+    """The robot's door is open. Activity is paused, or will pause soon."""
+
+    STOP_REQUESTED = "stop-requested"
+    """A stop has been requested. Activity will stop soon."""
+
+    FINISHING = "finishing"
+    """The robot is doing post-run cleanup, like homing and dropping tips."""
+
+    # Statuses for error recovery mode:
+
+    AWAITING_RECOVERY = "awaiting-recovery"
+    """The engine is waiting for external input to recover from a nonfatal error.
+
+    New commands with `intent: "fixit"` may be enqueued, which will run immediately.
+    The run can't be paused in this state, but it can be canceled, or resumed from the
+    next protocol command if recovery is complete.
+    """
+
+    AWAITING_RECOVERY_PAUSED = "awaiting-recovery-paused"
+    """The engine is paused while in error recovery mode. Activity is paused, or will pause soon.
+
+    This state is not possible to enter manually. It happens when an open door
+    gets closed during error recovery.
+    """
+
+    AWAITING_RECOVERY_BLOCKED_BY_OPEN_DOOR = "awaiting-recovery-blocked-by-open-door"
+    """The robot's door is open while in recovery mode. Activity is paused, or will pause soon."""
+
+    # Terminal statuses:
+
+    STOPPED = "stopped"
+    """All activity is over; it was stopped by an explicit external request."""
+
+    FAILED = "failed"
+    """All activity is over; there was a fatal error."""
+
+    SUCCEEDED = "succeeded"
+    """All activity is over; things completed without any fatal error."""
+
+
+class PostRunHardwareState(Enum):
+    """State of robot gantry & motors after a stop is performed and the hardware API is reset.
+
+    HOME_AND_STAY_ENGAGED: home the gantry and keep all motors engaged. This allows the
+        robot to continue performing movement actions without re-homing
+    HOME_THEN_DISENGAGE: home the gantry and then disengage motors.
+        Reduces current consumption of the motors and prevents coil heating.
+        Re-homing is required to re-engage the motors and resume robot movement.
+    STAY_ENGAGED_IN_PLACE: do not home after the stop and keep the motors engaged.
+        Keeps gantry in the same position as prior to `stop()` execution
+        and allows the robot to execute movement commands without requiring to re-home first.
+    DISENGAGE_IN_PLACE: disengage motors and do not home the robot
+    Probable states for pipette:
+        - for 1- or 8-channel:
+            - HOME_AND_STAY_ENGAGED after protocol runs
+            - STAY_ENGAGED_IN_PLACE after maintenance runs
+        - for 96-channel:
+            - HOME_THEN_DISENGAGE after protocol runs
+            - DISENGAGE_IN_PLACE after maintenance runs
+    """
+
+    HOME_AND_STAY_ENGAGED = "homeAndStayEngaged"
+    HOME_THEN_DISENGAGE = "homeThenDisengage"
+    STAY_ENGAGED_IN_PLACE = "stayEngagedInPlace"
+    DISENGAGE_IN_PLACE = "disengageInPlace"

opentrons/protocol_engine/types/hardware_passthrough.py

@@ -0,0 +1,25 @@
+"""Protocol Engine types for hardware passthrough."""
+
+from enum import Enum
+
+
+class MovementAxis(str, Enum):
+    """Axis on which to issue a relative movement."""
+
+    X = "x"
+    Y = "y"
+    Z = "z"
+
+
+class MotorAxis(str, Enum):
+    """Motor axis on which to issue a home command."""
+
+    X = "x"
+    Y = "y"
+    LEFT_Z = "leftZ"
+    RIGHT_Z = "rightZ"
+    LEFT_PLUNGER = "leftPlunger"
+    RIGHT_PLUNGER = "rightPlunger"
+    EXTENSION_Z = "extensionZ"
+    EXTENSION_JAW = "extensionJaw"
+    AXIS_96_CHANNEL_CAM = "axis96ChannelCam"

opentrons/protocol_engine/types/instrument.py

@@ -0,0 +1,47 @@
+"""Protocol Engine types to do with instruments."""
+
+from typing import Union
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from opentrons.types import MountType
+from opentrons_shared_data.pipette.types import PipetteNameType
+
+
+class LoadedPipette(BaseModel):
+    """A pipette that has been loaded."""
+
+    id: str
+    pipetteName: PipetteNameType
+    mount: MountType
+
+
+@dataclass(frozen=True)
+class CurrentAddressableArea:
+    """The latest addressable area the robot has accessed."""
+
+    pipette_id: str
+    addressable_area_name: str
+
+
+@dataclass(frozen=True)
+class CurrentWell:
+    """The latest well that the robot has accessed."""
+
+    pipette_id: str
+    labware_id: str
+    well_name: str
+
+
+CurrentPipetteLocation = Union[CurrentWell, CurrentAddressableArea]
+
+
+# TODO(mm, 2022-11-07): Deduplicate with Vec3f.
+class InstrumentOffsetVector(BaseModel):
+    """Instrument Offset from home position to robot deck."""
+
+    x: float
+    y: float
+    z: float

opentrons/protocol_engine/types/instrument_sensors.py

@@ -0,0 +1,47 @@
+"""Protocol engine types involving instrument sensors."""
+from enum import Enum
+
+from opentrons.hardware_control.types import (
+    TipStateType as HwTipStateType,
+    InstrumentProbeType,
+)
+
+
+class InstrumentSensorId(str, Enum):
+    """Primary and secondary sensor ids."""
+
+    PRIMARY = "primary"
+    SECONDARY = "secondary"
+    BOTH = "both"
+
+    def to_instrument_probe_type(self) -> InstrumentProbeType:
+        """Convert to InstrumentProbeType."""
+        return {
+            InstrumentSensorId.PRIMARY: InstrumentProbeType.PRIMARY,
+            InstrumentSensorId.SECONDARY: InstrumentProbeType.SECONDARY,
+            InstrumentSensorId.BOTH: InstrumentProbeType.BOTH,
+        }[self]
+
+
+class TipPresenceStatus(str, Enum):
+    """Tip presence status reported by a pipette."""
+
+    PRESENT = "present"
+    ABSENT = "absent"
+    UNKNOWN = "unknown"
+
+    def to_hw_state(self) -> HwTipStateType:
+        """Convert to hardware tip state."""
+        assert self != TipPresenceStatus.UNKNOWN
+        return {
+            TipPresenceStatus.PRESENT: HwTipStateType.PRESENT,
+            TipPresenceStatus.ABSENT: HwTipStateType.ABSENT,
+        }[self]
+
+    @classmethod
+    def from_hw_state(cls, state: HwTipStateType) -> "TipPresenceStatus":
+        """Convert from hardware tip state."""
+        return {
+            HwTipStateType.PRESENT: TipPresenceStatus.PRESENT,
+            HwTipStateType.ABSENT: TipPresenceStatus.ABSENT,
+        }[state]