opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_engine/state/liquid_classes.py

@@ -0,0 +1,82 @@
+"""A data store of liquid classes."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Dict
+from typing_extensions import Optional
+
+from .. import errors
+from ..actions import Action, get_state_updates
+from ..types import LiquidClassRecord
+from . import update_types
+from ._abstract_store import HasState, HandlesActions
+
+
+@dataclasses.dataclass
+class LiquidClassState:
+    """Our state is a bidirectional mapping between IDs <-> LiquidClassRecords."""
+
+    # We use the bidirectional map to see if we've already assigned an ID to a liquid class when the
+    # engine is asked to store a new liquid class.
+    liquid_class_record_by_id: Dict[str, LiquidClassRecord]
+    liquid_class_record_to_id: Dict[LiquidClassRecord, str]
+
+
+class LiquidClassStore(HasState[LiquidClassState], HandlesActions):
+    """Container for LiquidClassState."""
+
+    _state: LiquidClassState
+
+    def __init__(self) -> None:
+        self._state = LiquidClassState(
+            liquid_class_record_by_id={},
+            liquid_class_record_to_id={},
+        )
+
+    def handle_action(self, action: Action) -> None:
+        """Update the state in response to the action."""
+        for state_update in get_state_updates(action):
+            if state_update.liquid_class_loaded != update_types.NO_CHANGE:
+                self._handle_liquid_class_loaded_update(
+                    state_update.liquid_class_loaded
+                )
+
+    def _handle_liquid_class_loaded_update(
+        self, state_update: update_types.LiquidClassLoadedUpdate
+    ) -> None:
+        # We're just a data store. All the validation and ID generation happens in the command implementation.
+        self._state.liquid_class_record_by_id[
+            state_update.liquid_class_id
+        ] = state_update.liquid_class_record
+        self._state.liquid_class_record_to_id[
+            state_update.liquid_class_record
+        ] = state_update.liquid_class_id
+
+
+class LiquidClassView:
+    """Read-only view of the LiquidClassState."""
+
+    _state: LiquidClassState
+
+    def __init__(self, state: LiquidClassState) -> None:
+        self._state = state
+
+    def get(self, liquid_class_id: str) -> LiquidClassRecord:
+        """Get the LiquidClassRecord with the given identifier."""
+        try:
+            return self._state.liquid_class_record_by_id[liquid_class_id]
+        except KeyError as e:
+            raise errors.LiquidClassDoesNotExistError(
+                f"Liquid class ID {liquid_class_id} not found."
+            ) from e
+
+    def get_id_for_liquid_class_record(
+        self, liquid_class_record: LiquidClassRecord
+    ) -> Optional[str]:
+        """See if the given LiquidClassRecord if already in the store, and if so, return its identifier."""
+        return self._state.liquid_class_record_to_id.get(liquid_class_record)
+
+    def get_all(self) -> Dict[str, LiquidClassRecord]:
+        """Get all the LiquidClassRecords in the store."""
+        return self._state.liquid_class_record_by_id.copy()

opentrons/protocol_engine/state/liquids.py

@@ -0,0 +1,73 @@
+"""Basic liquid data state and store."""
+from dataclasses import dataclass
+from typing import Dict, List
+from opentrons.protocol_engine.types import Liquid, LiquidId
+
+from ._abstract_store import HasState, HandlesActions
+from ..actions import Action, AddLiquidAction
+from ..errors import LiquidDoesNotExistError, InvalidLiquidError
+
+
+@dataclass
+class LiquidState:
+    """State of all loaded liquids."""
+
+    liquids_by_id: Dict[str, Liquid]
+
+
+class LiquidStore(HasState[LiquidState], HandlesActions):
+    """Liquid state container."""
+
+    _state: LiquidState
+
+    def __init__(self) -> None:
+        """Initialize a liquid store and its state."""
+        self._state = LiquidState(liquids_by_id={})
+
+    def handle_action(self, action: Action) -> None:
+        """Modify state in reaction to an action."""
+        if isinstance(action, AddLiquidAction):
+            self._add_liquid(action)
+
+    def _add_liquid(self, action: AddLiquidAction) -> None:
+        """Add liquid to protocol liquids."""
+        self._state.liquids_by_id[action.liquid.id] = action.liquid
+
+
+class LiquidView:
+    """Read-only liquid state view."""
+
+    _state: LiquidState
+
+    def __init__(self, state: LiquidState) -> None:
+        """Initialize the computed view of liquid state.
+
+        Arguments:
+            state: Liquid state dataclass used for all calculations.
+        """
+        self._state = state
+
+    def get_all(self) -> List[Liquid]:
+        """Get all protocol liquids."""
+        return list(self._state.liquids_by_id.values())
+
+    def validate_liquid_id(self, liquid_id: LiquidId) -> LiquidId:
+        """Check if liquid_id exists in liquids."""
+        is_empty = liquid_id == "EMPTY"
+        if is_empty:
+            return liquid_id
+        has_liquid = liquid_id in self._state.liquids_by_id
+        if not has_liquid:
+            raise LiquidDoesNotExistError(
+                f"Supplied liquidId: {liquid_id} does not exist in the loaded liquids."
+            )
+        return liquid_id
+
+    def validate_liquid_allowed(self, liquid: Liquid) -> Liquid:
+        """Validate that a liquid is legal to load."""
+        is_empty = liquid.id == "EMPTY"
+        if is_empty:
+            raise InvalidLiquidError(
+                message='Protocols may not define a liquid with the special id "EMPTY".'
+            )
+        return liquid

opentrons/protocol_engine/state/module_substates/__init__.py

@@ -0,0 +1,45 @@
+"""Hardware Modules' substates."""
+
+from typing import Union
+from .magnetic_module_substate import MagneticModuleSubState, MagneticModuleId
+from .heater_shaker_module_substate import (
+    HeaterShakerModuleSubState,
+    HeaterShakerModuleId,
+)
+from .temperature_module_substate import TemperatureModuleSubState, TemperatureModuleId
+from .thermocycler_module_substate import (
+    ThermocyclerModuleSubState,
+    ThermocyclerModuleId,
+)
+from .magnetic_block_substate import MagneticBlockSubState, MagneticBlockId
+from .absorbance_reader_substate import AbsorbanceReaderSubState, AbsorbanceReaderId
+from .flex_stacker_substate import FlexStackerSubState, FlexStackerId
+
+ModuleSubStateType = Union[
+    HeaterShakerModuleSubState,
+    MagneticModuleSubState,
+    TemperatureModuleSubState,
+    ThermocyclerModuleSubState,
+    MagneticBlockSubState,
+    AbsorbanceReaderSubState,
+    FlexStackerSubState,
+]
+
+__all__ = [
+    "MagneticModuleSubState",
+    "MagneticModuleId",
+    "HeaterShakerModuleSubState",
+    "HeaterShakerModuleId",
+    "TemperatureModuleSubState",
+    "TemperatureModuleId",
+    "ThermocyclerModuleSubState",
+    "ThermocyclerModuleId",
+    "MagneticBlockSubState",
+    "MagneticBlockId",
+    "AbsorbanceReaderSubState",
+    "AbsorbanceReaderId",
+    "FlexStackerSubState",
+    "FlexStackerId",
+    # Union of all module substates
+    "ModuleSubStateType",
+]

opentrons/protocol_engine/state/module_substates/absorbance_reader_substate.py

@@ -0,0 +1,35 @@
+"""Heater-Shaker Module sub-state."""
+from dataclasses import dataclass
+from typing import List, NewType, Optional, Dict
+
+from opentrons.protocol_engine.errors import CannotPerformModuleAction
+
+AbsorbanceReaderId = NewType("AbsorbanceReaderId", str)
+AbsorbanceReaderLidId = NewType("AbsorbanceReaderLidId", str)
+AbsorbanceReaderMeasureMode = NewType("AbsorbanceReaderMeasureMode", str)
+
+
+# todo(mm, 2024-11-08): frozen=True is getting pretty painful because ModuleStore has
+# no type-safe way to modify just a single attribute. Consider unfreezing this
+# (taking care to ensure that consumers of ModuleView still only get a read-only view).
+@dataclass(frozen=True)
+class AbsorbanceReaderSubState:
+    """Absorbance-Plate-Reader-specific state."""
+
+    module_id: AbsorbanceReaderId
+    configured: bool
+    measured: bool
+    is_lid_on: bool
+    data: Optional[Dict[int, Dict[str, float]]]
+    configured_wavelengths: Optional[List[int]]
+    measure_mode: Optional[AbsorbanceReaderMeasureMode]
+    reference_wavelength: Optional[int]
+
+    def raise_if_lid_status_not_expected(self, lid_on_expected: bool) -> None:
+        """Raise if the lid status is not correct."""
+        match = self.is_lid_on is lid_on_expected
+        if not match:
+            raise CannotPerformModuleAction(
+                "Cannot perform lid action because the lid is already "
+                f"{'closed' if self.is_lid_on else 'open'}"
+            )

opentrons/protocol_engine/state/module_substates/flex_stacker_substate.py

@@ -0,0 +1,112 @@
+"""Flex Stacker substate."""
+
+from dataclasses import dataclass
+from typing import NewType
+from opentrons_shared_data.labware.labware_definition import LabwareDefinition
+from opentrons.protocol_engine.types.module import (
+    StackerStoredLabwareGroup,
+    StackerPoolDefinition,
+)
+from opentrons.protocol_engine.state.update_types import (
+    FlexStackerStateUpdate,
+    NO_CHANGE,
+)
+
+
+FlexStackerId = NewType("FlexStackerId", str)
+
+
+@dataclass(frozen=True)
+class FlexStackerSubState:
+    """Flex Stacker-specific state.
+
+    Provides calculations and read-only state access
+    for an individual loaded Flex Stacker Module.
+    """
+
+    module_id: FlexStackerId
+    pool_primary_definition: LabwareDefinition | None
+    pool_adapter_definition: LabwareDefinition | None
+    pool_lid_definition: LabwareDefinition | None
+    max_pool_count: int
+    pool_height: float
+    pool_overlap: float
+    contained_labware_bottom_first: list[StackerStoredLabwareGroup]
+
+    def new_from_state_change(
+        self, update: FlexStackerStateUpdate
+    ) -> "FlexStackerSubState":
+        """Return a new state with the given update applied."""
+        pool_primary_definition = self.pool_primary_definition
+        pool_adapter_definition = self.pool_adapter_definition
+        pool_lid_definition = self.pool_lid_definition
+        max_pool_count = self.max_pool_count
+        pool_overlap = self.pool_overlap
+        pool_height = self.pool_height
+        if update.pool_constraint != NO_CHANGE:
+            max_pool_count = update.pool_constraint.max_pool_count
+            pool_primary_definition = update.pool_constraint.primary_definition
+            pool_adapter_definition = update.pool_constraint.adapter_definition
+            pool_lid_definition = update.pool_constraint.lid_definition
+            pool_overlap = update.pool_constraint.pool_overlap
+            pool_height = update.pool_constraint.pool_height
+
+        contained_labware = self.contained_labware_bottom_first
+
+        if update.contained_labware_bottom_first != NO_CHANGE:
+            contained_labware = update.contained_labware_bottom_first
+
+        return FlexStackerSubState(
+            module_id=self.module_id,
+            pool_primary_definition=pool_primary_definition,
+            pool_adapter_definition=pool_adapter_definition,
+            pool_lid_definition=pool_lid_definition,
+            contained_labware_bottom_first=contained_labware,
+            max_pool_count=max_pool_count,
+            pool_overlap=pool_overlap,
+            pool_height=pool_height,
+        )
+
+    def get_pool_definition_ordered_list(self) -> list[LabwareDefinition] | None:
+        """Get the pool definitions in a list suitable for getting the height."""
+        if not self.pool_primary_definition:
+            return None
+
+        defs: list[LabwareDefinition] = []
+        if self.pool_lid_definition is not None:
+            defs.append(self.pool_lid_definition)
+        defs.append(self.pool_primary_definition)
+        if self.pool_adapter_definition is not None:
+            defs.append(self.pool_adapter_definition)
+        return defs
+
+    def get_pool_height_minus_overlap(self) -> float:
+        """Get the height used in dispense/store action."""
+        return self.pool_height - self.pool_overlap
+
+    def get_contained_labware(self) -> list[StackerStoredLabwareGroup]:
+        """Get the labware inside the hopper."""
+        return self.contained_labware_bottom_first
+
+    def get_max_pool_count(self) -> int | None:
+        """Get the maximum number of currently-configured labware.
+
+        If the stacker has not been configured, return None.
+        """
+        if not self.pool_primary_definition:
+            return None
+        return self.max_pool_count
+
+    def get_pool_overlap(self) -> float:
+        """Get the overlap of the currently-configured labware."""
+        return self.pool_overlap
+
+    def get_pool_definition(self) -> StackerPoolDefinition | None:
+        """Get the labware definitions of the stacker pool."""
+        if not self.pool_primary_definition:
+            return None
+        return StackerPoolDefinition(
+            primaryLabwareDefinition=self.pool_primary_definition,
+            adapterLabwareDefinition=self.pool_adapter_definition,
+            lidLabwareDefinition=self.pool_lid_definition,
+        )

opentrons/protocol_engine/state/module_substates/heater_shaker_module_substate.py

@@ -0,0 +1,115 @@
+"""Heater-Shaker Module sub-state."""
+
+from dataclasses import dataclass
+from typing import NewType, Optional
+
+from opentrons.hardware_control.modules import ModuleDataValidator, ModuleData
+from opentrons.protocol_engine.types import (
+    TemperatureRange,
+    SpeedRange,
+    HeaterShakerLatchStatus,
+)
+from opentrons.protocol_engine.errors import (
+    InvalidTargetTemperatureError,
+    InvalidTargetSpeedError,
+    NoTargetTemperatureSetError,
+    CannotPerformModuleAction,
+)
+
+HeaterShakerModuleId = NewType("HeaterShakerModuleId", str)
+
+
+HEATER_SHAKER_TEMPERATURE_RANGE = TemperatureRange(min=0, max=95)
+HEATER_SHAKER_SPEED_RANGE = SpeedRange(min=200, max=3000)
+
+
+@dataclass(frozen=True)
+class HeaterShakerModuleSubState:
+    """Heater-Shaker-specific state.
+
+    Provides calculations and read-only state access
+    for an individual loaded Heater-Shaker Module.
+    """
+
+    module_id: HeaterShakerModuleId
+    labware_latch_status: HeaterShakerLatchStatus
+    is_plate_shaking: bool
+    plate_target_temperature: Optional[float]
+
+    def get_plate_target_temperature(self) -> float:
+        """Get the module's target plate temperature."""
+        target = self.plate_target_temperature
+
+        if target is None:
+            raise NoTargetTemperatureSetError(
+                f"Module {self.module_id} does not have a target temperature set."
+            )
+        return target
+
+    @staticmethod
+    def validate_target_temperature(celsius: float) -> float:
+        """Verify that the target temperature being set is valid for heater-shaker."""
+        if (
+            HEATER_SHAKER_TEMPERATURE_RANGE.min
+            <= celsius
+            <= HEATER_SHAKER_TEMPERATURE_RANGE.max
+        ):
+            return celsius
+        else:
+            raise InvalidTargetTemperatureError(
+                f"Cannot set Heater-Shaker to {celsius} °C."
+                f" Valid range is {HEATER_SHAKER_TEMPERATURE_RANGE} °C."
+            )
+
+    @staticmethod
+    def validate_target_speed(rpm: float) -> int:
+        """Verify that the target speed is valid for heater-shaker & convert to int."""
+        rpm_int = int(round(rpm, 0))
+        if HEATER_SHAKER_SPEED_RANGE.min <= rpm <= HEATER_SHAKER_SPEED_RANGE.max:
+            return rpm_int
+        else:
+            raise InvalidTargetSpeedError(
+                f"Cannot set Heater-Shaker to shake at {rpm} rpm. Valid speed range is "
+                f"{HEATER_SHAKER_SPEED_RANGE} rpm."
+            )
+
+    def raise_if_labware_latch_not_closed(self) -> None:
+        """Raise an error if labware is not latched on the heater-shaker."""
+        if self.labware_latch_status == HeaterShakerLatchStatus.UNKNOWN:
+            raise CannotPerformModuleAction(
+                "Heater-Shaker cannot start or deactivate shaking if the labware latch has not been set to closed."
+            )
+        elif self.labware_latch_status == HeaterShakerLatchStatus.OPEN:
+            raise CannotPerformModuleAction(
+                "Heater-Shaker cannot start or deactivate shaking while the labware latch is open."
+            )
+
+    def raise_if_shaking(self) -> None:
+        """Raise an error if the heater-shaker is currently shaking."""
+        if self.is_plate_shaking:
+            raise CannotPerformModuleAction(
+                "Heater-Shaker cannot open its labware latch while it is shaking."
+            )
+
+    @classmethod
+    def from_live_data(
+        cls, module_id: HeaterShakerModuleId, data: ModuleData | None
+    ) -> "HeaterShakerModuleSubState":
+        """Create a HeaterShakerModuleSubState from live data."""
+        if ModuleDataValidator.is_heater_shaker_data(data):
+            return cls(
+                module_id=module_id,
+                labware_latch_status=(
+                    HeaterShakerLatchStatus.CLOSED
+                    if data["labwareLatchStatus"] == "idle_closed"
+                    else HeaterShakerLatchStatus.OPEN
+                ),
+                is_plate_shaking=data["targetSpeed"] is not None,
+                plate_target_temperature=data["targetTemp"],
+            )
+        return cls(
+            module_id=module_id,
+            labware_latch_status=HeaterShakerLatchStatus.UNKNOWN,
+            is_plate_shaking=False,
+            plate_target_temperature=None,
+        )

opentrons/protocol_engine/state/module_substates/magnetic_block_substate.py

@@ -0,0 +1,17 @@
+"""Magnetic block sub-state."""
+
+from dataclasses import dataclass
+from typing import NewType
+
+MagneticBlockId = NewType("MagneticBlockId", str)
+
+
+@dataclass(frozen=True)
+class MagneticBlockSubState:
+    """Magnetic Block specific state.
+
+    Provides a read-only state access
+    for an individual loaded Magnetic Block.
+    """
+
+    module_id: MagneticBlockId

opentrons/protocol_engine/state/module_substates/magnetic_module_substate.py

@@ -0,0 +1,65 @@
+"""Magnetic module sub-state."""
+
+from dataclasses import dataclass
+from typing import NewType
+
+from opentrons.protocol_engine.types import MagneticModuleModel, ModuleModel
+from opentrons.protocol_engine.errors import EngageHeightOutOfRangeError
+from opentrons.hardware_control.modules.magdeck import (
+    engage_height_is_in_range,
+    OFFSET_TO_LABWARE_BOTTOM as MAGNETIC_MODULE_OFFSET_TO_LABWARE_BOTTOM,
+    MAX_ENGAGE_HEIGHT as MAGNETIC_MODULE_MAX_ENGAGE_HEIGHT,
+)
+
+MagneticModuleId = NewType("MagneticModuleId", str)
+
+
+@dataclass(frozen=True)
+class MagneticModuleSubState:
+    """Magnetic Module specific state.
+
+    Provides calculations and read-only state access
+    for an individual loaded Magnetic Module.
+    """
+
+    module_id: MagneticModuleId
+    model: MagneticModuleModel
+
+    def calculate_magnet_hardware_height(self, mm_from_base: float) -> float:
+        """Convert a human-friendly magnet height to be hardware-friendly.
+
+        Args:
+            mm_from_base: The height to convert. Measured in how far the tops
+                of the magnets are above the labware base plane.
+
+        Returns:
+            The same height, with its units and origin point converted
+            so that it's suitable to pass to `MagDeck.engage()`.
+
+        Raises:
+            EngageHeightOutOfRangeError: If modules of the given model are
+                physically incapable of reaching the requested height.
+        """
+        hardware_units_from_base = (
+            mm_from_base * 2
+            if self.model == ModuleModel.MAGNETIC_MODULE_V1
+            else mm_from_base
+        )
+        home_to_base_offset = MAGNETIC_MODULE_OFFSET_TO_LABWARE_BOTTOM[self.model]
+        hardware_units_from_home = home_to_base_offset + hardware_units_from_base
+
+        if not engage_height_is_in_range(
+            model=self.model,
+            height=hardware_units_from_home,
+        ):
+            # TODO(mm, 2022-03-02): This error message probably will not match how
+            # the user specified the height. (Hardware units versus mm,
+            # home as origin versus labware base as origin.) This may be confusing
+            # depending on how it propagates up.
+            raise EngageHeightOutOfRangeError(
+                f"Invalid engage height for {self.model}:"
+                f" {hardware_units_from_home}. Must be"
+                f" 0 - {MAGNETIC_MODULE_MAX_ENGAGE_HEIGHT[self.model]}."
+            )
+
+        return hardware_units_from_home

opentrons/protocol_engine/state/module_substates/temperature_module_substate.py

@@ -0,0 +1,67 @@
+"""Temperature module sub-state."""
+
+from dataclasses import dataclass
+from typing import NewType, Optional
+
+from opentrons.hardware_control.modules import ModuleDataValidator, ModuleData
+from opentrons.protocol_engine.types import TemperatureRange
+from opentrons.protocol_engine.errors import (
+    InvalidTargetTemperatureError,
+    NoTargetTemperatureSetError,
+)
+
+TemperatureModuleId = NewType("TemperatureModuleId", str)
+
+# TODO (spp, 2022-03-22): Move these values to temperature module definition.
+TEMP_MODULE_TEMPERATURE_RANGE = TemperatureRange(min=-9, max=99)
+
+
+@dataclass(frozen=True)
+class TemperatureModuleSubState:
+    """Temperature Module specific state.
+
+    Provides calculations and read-only state access
+    for an individual loaded Temperaute Module.
+    """
+
+    module_id: TemperatureModuleId
+    plate_target_temperature: Optional[float]
+
+    @staticmethod
+    def validate_target_temperature(celsius: float) -> int:
+        """Verify target temperature is within range and of correct type."""
+        # Both Gen1 & 2 Temperature modules use 0 decimal precision.
+        celsius_int = int(round(celsius, 0))
+        if (
+            TEMP_MODULE_TEMPERATURE_RANGE.min
+            <= celsius_int
+            <= TEMP_MODULE_TEMPERATURE_RANGE.max
+        ):
+            return celsius_int
+        else:
+            raise InvalidTargetTemperatureError(
+                f"Temperature module got an invalid temperature {celsius} °C."
+                f" Valid range is {TEMP_MODULE_TEMPERATURE_RANGE}."
+            )
+
+    def get_plate_target_temperature(self) -> float:
+        """Get the module's target plate temperature."""
+        target = self.plate_target_temperature
+
+        if target is None:
+            raise NoTargetTemperatureSetError(
+                f"Module {self.module_id} does not have a target temperature set."
+            )
+        return target
+
+    @classmethod
+    def from_live_data(
+        cls, module_id: TemperatureModuleId, data: ModuleData | None
+    ) -> "TemperatureModuleSubState":
+        """Create a TemperatureModuleSubState from live data."""
+        return cls(
+            module_id=module_id,
+            plate_target_temperature=data["targetTemp"]
+            if ModuleDataValidator.is_temperature_module_data(data)
+            else None,
+        )