opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/commands/comment.py

@@ -0,0 +1,57 @@
+"""Comment command request, result, and implementation models."""
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import Optional, Type
+from typing_extensions import Literal
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+
+CommentCommandType = Literal["comment"]
+
+
+class CommentParams(BaseModel):
+    """Payload required to annotate execution with a comment."""
+
+    message: str = Field(
+        ...,
+        description="A user-facing message",
+    )
+
+
+class CommentResult(BaseModel):
+    """Result data from the execution of a Comment command."""
+
+
+class CommentImplementation(
+    AbstractCommandImpl[CommentParams, SuccessData[CommentResult]]
+):
+    """Comment command implementation."""
+
+    def __init__(self, **kwargs: object) -> None:
+        pass
+
+    async def execute(self, params: CommentParams) -> SuccessData[CommentResult]:
+        """No operation taken other than capturing message in command."""
+        return SuccessData(
+            public=CommentResult(),
+        )
+
+
+class Comment(BaseCommand[CommentParams, CommentResult, ErrorOccurrence]):
+    """Comment command model."""
+
+    commandType: CommentCommandType = "comment"
+    params: CommentParams
+    result: Optional[CommentResult] = None
+
+    _ImplementationCls: Type[CommentImplementation] = CommentImplementation
+
+
+class CommentCreate(BaseCommandCreate[CommentParams]):
+    """Comment command request model."""
+
+    commandType: CommentCommandType = "comment"
+    params: CommentParams
+
+    _CommandCls: Type[Comment] = Comment

opentrons/protocol_engine/commands/configure_for_volume.py

@@ -0,0 +1,108 @@
+"""Configure for volume command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Any
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+from typing_extensions import Literal
+
+from .pipetting_common import PipetteIdMixin
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..state.update_types import StateUpdate
+
+if TYPE_CHECKING:
+    from ..execution import EquipmentHandler
+
+
+ConfigureForVolumeCommandType = Literal["configureForVolume"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class ConfigureForVolumeParams(PipetteIdMixin):
+    """Parameters required to configure volume for a specific pipette."""
+
+    volume: float = Field(
+        ...,
+        description="Amount of liquid in uL. Must be at least 0 and no greater "
+        "than a pipette-specific maximum volume.",
+        ge=0.0,
+    )
+    tipOverlapNotAfterVersion: str | SkipJsonSchema[None] = Field(
+        None,
+        description="A version of tip overlap data to not exceed. The highest-versioned "
+        "tip overlap data that does not exceed this version will be used. Versions are "
+        "expressed as vN where N is an integer, counting up from v0. If None, the current "
+        "highest version will be used.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class ConfigureForVolumeResult(BaseModel):
+    """Result data from execution of an ConfigureForVolume command."""
+
+    pass
+
+
+class ConfigureForVolumeImplementation(
+    AbstractCommandImpl[
+        ConfigureForVolumeParams,
+        SuccessData[ConfigureForVolumeResult],
+    ]
+):
+    """Configure for volume command implementation."""
+
+    def __init__(self, equipment: EquipmentHandler, **kwargs: object) -> None:
+        self._equipment = equipment
+
+    async def execute(
+        self, params: ConfigureForVolumeParams
+    ) -> SuccessData[ConfigureForVolumeResult]:
+        """Check that requested pipette can be configured for the given volume."""
+        pipette_result = await self._equipment.configure_for_volume(
+            pipette_id=params.pipetteId,
+            volume=params.volume,
+            tip_overlap_version=params.tipOverlapNotAfterVersion,
+        )
+
+        state_update = StateUpdate()
+        state_update.update_pipette_config(
+            pipette_id=pipette_result.pipette_id,
+            config=pipette_result.static_config,
+            serial_number=pipette_result.serial_number,
+        )
+        state_update.set_pipette_ready_to_aspirate(
+            pipette_result.pipette_id, ready_to_aspirate=False
+        )
+
+        return SuccessData(
+            public=ConfigureForVolumeResult(),
+            state_update=state_update,
+        )
+
+
+class ConfigureForVolume(
+    BaseCommand[ConfigureForVolumeParams, ConfigureForVolumeResult, ErrorOccurrence]
+):
+    """Configure for volume command model."""
+
+    commandType: ConfigureForVolumeCommandType = "configureForVolume"
+    params: ConfigureForVolumeParams
+    result: Optional[ConfigureForVolumeResult] = None
+
+    _ImplementationCls: Type[
+        ConfigureForVolumeImplementation
+    ] = ConfigureForVolumeImplementation
+
+
+class ConfigureForVolumeCreate(BaseCommandCreate[ConfigureForVolumeParams]):
+    """Configure for volume command creation request model."""
+
+    commandType: ConfigureForVolumeCommandType = "configureForVolume"
+    params: ConfigureForVolumeParams
+
+    _CommandCls: Type[ConfigureForVolume] = ConfigureForVolume

opentrons/protocol_engine/commands/configure_nozzle_layout.py

@@ -0,0 +1,115 @@
+"""Configure nozzle layout command request, result, and implementation models."""
+from __future__ import annotations
+from opentrons.protocol_engine.state.update_types import StateUpdate
+from pydantic import BaseModel
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from .pipetting_common import (
+    PipetteIdMixin,
+)
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+from ..types import (
+    AllNozzleLayoutConfiguration,
+    SingleNozzleLayoutConfiguration,
+    RowNozzleLayoutConfiguration,
+    ColumnNozzleLayoutConfiguration,
+    QuadrantNozzleLayoutConfiguration,
+)
+
+if TYPE_CHECKING:
+    from ..execution import EquipmentHandler, TipHandler
+
+
+ConfigureNozzleLayoutCommandType = Literal["configureNozzleLayout"]
+
+
+class ConfigureNozzleLayoutParams(PipetteIdMixin):
+    """Parameters required to configure the nozzle layout for a specific pipette."""
+
+    configurationParams: Union[
+        AllNozzleLayoutConfiguration,
+        SingleNozzleLayoutConfiguration,
+        RowNozzleLayoutConfiguration,
+        ColumnNozzleLayoutConfiguration,
+        QuadrantNozzleLayoutConfiguration,
+    ]
+
+
+class ConfigureNozzleLayoutResult(BaseModel):
+    """Result data from execution of an configureNozzleLayout command."""
+
+    pass
+
+
+class ConfigureNozzleLayoutImplementation(
+    AbstractCommandImpl[
+        ConfigureNozzleLayoutParams,
+        SuccessData[ConfigureNozzleLayoutResult],
+    ]
+):
+    """Configure nozzle layout command implementation."""
+
+    def __init__(
+        self, equipment: EquipmentHandler, tip_handler: TipHandler, **kwargs: object
+    ) -> None:
+        self._equipment = equipment
+        self._tip_handler = tip_handler
+
+    async def execute(
+        self, params: ConfigureNozzleLayoutParams
+    ) -> SuccessData[ConfigureNozzleLayoutResult]:
+        """Check that requested pipette can support the requested nozzle layout."""
+        primary_nozzle = params.configurationParams.model_dump().get("primaryNozzle")
+        front_right_nozzle = params.configurationParams.model_dump().get(
+            "frontRightNozzle"
+        )
+        back_left_nozzle = params.configurationParams.model_dump().get("backLeftNozzle")
+        nozzle_params = await self._tip_handler.available_for_nozzle_layout(
+            pipette_id=params.pipetteId,
+            style=params.configurationParams.style,
+            primary_nozzle=primary_nozzle,
+            front_right_nozzle=front_right_nozzle,
+            back_left_nozzle=back_left_nozzle,
+        )
+
+        nozzle_map = await self._equipment.configure_nozzle_layout(
+            pipette_id=params.pipetteId,
+            **nozzle_params,
+        )
+
+        update_state = StateUpdate()
+        update_state.update_pipette_nozzle(
+            pipette_id=params.pipetteId, nozzle_map=nozzle_map
+        )
+
+        return SuccessData(
+            public=ConfigureNozzleLayoutResult(),
+            state_update=update_state,
+        )
+
+
+class ConfigureNozzleLayout(
+    BaseCommand[
+        ConfigureNozzleLayoutParams, ConfigureNozzleLayoutResult, ErrorOccurrence
+    ]
+):
+    """Configure nozzle layout command model."""
+
+    commandType: ConfigureNozzleLayoutCommandType = "configureNozzleLayout"
+    params: ConfigureNozzleLayoutParams
+    result: Optional[ConfigureNozzleLayoutResult] = None
+
+    _ImplementationCls: Type[
+        ConfigureNozzleLayoutImplementation
+    ] = ConfigureNozzleLayoutImplementation
+
+
+class ConfigureNozzleLayoutCreate(BaseCommandCreate[ConfigureNozzleLayoutParams]):
+    """Configure nozzle layout creation request model."""
+
+    commandType: ConfigureNozzleLayoutCommandType = "configureNozzleLayout"
+    params: ConfigureNozzleLayoutParams
+
+    _CommandCls: Type[ConfigureNozzleLayout] = ConfigureNozzleLayout

opentrons/protocol_engine/commands/custom.py

@@ -0,0 +1,67 @@
+"""Custom protocol command.
+
+A "custom" command contains arbitrary payload and result data.
+It can be used by ProtocolEngine plugins to represent external
+commands in state that a vanilla ProtocolEngine would not
+know about.
+
+This data model serves as a wrapper to ensure custom, arbitrary
+data still adheres to the shapes that ProtocolEngine expects.
+If you are implementing a custom command, you should probably
+put your own disambiguation identifier in the payload.
+"""
+from pydantic import ConfigDict, BaseModel, SerializeAsAny
+from typing import Optional, Type
+from typing_extensions import Literal
+
+from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ..errors.error_occurrence import ErrorOccurrence
+
+
+CustomCommandType = Literal["custom"]
+
+
+class CustomParams(BaseModel):
+    """Payload used by a custom command."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class CustomResult(BaseModel):
+    """Result data from a custom command."""
+
+    model_config = ConfigDict(extra="allow")
+
+
+class CustomImplementation(
+    AbstractCommandImpl[CustomParams, SuccessData[CustomResult]]
+):
+    """Custom command implementation."""
+
+    # TODO(mm, 2022-11-09): figure out how a plugin can specify a custom command
+    # implementation. For now, always no-op, so we can use custom commands as containers
+    # for legacy RPC (pre-ProtocolEngine) payloads.
+    async def execute(self, params: CustomParams) -> SuccessData[CustomResult]:
+        """A custom command does nothing when executed directly."""
+        return SuccessData(
+            public=CustomResult.model_construct(),
+        )
+
+
+class Custom(BaseCommand[CustomParams, CustomResult, ErrorOccurrence]):
+    """Custom command model."""
+
+    commandType: CustomCommandType = "custom"
+    params: SerializeAsAny[CustomParams]
+    result: Optional[CustomResult] = None
+
+    _ImplementationCls: Type[CustomImplementation] = CustomImplementation
+
+
+class CustomCreate(BaseCommandCreate[CustomParams]):
+    """A request to create a custom command."""
+
+    commandType: CustomCommandType = "custom"
+    params: CustomParams
+
+    _CommandCls: Type[Custom] = Custom

opentrons/protocol_engine/commands/dispense.py

@@ -0,0 +1,194 @@
+"""Dispense command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union, Any
+from typing_extensions import Literal
+
+from pydantic import Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..state.update_types import StateUpdate, CLEAR
+from .pipetting_common import (
+    PipetteIdMixin,
+    DispenseVolumeMixin,
+    FlowRateMixin,
+    BaseLiquidHandlingResult,
+    OverpressureError,
+    dispense_in_place,
+    DEFAULT_CORRECTION_VOLUME,
+)
+from .movement_common import (
+    LiquidHandlingWellLocationMixin,
+    DestinationPositionResult,
+    StallOrCollisionError,
+    move_to_well,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    DefinedErrorData,
+    SuccessData,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler, PipettingHandler
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+
+
+DispenseCommandType = Literal["dispense"]
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+class DispenseParams(
+    PipetteIdMixin, DispenseVolumeMixin, FlowRateMixin, LiquidHandlingWellLocationMixin
+):
+    """Payload required to dispense to a specific well."""
+
+    pushOut: float | SkipJsonSchema[None] = Field(
+        None,
+        description="push the plunger a small amount farther than necessary for accurate low-volume dispensing",
+        json_schema_extra=_remove_default,
+    )
+
+
+class DispenseResult(BaseLiquidHandlingResult, DestinationPositionResult):
+    """Result data from the execution of a Dispense command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[DispenseResult],
+    DefinedErrorData[OverpressureError] | DefinedErrorData[StallOrCollisionError],
+]
+
+
+class DispenseImplementation(AbstractCommandImpl[DispenseParams, _ExecuteReturn]):
+    """Dispense command implementation."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        movement: MovementHandler,
+        pipetting: PipettingHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._movement = movement
+        self._pipetting = pipetting
+        self._model_utils = model_utils
+
+    async def execute(self, params: DispenseParams) -> _ExecuteReturn:
+        """Move to and dispense to the requested well."""
+        well_location = params.wellLocation
+        labware_id = params.labwareId
+        well_name = params.wellName
+        volume = params.volume
+
+        # TODO(pbm, 10-15-24): call self._state_view.geometry.validate_dispense_volume_into_well()
+
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=params.pipetteId,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+            operation_volume=volume,
+        )
+        if isinstance(move_result, DefinedErrorData):
+            return move_result
+        dispense_result = await dispense_in_place(
+            pipette_id=params.pipetteId,
+            volume=volume,
+            flow_rate=params.flowRate,
+            push_out=params.pushOut,
+            location_if_error={
+                "retryLocation": (
+                    move_result.public.position.x,
+                    move_result.public.position.y,
+                    move_result.public.position.z,
+                )
+            },
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+            correction_volume=params.correctionVolume or DEFAULT_CORRECTION_VOLUME,
+        )
+
+        if isinstance(dispense_result, DefinedErrorData):
+            return DefinedErrorData(
+                public=dispense_result.public,
+                state_update=(
+                    StateUpdate.reduce(
+                        move_result.state_update, dispense_result.state_update
+                    ).set_liquid_operated(
+                        labware_id=labware_id,
+                        well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                            labware_id, well_name, params.pipetteId
+                        ),
+                        volume_added=CLEAR,
+                    )
+                ),
+                state_update_if_false_positive=StateUpdate.reduce(
+                    move_result.state_update,
+                    dispense_result.state_update_if_false_positive,
+                ),
+            )
+        else:
+            volume_added = (
+                self._state_view.pipettes.get_liquid_dispensed_by_ejecting_volume(
+                    pipette_id=params.pipetteId, volume=dispense_result.public.volume
+                )
+            )
+            if volume_added is not None:
+                volume_added *= self._state_view.geometry.get_nozzles_per_well(
+                    labware_id, well_name, params.pipetteId
+                )
+            return SuccessData(
+                public=DispenseResult(
+                    volume=dispense_result.public.volume,
+                    position=move_result.public.position,
+                ),
+                state_update=(
+                    StateUpdate.reduce(
+                        move_result.state_update, dispense_result.state_update
+                    ).set_liquid_operated(
+                        labware_id=labware_id,
+                        well_names=self._state_view.geometry.get_wells_covered_by_pipette_with_active_well(
+                            labware_id, well_name, params.pipetteId
+                        ),
+                        volume_added=volume_added
+                        if volume_added is not None
+                        else CLEAR,
+                    )
+                ),
+            )
+
+
+class Dispense(
+    BaseCommand[
+        DispenseParams, DispenseResult, OverpressureError | StallOrCollisionError
+    ]
+):
+    """Dispense command model."""
+
+    commandType: DispenseCommandType = "dispense"
+    params: DispenseParams
+    result: Optional[DispenseResult] = None
+
+    _ImplementationCls: Type[DispenseImplementation] = DispenseImplementation
+
+
+class DispenseCreate(BaseCommandCreate[DispenseParams]):
+    """Create dispense command request model."""
+
+    commandType: DispenseCommandType = "dispense"
+    params: DispenseParams
+
+    _CommandCls: Type[Dispense] = Dispense