opentrons 8.6.0__py3-none-any.whl

opentrons/protocol_engine/commands/flex_stacker/store.py

@@ -0,0 +1,339 @@
+"""Command models to retrieve a labware from a Flex Stacker."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Type, Union, cast
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons_shared_data.errors.exceptions import (
+    FlexStackerStallError,
+    FlexStackerShuttleMissingError,
+)
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..flex_stacker.common import (
+    FlexStackerStallOrCollisionError,
+    FlexStackerShuttleError,
+    labware_locations_for_group,
+    labware_location_base_sequence,
+    primary_location_sequence,
+    adapter_location_sequence,
+    lid_location_sequence,
+)
+from ...errors import (
+    ErrorOccurrence,
+    CannotPerformModuleAction,
+    LabwareNotLoadedOnModuleError,
+    FlexStackerLabwarePoolNotYetDefinedError,
+)
+from ...resources import ModelUtils
+from ...state import update_types
+from ...types import (
+    LabwareLocationSequence,
+    InStackerHopperLocation,
+    StackerStoredLabwareGroup,
+    ModuleLocation,
+    StackerLabwareMovementStrategy,
+)
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.state.module_substates import FlexStackerSubState
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+
+StoreCommandType = Literal["flexStacker/store"]
+
+
+class StoreParams(BaseModel):
+    """Input parameters for a labware storage command."""
+
+    moduleId: str = Field(
+        ...,
+        description="Unique ID of the flex stacker.",
+    )
+    strategy: StackerLabwareMovementStrategy = Field(
+        ...,
+        description=(
+            "If manual, indicates that labware has been moved to the hopper "
+            "manually by the user, as required in error recovery."
+        ),
+    )
+
+
+class StoreResult(BaseModel):
+    """Result data from a labware storage command."""
+
+    eventualDestinationLocationSequence: (
+        LabwareLocationSequence | SkipJsonSchema[None]
+    ) = Field(
+        None,
+        description=(
+            "The full location in which all labware moved by this command will eventually reside."
+        ),
+    )
+    primaryOriginLocationSequence: LabwareLocationSequence | SkipJsonSchema[
+        None
+    ] = Field(None, description=("The origin location of the primary labware."))
+    primaryLabwareId: str | SkipJsonSchema[None] = Field(
+        None, description="The primary labware in the stack that was stored."
+    )
+    adapterOriginLocationSequence: LabwareLocationSequence | SkipJsonSchema[
+        None
+    ] = Field(None, description=("The origin location of the adapter labware, if any."))
+    adapterLabwareId: str | SkipJsonSchema[None] = Field(
+        None, description="The adapter in the stack that was stored, if any."
+    )
+    lidOriginLocationSequence: LabwareLocationSequence | SkipJsonSchema[None] = Field(
+        None, description=("The origin location of the lid labware, if any.")
+    )
+    lidLabwareId: str | SkipJsonSchema[None] = Field(
+        None, description="The lid in the stack that was stored, if any."
+    )
+    primaryLabwareURI: str = Field(
+        ...,
+        description="The labware definition URI of the primary labware.",
+    )
+    adapterLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the adapter labware.",
+    )
+    lidLabwareURI: str | SkipJsonSchema[None] = Field(
+        None,
+        description="The labware definition URI of the lid labware.",
+    )
+
+
+_ExecuteReturn = Union[
+    SuccessData[StoreResult],
+    DefinedErrorData[FlexStackerStallOrCollisionError]
+    | DefinedErrorData[FlexStackerShuttleError],
+]
+
+
+class StoreImpl(AbstractCommandImpl[StoreParams, _ExecuteReturn]):
+    """Implementation of a labware storage command."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+        self._model_utils = model_utils
+
+    def _verify_labware_to_store(
+        self, params: StoreParams, stacker_state: FlexStackerSubState
+    ) -> tuple[str, str | None, str | None]:
+        location = self._state_view.modules.get_location(params.moduleId)
+        try:
+            bottom_id = self._state_view.labware.get_id_by_module(params.moduleId)
+        except LabwareNotLoadedOnModuleError:
+            raise CannotPerformModuleAction(
+                f"Flex Stacker in {location} cannot store labware because its carriage is empty"
+            )
+        labware_ids = self._state_view.labware.get_labware_stack_from_parent(bottom_id)
+        labware_defs = [
+            self._state_view.labware.get_definition(id) for id in labware_ids
+        ]
+
+        lid_id: str | None = None
+
+        pool_list = stacker_state.get_pool_definition_ordered_list()
+        assert pool_list is not None
+        if len(labware_ids) != len(pool_list):
+            raise CannotPerformModuleAction(
+                f"Cannot store labware stack that does not correspond with the configuration of Flex Stacker in {location}"
+            )
+        if stacker_state.pool_lid_definition is not None:
+            if labware_defs[-1] != stacker_state.pool_lid_definition:
+                raise CannotPerformModuleAction(
+                    f"Cannot store labware stack that does not correspond with the configuration of Flex Stacker in {location}"
+                )
+            lid_id = labware_ids[-1]
+
+        if stacker_state.pool_adapter_definition is not None:
+            if (
+                labware_defs[0] != stacker_state.pool_adapter_definition
+                or labware_defs[1] != stacker_state.pool_primary_definition
+            ):
+                raise CannotPerformModuleAction(
+                    f"Cannot store labware stack that does not correspond with the configuration of Flex Stacker in {location}"
+                )
+            else:
+                return labware_ids[1], labware_ids[0], lid_id
+        else:
+            if labware_defs[0] != stacker_state.pool_primary_definition:
+                raise CannotPerformModuleAction(
+                    f"Cannot store labware stack that does not correspond with the configuration of Flex Stacker in {location}"
+                )
+            return labware_ids[0], None, lid_id
+
+    async def execute(self, params: StoreParams) -> _ExecuteReturn:
+        """Execute the labware storage command."""
+        stacker_state = self._state_view.modules.get_flex_stacker_substate(
+            params.moduleId
+        )
+
+        location = self._state_view.modules.get_location(params.moduleId)
+        pool_definitions = stacker_state.get_pool_definition_ordered_list()
+        if pool_definitions is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                message=f"The Flex Stacker in {location} has not been configured yet and cannot be filled."
+            )
+
+        if (
+            len(stacker_state.contained_labware_bottom_first)
+            == stacker_state.max_pool_count
+        ):
+            raise CannotPerformModuleAction(
+                f"Cannot store labware in Flex Stacker in {location} because it is full"
+            )
+
+        primary_id, maybe_adapter_id, maybe_lid_id = self._verify_labware_to_store(
+            params, stacker_state
+        )
+
+        # Allow propagation of ModuleNotAttachedError.
+        stacker_hw = self._equipment.get_module_hardware_api(stacker_state.module_id)
+
+        state_update = update_types.StateUpdate()
+        if stacker_hw is not None:
+            stacker_hw.set_stacker_identify(True)
+
+        if (
+            params.strategy is StackerLabwareMovementStrategy.AUTOMATIC
+            and stacker_hw is not None
+        ):
+            try:
+                await stacker_hw.store_labware(
+                    labware_height=stacker_state.get_pool_height_minus_overlap()
+                )
+            except FlexStackerStallError as e:
+                return DefinedErrorData(
+                    public=FlexStackerStallOrCollisionError(
+                        id=self._model_utils.generate_id(),
+                        createdAt=self._model_utils.get_timestamp(),
+                        wrappedErrors=[
+                            ErrorOccurrence.from_failed(
+                                id=self._model_utils.generate_id(),
+                                createdAt=self._model_utils.get_timestamp(),
+                                error=e,
+                            )
+                        ],
+                        errorInfo={"labwareId": primary_id},
+                    ),
+                )
+            except FlexStackerShuttleMissingError as e:
+                return DefinedErrorData(
+                    public=FlexStackerShuttleError(
+                        id=self._model_utils.generate_id(),
+                        createdAt=self._model_utils.get_timestamp(),
+                        wrappedErrors=[
+                            ErrorOccurrence.from_failed(
+                                id=self._model_utils.generate_id(),
+                                createdAt=self._model_utils.get_timestamp(),
+                                error=e,
+                            )
+                        ],
+                        errorInfo={"labwareId": primary_id},
+                    ),
+                )
+
+        id_list = [
+            id for id in (primary_id, maybe_adapter_id, maybe_lid_id) if id is not None
+        ]
+
+        group = StackerStoredLabwareGroup(
+            primaryLabwareId=primary_id,
+            adapterLabwareId=maybe_adapter_id,
+            lidLabwareId=maybe_lid_id,
+        )
+
+        state_update.set_batch_labware_location(
+            new_locations_by_id={
+                id: InStackerHopperLocation(moduleId=params.moduleId) for id in id_list
+            },
+            new_offset_ids_by_id={id: None for id in id_list},
+        )
+
+        state_update.update_flex_stacker_contained_labware(
+            module_id=params.moduleId,
+            contained_labware_bottom_first=(
+                [group] + stacker_state.contained_labware_bottom_first
+            ),
+        )
+
+        original_location_sequences = labware_locations_for_group(
+            group,
+            labware_location_base_sequence(
+                group,
+                self._state_view,
+                self._state_view.geometry.get_predicted_location_sequence(
+                    ModuleLocation(moduleId=params.moduleId)
+                ),
+            ),
+        )
+
+        if stacker_hw is not None:
+            stacker_hw.set_stacker_identify(False)
+
+        return SuccessData(
+            public=StoreResult.model_construct(
+                eventualDestinationLocationSequence=[
+                    InStackerHopperLocation(moduleId=params.moduleId)
+                ],
+                primaryOriginLocationSequence=primary_location_sequence(
+                    original_location_sequences
+                ),
+                primaryLabwareId=primary_id,
+                adapterOriginLocationSequence=adapter_location_sequence(
+                    original_location_sequences
+                ),
+                adapterLabwareId=maybe_adapter_id,
+                lidOriginLocationSequence=lid_location_sequence(
+                    original_location_sequences
+                ),
+                lidLabwareId=maybe_lid_id,
+                primaryLabwareURI=self._state_view.labware.get_uri_from_definition_unless_none(
+                    cast(LabwareDefinition, stacker_state.pool_primary_definition)
+                ),
+                adapterLabwareURI=self._state_view.labware.get_uri_from_definition_unless_none(
+                    stacker_state.pool_adapter_definition
+                ),
+                lidLabwareURI=self._state_view.labware.get_uri_from_definition_unless_none(
+                    stacker_state.pool_lid_definition
+                ),
+            ),
+            state_update=state_update,
+        )
+
+
+class Store(BaseCommand[StoreParams, StoreResult, ErrorOccurrence]):
+    """A command to store a labware in a Flex Stacker."""
+
+    commandType: StoreCommandType = "flexStacker/store"
+    params: StoreParams
+    result: Optional[StoreResult] = None
+
+    _ImplementationCls: Type[StoreImpl] = StoreImpl
+
+
+class StoreCreate(BaseCommandCreate[StoreParams]):
+    """A request to execute a Flex Stacker store command."""
+
+    commandType: StoreCommandType = "flexStacker/store"
+    params: StoreParams
+
+    _CommandCls: Type[Store] = Store

opentrons/protocol_engine/commands/generate_command_schema.py

@@ -0,0 +1,61 @@
+"""Generate a JSON schema against which all create commands statically validate."""
+
+import json
+import argparse
+import sys
+from opentrons.protocol_engine.commands.command_unions import CommandCreateAdapter
+
+from opentrons_shared_data.command import get_newest_schema_version
+from opentrons_shared_data.load import get_shared_data_root
+
+
+def generate_command_schema(version: str) -> str:
+    """Generate a JSON Schema that all valid create commands can validate against."""
+    schema_as_dict = CommandCreateAdapter.json_schema(mode="validation", by_alias=False)
+    schema_as_dict["$id"] = f"opentronsCommandSchemaV{version}"
+    schema_as_dict["$schema"] = "http://json-schema.org/draft-07/schema#"
+    return json.dumps(schema_as_dict, indent=2, sort_keys=True)
+
+
+def write_command_schema(json_string: str, version: str) -> None:
+    """Write a JSON command schema to the shared-data command schema directory."""
+    path = get_shared_data_root() / "command" / "schemas" / f"{version}.json"
+    with open(path, "w") as schema_file:
+        schema_file.write(json_string)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        prog="generate_command_schema",
+        description="Generate A JSON-schema of all possible Create-Commands accepted by the current Protocol Engine",
+    )
+    parser.add_argument(
+        "version",
+        type=str,
+        nargs="?",
+        help="The command schema version. This is a single integer (e.g. 7) that will be used to name the generated"
+        " schema file. If not included, it will automatically use the latest version in shared-data.",
+    )
+    parser.add_argument(
+        "--overwrite-shared-data",
+        action="store_true",
+        help="If used, overwrites the specified or automatically chosen command schema version in shared-data."
+        " If not included, the generated schema will be printed to stdout.",
+    )
+    args = parser.parse_args()
+
+    if args.version is None:
+        version_string = get_newest_schema_version()
+    else:
+        version_string = args.version
+
+    command_schema = generate_command_schema(version_string)
+
+    if args.overwrite_shared_data:
+        write_command_schema(command_schema, version_string)
+    else:
+        print(command_schema)
+
+    sys.exit()
+
+__all__ = ["generate_command_schema"]

opentrons/protocol_engine/commands/get_next_tip.py

@@ -0,0 +1,134 @@
+"""Get next tip command request, result, and implementation models."""
+
+from __future__ import annotations
+from pydantic import BaseModel, Field
+from typing import TYPE_CHECKING, Any, Optional, Type, List, Literal, Union
+
+from pydantic.json_schema import SkipJsonSchema
+
+from opentrons.types import NozzleConfigurationType
+
+from ..errors import ErrorOccurrence
+from ..types import NextTipInfo, NoTipAvailable, NoTipReason
+from .pipetting_common import PipetteIdMixin
+
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+)
+
+if TYPE_CHECKING:
+    from ..state.state import StateView
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+GetNextTipCommandType = Literal["getNextTip"]
+
+
+class GetNextTipParams(PipetteIdMixin):
+    """Payload needed to resolve the next available tip."""
+
+    labwareIds: List[str] = Field(
+        ...,
+        description="Labware ID(s) of tip racks to resolve next available tip(s) from"
+        " Labware IDs will be resolved sequentially",
+    )
+    startingTipWell: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Name of starting tip rack 'well'."
+        " This only applies to the first tip rack in the list provided in labwareIDs",
+        json_schema_extra=_remove_default,
+    )
+
+
+class GetNextTipResult(BaseModel):
+    """Result data from the execution of a GetNextTip."""
+
+    nextTipInfo: Union[NextTipInfo, NoTipAvailable] = Field(
+        ...,
+        description="Labware ID and well name of next available tip for a pipette,"
+        " or information why no tip could be resolved.",
+    )
+
+
+class GetNextTipImplementation(
+    AbstractCommandImpl[GetNextTipParams, SuccessData[GetNextTipResult]]
+):
+    """Get next tip command implementation."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        **kwargs: object,
+    ) -> None:
+        self._state_view = state_view
+
+    async def execute(self, params: GetNextTipParams) -> SuccessData[GetNextTipResult]:
+        """Get the next available tip for the requested pipette."""
+        pipette_id = params.pipetteId
+        starting_tip_name = params.startingTipWell
+
+        num_tips = self._state_view.pipettes.get_active_channels(pipette_id)
+        nozzle_map = self._state_view.pipettes.get_nozzle_configuration(pipette_id)
+
+        if (
+            starting_tip_name is not None
+            and nozzle_map.configuration != NozzleConfigurationType.FULL
+        ):
+            # This is to match the behavior found in PAPI, but also because we don't have logic to automatically find
+            # the next tip with partial configuration and a starting tip. This will never work for a 96-channel due to
+            # x-axis overlap, but could eventually work with 8-channel if we better define starting tip USED or CLEAN
+            # state when starting a protocol to prevent accidental tip pick-up with starting non-full tip racks.
+            return SuccessData(
+                public=GetNextTipResult(
+                    nextTipInfo=NoTipAvailable(
+                        noTipReason=NoTipReason.STARTING_TIP_WITH_PARTIAL,
+                        message="Cannot automatically resolve next tip with starting tip and partial tip configuration.",
+                    )
+                )
+            )
+
+        next_tip: Union[NextTipInfo, NoTipAvailable]
+        for labware_id in params.labwareIds:
+            well_name = self._state_view.tips.get_next_tip(
+                labware_id=labware_id,
+                num_tips=num_tips,
+                starting_tip_name=starting_tip_name,
+                nozzle_map=nozzle_map,
+            )
+            if well_name is not None:
+                next_tip = NextTipInfo(labwareId=labware_id, tipStartingWell=well_name)
+                break
+            # After the first tip rack is exhausted, starting tip no longer applies
+            starting_tip_name = None
+        else:
+            next_tip = NoTipAvailable(
+                noTipReason=NoTipReason.NO_AVAILABLE_TIPS,
+                message="No available tips for given pipette, nozzle configuration and provided tip racks.",
+            )
+
+        return SuccessData(public=GetNextTipResult(nextTipInfo=next_tip))
+
+
+class GetNextTip(BaseCommand[GetNextTipParams, GetNextTipResult, ErrorOccurrence]):
+    """Get next tip command model."""
+
+    commandType: GetNextTipCommandType = "getNextTip"
+    params: GetNextTipParams
+    result: Optional[GetNextTipResult] = None
+
+    _ImplementationCls: Type[GetNextTipImplementation] = GetNextTipImplementation
+
+
+class GetNextTipCreate(BaseCommandCreate[GetNextTipParams]):
+    """Get next tip command creation request model."""
+
+    commandType: GetNextTipCommandType = "getNextTip"
+    params: GetNextTipParams
+
+    _CommandCls: Type[GetNextTip] = GetNextTip

opentrons/protocol_engine/commands/get_tip_presence.py

@@ -0,0 +1,87 @@
+"""Get tip presence command request, result and implementation models."""
+from __future__ import annotations
+
+from pydantic import Field, BaseModel
+from typing import TYPE_CHECKING, Optional, Type
+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 TipPresenceStatus
+
+if TYPE_CHECKING:
+    from ..execution import TipHandler
+
+
+GetTipPresenceCommandType = Literal["getTipPresence"]
+
+
+class GetTipPresenceParams(PipetteIdMixin):
+    """Payload required for a GetTipPresence command."""
+
+    pass
+
+
+class GetTipPresenceResult(BaseModel):
+    """Result data from the execution of a GetTipPresence command."""
+
+    status: TipPresenceStatus = Field(
+        ...,
+        description=(
+            "Whether or not a tip is attached on the pipette. This only works on"
+            " on FLEX because OT-2 pipettes do not possess tip presence sensors,"
+            " hence, will always return TipPresenceStatus.UNKNOWN."
+        ),
+    )
+
+
+class GetTipPresenceImplementation(
+    AbstractCommandImpl[GetTipPresenceParams, SuccessData[GetTipPresenceResult]]
+):
+    """GetTipPresence command implementation."""
+
+    def __init__(
+        self,
+        tip_handler: TipHandler,
+        **kwargs: object,
+    ) -> None:
+        self._tip_handler = tip_handler
+
+    async def execute(
+        self, params: GetTipPresenceParams
+    ) -> SuccessData[GetTipPresenceResult]:
+        """Verify if tip presence is as expected for the requested pipette."""
+        pipette_id = params.pipetteId
+
+        result = await self._tip_handler.get_tip_presence(
+            pipette_id=pipette_id,
+        )
+
+        return SuccessData(
+            public=GetTipPresenceResult(status=result),
+        )
+
+
+class GetTipPresence(
+    BaseCommand[GetTipPresenceParams, GetTipPresenceResult, ErrorOccurrence]
+):
+    """GetTipPresence command model."""
+
+    commandType: GetTipPresenceCommandType = "getTipPresence"
+    params: GetTipPresenceParams
+    result: Optional[GetTipPresenceResult] = None
+
+    _ImplementationCls: Type[
+        GetTipPresenceImplementation
+    ] = GetTipPresenceImplementation
+
+
+class GetTipPresenceCreate(BaseCommandCreate[GetTipPresenceParams]):
+    """GetTipPresence command creation request model."""
+
+    commandType: GetTipPresenceCommandType = "getTipPresence"
+    params: GetTipPresenceParams
+
+    _CommandCls: Type[GetTipPresence] = GetTipPresence

opentrons/protocol_engine/commands/hash_command_params.py

@@ -0,0 +1,38 @@
+"""Hash command params into idempotent keys to track commands from analysis to run."""
+from hashlib import md5
+from typing import Optional
+
+from .command import CommandIntent
+from .command_unions import CommandCreate
+
+
+# TODO(mm, 2023-04-28):
+# This implementation will not notice that commands are different if they have different params
+# but share the same commandType. We should also hash command params. (Jira RCORE-326.)
+def hash_protocol_command_params(
+    create: CommandCreate, last_hash: Optional[str]
+) -> Optional[str]:
+    """Given a command create object, return a hash.
+
+    The hash is based on three things:
+    - The command parameters
+    - The latest hash (yo dawg I heard you like blockchains)
+    - Whether the command is a setup command or a protocol command;
+      setup commands are not hashed
+
+    Args:
+        create: The command create request.
+        last_hash: The last command hash, if it exists.
+
+    Returns:
+        The command hash, if the command is a protocol command.
+        `None` if the command is a setup command.
+    """
+    if create.intent in [CommandIntent.SETUP, CommandIntent.FIXIT]:
+        return None
+    # We avoid Python's built-in hash() function because it's not stable across
+    # runs of the Python interpreter. (Jira RSS-215.)
+    last_contribution = b"" if last_hash is None else last_hash.encode("ascii")
+    this_contribution = md5(create.commandType.encode("ascii")).digest()
+    to_hash = last_contribution + this_contribution
+    return md5(to_hash).hexdigest()