opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/commands/absorbance_reader/read.py

@@ -0,0 +1,226 @@
+"""Command models to read absorbance."""
+from __future__ import annotations
+from datetime import datetime
+from typing import Optional, Dict, TYPE_CHECKING, List, Any
+
+from typing_extensions import Literal, Type
+from pydantic import BaseModel, Field
+from pydantic.json_schema import SkipJsonSchema
+
+from ..command import AbstractCommandImpl, BaseCommand, BaseCommandCreate, SuccessData
+from ...errors import CannotPerformModuleAction, StorageLimitReachedError
+from ...errors.error_occurrence import ErrorOccurrence
+
+from ...resources.file_provider import (
+    PlateReaderData,
+    ReadData,
+    MAXIMUM_CSV_FILE_LIMIT,
+)
+from ...resources import FileProvider
+from ...state import update_types
+
+if TYPE_CHECKING:
+    from opentrons.protocol_engine.state.state import StateView
+    from opentrons.protocol_engine.execution import EquipmentHandler
+
+
+def _remove_default(s: dict[str, Any]) -> None:
+    s.pop("default", None)
+
+
+ReadAbsorbanceCommandType = Literal["absorbanceReader/read"]
+
+
+class ReadAbsorbanceParams(BaseModel):
+    """Input parameters for an absorbance reading."""
+
+    moduleId: str = Field(..., description="Unique ID of the Absorbance Reader.")
+    fileName: str | SkipJsonSchema[None] = Field(
+        None,
+        description="Optional file name to use when storing the results of a measurement.",
+        json_schema_extra=_remove_default,
+    )
+
+
+class ReadAbsorbanceResult(BaseModel):
+    """Result data from running an aborbance reading, returned as a dictionary map of wavelengths containing a map of values by well name (eg. {450: {"A1": 0.0, ...}})."""
+
+    data: Optional[Dict[int, Dict[str, float]]] = Field(
+        ..., description="Absorbance data points per wavelength."
+    )
+    fileIds: Optional[List[str]] = Field(
+        ...,
+        description="List of file IDs for files output as a result of a Read action.",
+    )
+
+
+class ReadAbsorbanceImpl(
+    AbstractCommandImpl[ReadAbsorbanceParams, SuccessData[ReadAbsorbanceResult]]
+):
+    """Execution implementation of an Absorbance Reader measurement."""
+
+    def __init__(
+        self,
+        state_view: StateView,
+        equipment: EquipmentHandler,
+        file_provider: FileProvider,
+        **unused_dependencies: object,
+    ) -> None:
+        self._state_view = state_view
+        self._equipment = equipment
+        self._file_provider = file_provider
+
+    async def execute(  # noqa: C901
+        self, params: ReadAbsorbanceParams
+    ) -> SuccessData[ReadAbsorbanceResult]:
+        """Initiate an absorbance measurement."""
+        state_update = update_types.StateUpdate()
+        abs_reader_substate = self._state_view.modules.get_absorbance_reader_substate(
+            module_id=params.moduleId
+        )
+
+        # Allow propagation of ModuleNotAttachedError.
+        abs_reader = self._equipment.get_module_hardware_api(
+            abs_reader_substate.module_id
+        )
+
+        if abs_reader_substate.configured is False:
+            raise CannotPerformModuleAction(
+                "Cannot perform Read action on Absorbance Reader without calling `.initialize(...)` first."
+            )
+        if abs_reader_substate.is_lid_on is False:
+            raise CannotPerformModuleAction(
+                "Absorbance Plate Reader can't read a plate with the lid open. Call `close_lid()` first."
+            )
+
+        # TODO: we need to return a file ID and increase the file count even when a moduel is not attached
+        if (
+            params.fileName is not None
+            and abs_reader_substate.configured_wavelengths is not None
+        ):
+            # Validate that the amount of files we are about to generate does not put us higher than the limit
+            if (
+                self._state_view.files.get_filecount()
+                + len(abs_reader_substate.configured_wavelengths)
+                > MAXIMUM_CSV_FILE_LIMIT
+            ):
+                raise StorageLimitReachedError(
+                    message=f"Attempt to write file {params.fileName} exceeds file creation limit of {MAXIMUM_CSV_FILE_LIMIT} files."
+                )
+
+        asbsorbance_result: Dict[int, Dict[str, float]] = {}
+        transform_results = []
+        # Handle the measurement and begin building data for return
+        if abs_reader is not None:
+            start_time = datetime.now()
+            results = await abs_reader.start_measure()
+            finish_time = datetime.now()
+            if abs_reader._measurement_config is not None:
+                sample_wavelengths = abs_reader._measurement_config.sample_wavelengths
+                for wavelength, result in zip(sample_wavelengths, results):
+                    converted_values = (
+                        self._state_view.modules.convert_absorbance_reader_data_points(
+                            data=result
+                        )
+                    )
+                    asbsorbance_result[wavelength] = converted_values
+                    transform_results.append(
+                        ReadData.model_construct(
+                            wavelength=wavelength, data=converted_values
+                        )
+                    )
+        # Handle the virtual module case for data creation (all zeroes)
+        elif self._state_view.config.use_virtual_modules:
+            start_time = finish_time = datetime.now()
+            if abs_reader_substate.configured_wavelengths is not None:
+                for wavelength in abs_reader_substate.configured_wavelengths:
+                    converted_values = (
+                        self._state_view.modules.convert_absorbance_reader_data_points(
+                            data=[0] * 96
+                        )
+                    )
+                    asbsorbance_result[wavelength] = converted_values
+                    transform_results.append(
+                        ReadData.model_construct(
+                            wavelength=wavelength, data=converted_values
+                        )
+                    )
+            else:
+                raise CannotPerformModuleAction(
+                    "Plate Reader data cannot be requested with a module that has not been initialized."
+                )
+
+        state_update.set_absorbance_reader_data(
+            module_id=abs_reader_substate.module_id, read_result=asbsorbance_result
+        )
+        # TODO (cb, 10-17-2024): FILE PROVIDER - Some day we may want to break the file provider behavior into a seperate API function.
+        # When this happens, we probably will to have the change the command results handler we utilize to track file IDs in engine.
+        # Today, the action handler for the FileStore looks for a ReadAbsorbanceResult command action, this will need to be delinked.
+
+        # Begin interfacing with the file provider if the user provided a filename
+        file_ids: list[str] = []
+        if params.fileName is not None:
+            # Create the Plate Reader Transform
+            plate_read_result = PlateReaderData.model_construct(
+                read_results=transform_results,
+                reference_wavelength=abs_reader_substate.reference_wavelength,
+                start_time=start_time,
+                finish_time=finish_time,
+                serial_number=abs_reader.serial_number
+                if (abs_reader is not None and abs_reader.serial_number is not None)
+                else "VIRTUAL_SERIAL",
+            )
+
+            if isinstance(plate_read_result, PlateReaderData):
+                # Write a CSV file for each of the measurements taken
+                for measurement in plate_read_result.read_results:
+                    file_id = await self._file_provider.write_csv(
+                        write_data=plate_read_result.build_generic_csv(
+                            filename=params.fileName,
+                            measurement=measurement,
+                        )
+                    )
+                    file_ids.append(file_id)
+
+                state_update.files_added = update_types.FilesAddedUpdate(
+                    file_ids=file_ids
+                )
+                # Return success data to api
+                return SuccessData(
+                    public=ReadAbsorbanceResult(
+                        data=asbsorbance_result,
+                        fileIds=file_ids,
+                    ),
+                    state_update=state_update,
+                )
+
+        state_update.files_added = update_types.FilesAddedUpdate(file_ids=file_ids)
+
+        return SuccessData(
+            public=ReadAbsorbanceResult(
+                data=asbsorbance_result,
+                fileIds=file_ids,
+            ),
+            state_update=state_update,
+        )
+
+
+class ReadAbsorbance(
+    BaseCommand[ReadAbsorbanceParams, ReadAbsorbanceResult, ErrorOccurrence]
+):
+    """A command to execute an Absorbance Reader measurement."""
+
+    commandType: ReadAbsorbanceCommandType = "absorbanceReader/read"
+    params: ReadAbsorbanceParams
+    result: Optional[ReadAbsorbanceResult] = None
+
+    _ImplementationCls: Type[ReadAbsorbanceImpl] = ReadAbsorbanceImpl
+
+
+class ReadAbsorbanceCreate(BaseCommandCreate[ReadAbsorbanceParams]):
+    """A request to execute an Absorbance Reader measurement."""
+
+    commandType: ReadAbsorbanceCommandType = "absorbanceReader/read"
+    params: ReadAbsorbanceParams
+
+    _CommandCls: Type[ReadAbsorbance] = ReadAbsorbance

opentrons/protocol_engine/commands/air_gap_in_place.py

@@ -0,0 +1,162 @@
+"""AirGap in place command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from opentrons_shared_data.errors.exceptions import PipetteOverpressureError
+
+from opentrons.hardware_control import HardwareControlAPI
+
+from .pipetting_common import (
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    BaseLiquidHandlingResult,
+    OverpressureError,
+    DEFAULT_CORRECTION_VOLUME,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    SuccessData,
+    DefinedErrorData,
+)
+from ..errors.error_occurrence import ErrorOccurrence
+from ..errors.exceptions import PipetteNotReadyToAspirateError
+from ..state.update_types import StateUpdate
+from ..types import AspiratedFluid, FluidKind
+
+if TYPE_CHECKING:
+    from ..execution import PipettingHandler, GantryMover
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+    from ..notes import CommandNoteAdder
+
+AirGapInPlaceCommandType = Literal["airGapInPlace"]
+
+
+class AirGapInPlaceParams(PipetteIdMixin, AspirateVolumeMixin, FlowRateMixin):
+    """Payload required to air gap in place."""
+
+    pass
+
+
+class AirGapInPlaceResult(BaseLiquidHandlingResult):
+    """Result data from the execution of a AirGapInPlace command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[AirGapInPlaceResult],
+    DefinedErrorData[OverpressureError],
+]
+
+
+class AirGapInPlaceImplementation(
+    AbstractCommandImpl[AirGapInPlaceParams, _ExecuteReturn]
+):
+    """AirGapInPlace command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        hardware_api: HardwareControlAPI,
+        state_view: StateView,
+        command_note_adder: CommandNoteAdder,
+        model_utils: ModelUtils,
+        gantry_mover: GantryMover,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._command_note_adder = command_note_adder
+        self._model_utils = model_utils
+        self._gantry_mover = gantry_mover
+
+    async def execute(self, params: AirGapInPlaceParams) -> _ExecuteReturn:
+        """Air gap without moving the pipette.
+
+        Raises:
+            TipNotAttachedError: if no tip is attached to the pipette.
+            PipetteNotReadyToAirGapError: pipette plunger is not ready.
+        """
+        ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
+            pipette_id=params.pipetteId
+        )
+        if not ready_to_aspirate:
+            raise PipetteNotReadyToAspirateError(
+                "Pipette cannot air gap in place because a previous dispense or blowout"
+                " pushed the plunger beyond the bottom position."
+                " The subsequent aspirate must be from a specific well so the plunger"
+                " can be reset in a known safe position."
+            )
+
+        state_update = StateUpdate()
+
+        try:
+            current_position = await self._gantry_mover.get_position(params.pipetteId)
+            volume = await self._pipetting.aspirate_in_place(
+                pipette_id=params.pipetteId,
+                volume=params.volume,
+                flow_rate=params.flowRate,
+                command_note_adder=self._command_note_adder,
+                correction_volume=params.correctionVolume or DEFAULT_CORRECTION_VOLUME,
+            )
+        except PipetteOverpressureError as e:
+            return DefinedErrorData(
+                public=OverpressureError(
+                    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=(
+                        {
+                            "retryLocation": (
+                                current_position.x,
+                                current_position.y,
+                                current_position.z,
+                            )
+                        }
+                    ),
+                ),
+                state_update=state_update,
+            )
+        else:
+            state_update.set_fluid_aspirated(
+                pipette_id=params.pipetteId,
+                fluid=AspiratedFluid(kind=FluidKind.AIR, volume=volume),
+            )
+            return SuccessData(
+                public=AirGapInPlaceResult(volume=volume),
+                state_update=state_update,
+            )
+
+
+class AirGapInPlace(
+    BaseCommand[AirGapInPlaceParams, AirGapInPlaceResult, OverpressureError]
+):
+    """AirGapInPlace command model."""
+
+    commandType: AirGapInPlaceCommandType = "airGapInPlace"
+    params: AirGapInPlaceParams
+    result: Optional[AirGapInPlaceResult] = None
+
+    _ImplementationCls: Type[AirGapInPlaceImplementation] = AirGapInPlaceImplementation
+
+
+class AirGapInPlaceCreate(BaseCommandCreate[AirGapInPlaceParams]):
+    """AirGapInPlace command request model."""
+
+    commandType: AirGapInPlaceCommandType = "airGapInPlace"
+    params: AirGapInPlaceParams
+
+    _CommandCls: Type[AirGapInPlace] = AirGapInPlace

opentrons/protocol_engine/commands/aspirate.py

@@ -0,0 +1,244 @@
+"""Aspirate command request, result, and implementation models."""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional, Type, Union
+from typing_extensions import Literal
+
+from .pipetting_common import (
+    OverpressureError,
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    BaseLiquidHandlingResult,
+    aspirate_in_place,
+    prepare_for_aspirate,
+    DEFAULT_CORRECTION_VOLUME,
+)
+from .movement_common import (
+    LiquidHandlingWellLocationMixin,
+    DestinationPositionResult,
+    StallOrCollisionError,
+    move_to_well,
+)
+from .command import (
+    AbstractCommandImpl,
+    BaseCommand,
+    BaseCommandCreate,
+    DefinedErrorData,
+    SuccessData,
+)
+
+from opentrons.hardware_control import HardwareControlAPI
+
+from ..state.update_types import StateUpdate, CLEAR
+from ..types import (
+    WellLocation,
+    WellOrigin,
+    CurrentWell,
+)
+
+if TYPE_CHECKING:
+    from ..execution import MovementHandler, PipettingHandler
+    from ..resources import ModelUtils
+    from ..state.state import StateView
+    from ..notes import CommandNoteAdder
+
+
+AspirateCommandType = Literal["aspirate"]
+
+
+class AspirateParams(
+    PipetteIdMixin,
+    AspirateVolumeMixin,
+    FlowRateMixin,
+    LiquidHandlingWellLocationMixin,
+):
+    """Parameters required to aspirate from a specific well."""
+
+    pass
+
+
+class AspirateResult(BaseLiquidHandlingResult, DestinationPositionResult):
+    """Result data from execution of an Aspirate command."""
+
+    pass
+
+
+_ExecuteReturn = Union[
+    SuccessData[AspirateResult],
+    DefinedErrorData[OverpressureError] | DefinedErrorData[StallOrCollisionError],
+]
+
+
+class AspirateImplementation(AbstractCommandImpl[AspirateParams, _ExecuteReturn]):
+    """Aspirate command implementation."""
+
+    def __init__(
+        self,
+        pipetting: PipettingHandler,
+        state_view: StateView,
+        hardware_api: HardwareControlAPI,
+        movement: MovementHandler,
+        command_note_adder: CommandNoteAdder,
+        model_utils: ModelUtils,
+        **kwargs: object,
+    ) -> None:
+        self._pipetting = pipetting
+        self._state_view = state_view
+        self._hardware_api = hardware_api
+        self._movement = movement
+        self._command_note_adder = command_note_adder
+        self._model_utils = model_utils
+
+    async def execute(self, params: AspirateParams) -> _ExecuteReturn:
+        """Move to and aspirate from the requested well.
+
+        Raises:
+            TipNotAttachedError: if no tip is attached to the pipette.
+        """
+        pipette_id = params.pipetteId
+        labware_id = params.labwareId
+        well_name = params.wellName
+        well_location = params.wellLocation
+
+        state_update = StateUpdate()
+
+        final_location = self._state_view.geometry.get_well_position(
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+            operation_volume=-params.volume,
+            pipette_id=pipette_id,
+        )
+
+        ready_to_aspirate = self._pipetting.get_is_ready_to_aspirate(
+            pipette_id=pipette_id
+        )
+
+        current_well = None
+
+        if not ready_to_aspirate:
+            move_result = await move_to_well(
+                movement=self._movement,
+                model_utils=self._model_utils,
+                pipette_id=pipette_id,
+                labware_id=labware_id,
+                well_name=well_name,
+                well_location=WellLocation(origin=WellOrigin.TOP),
+            )
+            state_update.append(move_result.state_update)
+            if isinstance(move_result, DefinedErrorData):
+                return DefinedErrorData(move_result.public, state_update=state_update)
+
+            prepare_result = await prepare_for_aspirate(
+                pipette_id=pipette_id,
+                pipetting=self._pipetting,
+                model_utils=self._model_utils,
+                # Note that the retryLocation is the final location, inside the liquid,
+                # because that's where we'd want the client to try re-aspirating if this
+                # command fails and the run enters error recovery.
+                location_if_error={"retryLocation": final_location},
+            )
+            state_update.append(prepare_result.state_update)
+            if isinstance(prepare_result, DefinedErrorData):
+                return DefinedErrorData(
+                    public=prepare_result.public, state_update=state_update
+                )
+
+            # set our current deck location to the well now that we've made
+            # an intermediate move for the "prepare for aspirate" step
+            current_well = CurrentWell(
+                pipette_id=pipette_id,
+                labware_id=labware_id,
+                well_name=well_name,
+            )
+        move_result = await move_to_well(
+            movement=self._movement,
+            model_utils=self._model_utils,
+            pipette_id=pipette_id,
+            labware_id=labware_id,
+            well_name=well_name,
+            well_location=well_location,
+            current_well=current_well,
+            operation_volume=-params.volume,
+        )
+        state_update.append(move_result.state_update)
+        if isinstance(move_result, DefinedErrorData):
+            return DefinedErrorData(
+                public=move_result.public, state_update=state_update
+            )
+
+        aspirate_result = await aspirate_in_place(
+            pipette_id=pipette_id,
+            volume=params.volume,
+            flow_rate=params.flowRate,
+            location_if_error={
+                "retryLocation": (
+                    move_result.public.position.x,
+                    move_result.public.position.y,
+                    move_result.public.position.z,
+                )
+            },
+            command_note_adder=self._command_note_adder,
+            pipetting=self._pipetting,
+            model_utils=self._model_utils,
+            correction_volume=params.correctionVolume or DEFAULT_CORRECTION_VOLUME,
+        )
+        state_update.append(aspirate_result.state_update)
+        if isinstance(aspirate_result, DefinedErrorData):
+            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,
+            )
+            return DefinedErrorData(
+                public=aspirate_result.public, state_update=state_update
+            )
+
+        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, pipette_id
+            ),
+            volume_added=-aspirate_result.public.volume
+            * self._state_view.geometry.get_nozzles_per_well(
+                labware_id,
+                well_name,
+                params.pipetteId,
+            ),
+        )
+
+        return SuccessData(
+            public=AspirateResult(
+                volume=aspirate_result.public.volume,
+                position=move_result.public.position,
+            ),
+            state_update=state_update,
+        )
+
+
+class Aspirate(
+    BaseCommand[
+        AspirateParams, AspirateResult, OverpressureError | StallOrCollisionError
+    ]
+):
+    """Aspirate command model."""
+
+    commandType: AspirateCommandType = "aspirate"
+    params: AspirateParams
+    result: Optional[AspirateResult] = None
+
+    _ImplementationCls: Type[AspirateImplementation] = AspirateImplementation
+
+
+class AspirateCreate(BaseCommandCreate[AspirateParams]):
+    """Create aspirate command request model."""
+
+    commandType: AspirateCommandType = "aspirate"
+    params: AspirateParams
+
+    _CommandCls: Type[Aspirate] = Aspirate