opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/state/wells.py

@@ -0,0 +1,290 @@
+"""Basic well data state and store."""
+
+from dataclasses import dataclass
+from typing import (
+    Dict,
+    List,
+    Union,
+    Iterator,
+    Optional,
+    Tuple,
+    overload,
+)
+from datetime import datetime
+
+from opentrons.protocol_engine.types import (
+    ProbedHeightInfo,
+    ProbedVolumeInfo,
+    LoadedVolumeInfo,
+    WellInfoSummary,
+    WellLiquidInfo,
+)
+from opentrons.protocol_engine.types.liquid_level_detection import (
+    SimulatedProbeResult,
+    LiquidTrackingType,
+)
+
+from . import update_types
+from ._abstract_store import HasState, HandlesActions
+from ..actions import Action
+from ..actions.get_state_update import get_state_updates
+
+
+LabwareId = str
+WellName = str
+
+
+@dataclass
+class WellState:
+    """State of all wells."""
+
+    loaded_volumes: Dict[LabwareId, Dict[WellName, LoadedVolumeInfo]]
+    probed_heights: Dict[LabwareId, Dict[WellName, ProbedHeightInfo]]
+    probed_volumes: Dict[LabwareId, Dict[WellName, ProbedVolumeInfo]]
+
+
+class WellStore(HasState[WellState], HandlesActions):
+    """Well state container."""
+
+    _state: WellState
+
+    def __init__(self) -> None:
+        """Initialize a well store and its state."""
+        self._state = WellState(loaded_volumes={}, probed_heights={}, probed_volumes={})
+
+    def handle_action(self, action: Action) -> None:
+        """Modify state in reaction to an action."""
+        for state_update in get_state_updates(action):
+            if state_update.liquid_loaded != update_types.NO_CHANGE:
+                self._handle_liquid_loaded_update(state_update.liquid_loaded)
+            if state_update.liquid_probed != update_types.NO_CHANGE:
+                self._handle_liquid_probed_update(state_update.liquid_probed)
+            if state_update.liquid_operated != update_types.NO_CHANGE:
+                self._handle_liquid_operated_update(state_update.liquid_operated)
+
+    def _handle_liquid_loaded_update(
+        self, state_update: update_types.LiquidLoadedUpdate
+    ) -> None:
+        labware_id = state_update.labware_id
+        if labware_id not in self._state.loaded_volumes:
+            self._state.loaded_volumes[labware_id] = {}
+        for well, volume in state_update.volumes.items():
+            self._state.loaded_volumes[labware_id][well] = LoadedVolumeInfo(
+                volume=_none_from_clear(volume),
+                last_loaded=state_update.last_loaded,
+                operations_since_load=0,
+            )
+
+    def _handle_liquid_probed_update(
+        self, state_update: update_types.LiquidProbedUpdate
+    ) -> None:
+        labware_id = state_update.labware_id
+        well_name = state_update.well_name
+        if labware_id not in self._state.probed_heights:
+            self._state.probed_heights[labware_id] = {}
+        if labware_id not in self._state.probed_volumes:
+            self._state.probed_volumes[labware_id] = {}
+        self._state.probed_heights[labware_id][well_name] = ProbedHeightInfo(
+            height=_none_from_clear(state_update.height),
+            last_probed=state_update.last_probed,
+        )
+        self._state.probed_volumes[labware_id][well_name] = ProbedVolumeInfo(
+            volume=_none_from_clear(state_update.volume),
+            last_probed=state_update.last_probed,
+            operations_since_probe=0,
+        )
+
+    def _handle_liquid_operated_update(
+        self, state_update: update_types.LiquidOperatedUpdate
+    ) -> None:
+        for well_name in state_update.well_names:
+            self._handle_well_operated(
+                state_update.labware_id, well_name, state_update.volume_added
+            )
+
+    def _handle_well_operated(
+        self,
+        labware_id: str,
+        well_name: str,
+        volume_added: float | update_types.ClearType,
+    ) -> None:
+        if (
+            labware_id in self._state.loaded_volumes
+            and well_name in self._state.loaded_volumes[labware_id]
+        ):
+            if volume_added is update_types.CLEAR:
+                del self._state.loaded_volumes[labware_id][well_name]
+            else:
+                prev_loaded_vol_info = self._state.loaded_volumes[labware_id][well_name]
+                assert prev_loaded_vol_info.volume is not None, "volume info not loaded"
+                self._state.loaded_volumes[labware_id][well_name] = LoadedVolumeInfo(
+                    volume=prev_loaded_vol_info.volume + volume_added,
+                    last_loaded=prev_loaded_vol_info.last_loaded,
+                    operations_since_load=prev_loaded_vol_info.operations_since_load
+                    + 1,
+                )
+        if (
+            labware_id in self._state.probed_heights
+            and well_name in self._state.probed_heights[labware_id]
+        ):
+            del self._state.probed_heights[labware_id][well_name]
+        if (
+            labware_id in self._state.probed_volumes
+            and well_name in self._state.probed_volumes[labware_id]
+        ):
+            prev_probed_vol_info = self._state.probed_volumes[labware_id][well_name]
+            if volume_added is update_types.CLEAR:
+                del self._state.probed_volumes[labware_id][well_name]
+            elif isinstance(
+                prev_probed_vol_info.volume,
+                SimulatedProbeResult,
+            ):
+                prev_probed_vol_info.volume.simulate_probed_aspirate_dispense(
+                    volume_added
+                )
+                self._state.probed_volumes[labware_id][well_name] = ProbedVolumeInfo(
+                    volume=prev_probed_vol_info.volume,
+                    last_probed=prev_probed_vol_info.last_probed,
+                    operations_since_probe=prev_probed_vol_info.operations_since_probe
+                    + 1,
+                )
+                return
+            else:
+                if prev_probed_vol_info.volume is None:
+                    new_vol_info: float | None = None
+                else:
+                    assert isinstance(prev_probed_vol_info.volume, float)
+                    new_vol_info = prev_probed_vol_info.volume + volume_added
+                self._state.probed_volumes[labware_id][well_name] = ProbedVolumeInfo(
+                    volume=new_vol_info,
+                    last_probed=prev_probed_vol_info.last_probed,
+                    operations_since_probe=prev_probed_vol_info.operations_since_probe
+                    + 1,
+                )
+
+
+class WellView:
+    """Read-only well state view."""
+
+    _state: WellState
+
+    def __init__(self, state: WellState) -> None:
+        """Initialize the computed view of well state.
+
+        Arguments:
+            state: Well state dataclass used for all calculations.
+        """
+        self._state = state
+
+    def get_well_liquid_info(self, labware_id: str, well_name: str) -> WellLiquidInfo:
+        """Return all the liquid info for a well."""
+        if (
+            labware_id not in self._state.loaded_volumes
+            or well_name not in self._state.loaded_volumes[labware_id]
+        ):
+            loaded_volume_info = None
+        else:
+            loaded_volume_info = self._state.loaded_volumes[labware_id][well_name]
+        if (
+            labware_id not in self._state.probed_heights
+            or well_name not in self._state.probed_heights[labware_id]
+        ):
+            probed_height_info = None
+        else:
+            probed_height_info = self._state.probed_heights[labware_id][well_name]
+        if (
+            labware_id not in self._state.probed_volumes
+            or well_name not in self._state.probed_volumes[labware_id]
+        ):
+            probed_volume_info = None
+        else:
+            probed_volume_info = self._state.probed_volumes[labware_id][well_name]
+        return WellLiquidInfo(
+            loaded_volume=loaded_volume_info,
+            probed_height=probed_height_info,
+            probed_volume=probed_volume_info,
+        )
+
+    def get_last_liquid_update(
+        self, labware_id: str, well_name: str
+    ) -> Optional[datetime]:
+        """Return the timestamp of the last load or probe done on the well."""
+        info = self.get_well_liquid_info(labware_id, well_name)
+        update_times: List[datetime] = []
+        if info.loaded_volume is not None and info.loaded_volume.volume is not None:
+            update_times.append(info.loaded_volume.last_loaded)
+        if info.probed_height is not None and info.probed_height.height is not None:
+            update_times.append(info.probed_height.last_probed)
+        if info.probed_volume is not None and info.probed_volume.volume is not None:
+            update_times.append(info.probed_volume.last_probed)
+        if len(update_times) > 0:
+            return max(update_times)
+        return None
+
+    def get_all(self) -> List[WellInfoSummary]:
+        """Get all well liquid info summaries."""
+
+        def _all_well_combos() -> Iterator[Tuple[str, str, str]]:
+            for labware, lv_wells in self._state.loaded_volumes.items():
+                for well_name in lv_wells.keys():
+                    yield f"{labware}{well_name}", labware, well_name
+            for labware, ph_wells in self._state.probed_heights.items():
+                for well_name in ph_wells.keys():
+                    yield f"{labware}{well_name}", labware, well_name
+            for labware, pv_wells in self._state.probed_volumes.items():
+                for well_name in pv_wells.keys():
+                    yield f"{labware}{well_name}", labware, well_name
+
+        wells = {
+            key: (labware_id, well_name)
+            for key, labware_id, well_name in _all_well_combos()
+        }
+        return [
+            self._summarize_well(labware_id, well_name)
+            for labware_id, well_name in wells.values()
+        ]
+
+    def _summarize_well(self, labware_id: str, well_name: str) -> WellInfoSummary:
+        well_liquid_info = self.get_well_liquid_info(labware_id, well_name)
+        return WellInfoSummary(
+            labware_id=labware_id,
+            well_name=well_name,
+            loaded_volume=_volume_from_info(well_liquid_info.loaded_volume),
+            probed_volume=_volume_from_info(well_liquid_info.probed_volume),
+            probed_height=_height_from_info(well_liquid_info.probed_height),
+        )
+
+
+@overload
+def _volume_from_info(info: Optional[ProbedVolumeInfo]) -> Optional[float]:
+    ...
+
+
+@overload
+def _volume_from_info(info: Optional[LoadedVolumeInfo]) -> Optional[float]:
+    ...
+
+
+def _volume_from_info(
+    info: Union[ProbedVolumeInfo, LoadedVolumeInfo, None],
+) -> Union[LiquidTrackingType, None]:
+    if info is None:
+        return None
+    return info.volume
+
+
+def _height_from_info(
+    info: Optional[ProbedHeightInfo],
+) -> Union[LiquidTrackingType, None]:
+    if info is None:
+        return None
+    return info.height
+
+
+def _none_from_clear(
+    inval: LiquidTrackingType | update_types.ClearType,
+) -> LiquidTrackingType | None:
+    if inval == update_types.CLEAR:
+        return None
+    assert isinstance(inval, (SimulatedProbeResult, float, int))
+    return inval

opentrons/protocol_engine/types/__init__.py

@@ -0,0 +1,310 @@
+"""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,
+    DeckLocationDefinition,
+)
+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,
+    StackerStoredLabwareGroup,
+    StackerLabwareMovementStrategy,
+)
+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,
+    LabwareParentDefinition,
+    LabwareWellId,
+)
+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",
+    "DeckLocationDefinition",
+    # 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",
+    "StackerStoredLabwareGroup",
+    "StackerLabwareMovementStrategy",
+    # 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",
+    "LabwareParentDefinition",
+    "LabwareWellId",
+    # 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]