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

opentrons/protocol_engine/commands/flex_stacker/store.py

@@ -0,0 +1,291 @@
+"""Command models to retrieve a labware from a Flex Stacker."""
+
+from __future__ import annotations
+from typing import Optional, Literal, TYPE_CHECKING, Type, Union
+
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..flex_stacker.common import FlexStackerStallOrCollisionError
+from ...errors import (
+    ErrorOccurrence,
+    CannotPerformModuleAction,
+    LabwareNotLoadedOnModuleError,
+    FlexStackerLabwarePoolNotYetDefinedError,
+)
+from ...resources import ModelUtils
+from ...state import update_types
+from ...types import (
+    LabwareLocationSequence,
+    InStackerHopperLocation,
+)
+
+from opentrons_shared_data.errors.exceptions import FlexStackerStallError
+from opentrons.calibration_storage.helpers import uri_from_details
+
+
+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.",
+    )
+
+
+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],
+]
+
+
+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]:
+        try:
+            bottom_id = self._state_view.labware.get_id_by_module(params.moduleId)
+        except LabwareNotLoadedOnModuleError:
+            raise CannotPerformModuleAction(
+                "Cannot store labware if Flex Stacker 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(
+                "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+            )
+        if stacker_state.pool_lid_definition is not None:
+            if labware_defs[-1] != stacker_state.pool_lid_definition:
+                raise CannotPerformModuleAction(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            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(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            else:
+                return labware_ids[1], labware_ids[0], lid_id
+        else:
+            if labware_defs[0] != stacker_state.pool_primary_definition:
+                raise CannotPerformModuleAction(
+                    "Cannot store labware stack that does not correspond with Flex Stacker configuration"
+                )
+            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
+        )
+
+        if stacker_state.pool_count == stacker_state.max_pool_count:
+            raise CannotPerformModuleAction(
+                "Cannot store labware in Flex Stacker while it is full"
+            )
+
+        pool_definitions = stacker_state.get_pool_definition_ordered_list()
+        if pool_definitions is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                message="The Flex Stacker has not been configured yet and cannot be filled."
+            )
+
+        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)
+
+        eventual_target_location_sequence = (
+            self._state_view.geometry.get_predicted_location_sequence(
+                InStackerHopperLocation(moduleId=params.moduleId)
+            )
+        )
+        stack_height = self._state_view.geometry.get_height_of_labware_stack(
+            pool_definitions
+        )
+
+        state_update = update_types.StateUpdate()
+        try:
+            if stacker_hw is not None:
+                await stacker_hw.store_labware(labware_height=stack_height)
+        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,
+                        )
+                    ],
+                ),
+            )
+
+        id_list = [
+            id for id in (primary_id, maybe_adapter_id, maybe_lid_id) if id is not None
+        ]
+
+        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_labware_pool_count(
+            module_id=params.moduleId, count=stacker_state.pool_count + 1
+        )
+        if stacker_state.pool_primary_definition is None:
+            raise FlexStackerLabwarePoolNotYetDefinedError(
+                "The Primary Labware must be defined in the stacker pool."
+            )
+
+        return SuccessData(
+            public=StoreResult(
+                eventualDestinationLocationSequence=eventual_target_location_sequence,
+                primaryOriginLocationSequence=self._state_view.geometry.get_location_sequence(
+                    primary_id
+                ),
+                primaryLabwareId=primary_id,
+                adapterOriginLocationSequence=(
+                    self._state_view.geometry.get_location_sequence(maybe_adapter_id)
+                    if maybe_adapter_id is not None
+                    else None
+                ),
+                adapterLabwareId=maybe_adapter_id,
+                lidOriginLocationSequence=(
+                    self._state_view.geometry.get_location_sequence(maybe_lid_id)
+                    if maybe_lid_id is not None
+                    else None
+                ),
+                lidLabwareId=maybe_lid_id,
+                primaryLabwareURI=uri_from_details(
+                    stacker_state.pool_primary_definition.namespace,
+                    stacker_state.pool_primary_definition.parameters.loadName,
+                    stacker_state.pool_primary_definition.version,
+                ),
+                adapterLabwareURI=uri_from_details(
+                    stacker_state.pool_adapter_definition.namespace,
+                    stacker_state.pool_adapter_definition.parameters.loadName,
+                    stacker_state.pool_adapter_definition.version,
+                )
+                if stacker_state.pool_adapter_definition is not None
+                else None,
+                lidLabwareURI=uri_from_details(
+                    stacker_state.pool_lid_definition.namespace,
+                    stacker_state.pool_lid_definition.parameters.loadName,
+                    stacker_state.pool_lid_definition.version,
+                )
+                if stacker_state.pool_lid_definition is not None
+                else None,
+            ),
+            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

@@ -5,6 +5,9 @@ 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."""
@@ -14,6 +17,13 @@ def generate_command_schema(version: str) -> str:
     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",
@@ -22,10 +32,29 @@ if __name__ == "__main__":
     parser.add_argument(
         "version",
         type=str,
-        help="The command schema version. This is a single integer (e.g. 7) that will be used to name the generated schema file",
+        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()
-    print(generate_command_schema(args.version))
+
+    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()
 

opentrons/protocol_engine/commands/labware_handling_common.py

@@ -0,0 +1,29 @@
+"""Helpers for commands that alter the position of labware."""
+
+from pydantic import BaseModel, Field
+
+from ..types import LabwareLocationSequence
+
+
+class LabwareHandlingResultMixin(BaseModel):
+    """A result for commands that create a labware entity."""
+
+    labwareId: str = Field(..., description="The id of the labware.")
+    locationSequence: LabwareLocationSequence | None = Field(
+        None,
+        description=(
+            "The full location down to the deck on which this labware exists."
+            " The reason this can be `null` or omitted is just backwards compatibility,"
+            " for older runs and analyses. This should always be present"
+            " for new runs and analyses, even for labware whose location is off-deck."
+        ),
+    )
+
+
+class LabwarePositionResultMixin(LabwareHandlingResultMixin):
+    """A result for commands that create an offsetable labware entity."""
+
+    offsetId: str | None = Field(
+        None,
+        description="An ID referencing the labware offset that will apply to this labware in this location.",
+    )

opentrons/protocol_engine/commands/liquid_probe.py

@@ -22,7 +22,7 @@ from opentrons_shared_data.errors.exceptions import (
     PipetteOverpressureError,
 )
 
-from ..types import DeckPoint
+from ..types import DeckPoint, LiquidTrackingType
 from .pipetting_common import (
     LiquidNotFoundError,
     PipetteIdMixin,
@@ -80,7 +80,7 @@ class TryLiquidProbeParams(_CommonParams):
 class LiquidProbeResult(DestinationPositionResult):
     """Result data from the execution of a `liquidProbe` command."""
 
-    z_position: float = Field(
+    z_position: LiquidTrackingType = Field(
         ..., description="The Z coordinate, in mm, of the found liquid in deck space."
     )
     # New fields should use camelCase. z_position is snake_case for historical reasons.
@@ -89,7 +89,7 @@ class LiquidProbeResult(DestinationPositionResult):
 class TryLiquidProbeResult(DestinationPositionResult):
     """Result data from the execution of a `tryLiquidProbe` command."""
 
-    z_position: float | SkipJsonSchema[None] = Field(
+    z_position: Union[LiquidTrackingType, SkipJsonSchema[None]] = Field(
         ...,
         description=(
             "The Z coordinate, in mm, of the found liquid in deck space."
@@ -116,8 +116,7 @@ class _ExecuteCommonResult(NamedTuple):
     # If the probe succeeded, the z_pos that it returned.
     # Or, if the probe found no liquid, the error representing that,
     # so calling code can propagate those details up.
-    z_pos_or_error: float | PipetteLiquidNotFoundError | PipetteOverpressureError
-
+    z_pos_or_error: LiquidTrackingType | PipetteLiquidNotFoundError | PipetteOverpressureError
     state_update: update_types.StateUpdate
     deck_point: DeckPoint
 
@@ -189,7 +188,16 @@ async def _execute_common(  # noqa: C901
             well_name=well_name,
             well_location=params.wellLocation,
         )
+        state_view.geometry.validate_probed_height(
+            labware_id=labware_id,
+            well_name=well_name,
+            pipette_id=pipette_id,
+            probed_height=z_pos,
+        )
     except PipetteLiquidNotFoundError as exception:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=exception,
             state_update=move_result.state_update,
@@ -223,6 +231,9 @@ async def _execute_common(  # noqa: C901
             ),
         )
     else:
+        move_result.state_update.set_pipette_ready_to_aspirate(
+            pipette_id=pipette_id, ready_to_aspirate=True
+        )
         return _ExecuteCommonResult(
             z_pos_or_error=z_pos,
             state_update=move_result.state_update,
@@ -303,12 +314,13 @@ class LiquidProbeImplementation(
             )
         else:
             try:
-                well_volume: float | update_types.ClearType = (
-                    self._state_view.geometry.get_well_volume_at_height(
-                        labware_id=params.labwareId,
-                        well_name=params.wellName,
-                        height=z_pos_or_error,
-                    )
+                well_volume: Union[
+                    LiquidTrackingType,
+                    update_types.ClearType,
+                ] = self._state_view.geometry.get_well_volume_at_height(
+                    labware_id=params.labwareId,
+                    well_name=params.wellName,
+                    height=z_pos_or_error,
                 )
             except IncompleteLabwareDefinitionError:
                 well_volume = update_types.CLEAR
@@ -370,7 +382,10 @@ class TryLiquidProbeImplementation(
             z_pos_or_error, (PipetteLiquidNotFoundError, PipetteOverpressureError)
         ):
             z_pos = None
-            well_volume: float | update_types.ClearType = update_types.CLEAR
+            well_volume: Union[
+                LiquidTrackingType,
+                update_types.ClearType,
+            ] = update_types.CLEAR
         else:
             z_pos = z_pos_or_error
             try:
@@ -387,7 +402,6 @@ class TryLiquidProbeImplementation(
             volume=well_volume,
             last_probed=self._model_utils.get_timestamp(),
         )
-
         return SuccessData(
             public=TryLiquidProbeResult(
                 z_position=z_pos,

opentrons/protocol_engine/commands/load_labware.py

@@ -1,25 +1,28 @@
 """Load labware 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 typing_extensions import Literal, TypeGuard
 
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 
 from ..errors import LabwareIsNotAllowedInLocationError
 from ..resources import labware_validation, fixture_validation
 from ..types import (
-    LabwareLocation,
+    LoadableLabwareLocation,
     ModuleLocation,
     ModuleModel,
     OnLabwareLocation,
     DeckSlotLocation,
     AddressableAreaLocation,
+    LoadedModule,
 )
 
 from .command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from .labware_handling_common import LabwarePositionResultMixin
 from ..errors.error_occurrence import ErrorOccurrence
 from ..state.update_types import StateUpdate
 
@@ -38,7 +41,7 @@ def _remove_default(s: dict[str, Any]) -> None:
 class LoadLabwareParams(BaseModel):
     """Payload required to load a labware into a slot."""
 
-    location: LabwareLocation = Field(
+    location: LoadableLabwareLocation = Field(
         ...,
         description="Location the labware should be loaded into.",
     )
@@ -71,30 +74,13 @@ class LoadLabwareParams(BaseModel):
     )
 
 
-class LoadLabwareResult(BaseModel):
+class LoadLabwareResult(LabwarePositionResultMixin):
     """Result data from the execution of a LoadLabware command."""
 
-    labwareId: str = Field(
-        ...,
-        description="An ID to reference this labware in subsequent commands.",
-    )
     definition: LabwareDefinition = Field(
         ...,
         description="The full definition data for this labware.",
     )
-    offsetId: Optional[str] = Field(
-        # Default `None` instead of `...` so this field shows up as non-required in
-        # OpenAPI. The server is allowed to omit it or make it null.
-        None,
-        description=(
-            "An ID referencing the labware offset that will apply"
-            " to the newly-placed labware."
-            " This offset will be in effect until the labware is moved"
-            " with a `moveLabware` command."
-            " Null or undefined means no offset applies,"
-            " so the default of (0, 0, 0) will be used."
-        ),
-    )
 
 
 class LoadLabwareImplementation(
@@ -108,6 +94,15 @@ class LoadLabwareImplementation(
         self._equipment = equipment
         self._state_view = state_view
 
+    def _is_loading_to_module(
+        self, location: LoadableLabwareLocation, module_model: ModuleModel
+    ) -> TypeGuard[ModuleLocation]:
+        if not isinstance(location, ModuleLocation):
+            return False
+
+        module: LoadedModule = self._state_view.modules.get(location.moduleId)
+        return module.model == module_model
+
     async def execute(
         self, params: LoadLabwareParams
     ) -> SuccessData[LoadLabwareResult]:
@@ -148,6 +143,7 @@ class LoadLabwareImplementation(
         verified_location = self._state_view.geometry.ensure_location_not_occupied(
             params.location
         )
+
         loaded_labware = await self._equipment.load_labware(
             load_name=params.loadName,
             namespace=params.namespace,
@@ -164,34 +160,38 @@ class LoadLabwareImplementation(
             display_name=params.displayName,
         )
 
-        # TODO(jbl 2023-06-23) these validation checks happen after the labware is loaded, because they rely on
-        #   on the definition. In practice this will not cause any issues since they will raise protocol ending
-        #   exception, but for correctness should be refactored to do this check beforehand.
         if isinstance(verified_location, OnLabwareLocation):
             self._state_view.labware.raise_if_labware_cannot_be_stacked(
                 top_labware_definition=loaded_labware.definition,
                 bottom_labware_id=verified_location.labwareId,
             )
             # Validate load location is valid for lids
-            if (
-                labware_validation.validate_definition_is_lid(
-                    definition=loaded_labware.definition
-                )
-                and loaded_labware.definition.compatibleParentLabware is not None
-                and self._state_view.labware.get_load_name(verified_location.labwareId)
-                not in loaded_labware.definition.compatibleParentLabware
+            if labware_validation.validate_definition_is_lid(
+                definition=loaded_labware.definition
             ):
-                raise ValueError(
-                    f"Labware Lid {params.loadName} may not be loaded on parent labware {self._state_view.labware.get_display_name(verified_location.labwareId)}."
+                # This parent is assumed to be compatible, unless the lid enumerates
+                # all its compatible parents and this parent is missing from the list.
+                parent_is_incompatible = (
+                    loaded_labware.definition.compatibleParentLabware is not None
+                    and self._state_view.labware.get_load_name(
+                        verified_location.labwareId
+                    )
+                    not in loaded_labware.definition.compatibleParentLabware
                 )
 
+                if parent_is_incompatible:
+                    raise ValueError(
+                        f"Labware Lid {params.loadName} may not be loaded on parent labware"
+                        f" {self._state_view.labware.get_display_name(verified_location.labwareId)}."
+                    )
+
         # Validate labware for the absorbance reader
-        elif isinstance(params.location, ModuleLocation):
-            module = self._state_view.modules.get(params.location.moduleId)
-            if module is not None and module.model == ModuleModel.ABSORBANCE_READER_V1:
-                self._state_view.labware.raise_if_labware_incompatible_with_plate_reader(
-                    loaded_labware.definition
-                )
+        if self._is_loading_to_module(
+            params.location, ModuleModel.ABSORBANCE_READER_V1
+        ):
+            self._state_view.labware.raise_if_labware_incompatible_with_plate_reader(
+                loaded_labware.definition
+            )
 
         self._state_view.labware.raise_if_labware_cannot_be_ondeck(
             location=params.location, labware_definition=loaded_labware.definition
@@ -202,6 +202,9 @@ class LoadLabwareImplementation(
                 labwareId=loaded_labware.labware_id,
                 definition=loaded_labware.definition,
                 offsetId=loaded_labware.offsetId,
+                locationSequence=self._state_view.geometry.get_predicted_location_sequence(
+                    verified_location,
+                ),
             ),
             state_update=state_update,
         )