opentrons 8.7.0a9__py3-none-any.whl → 8.8.0a8__py3-none-any.whl

opentrons/protocol_engine/state/tips.py

@@ -1,27 +1,24 @@
 """Tip state tracking."""
 
 from dataclasses import dataclass
-from enum import Enum
-from typing import Dict, Iterable, Optional, List, Union
+from typing import Dict, Iterable, Optional, List, Set
 
-from opentrons.types import NozzleMapInterface
+from opentrons.types import NozzleMapInterface, NozzleConfigurationType
 from opentrons.protocol_engine.state import update_types
+from opentrons.protocol_engine.types import TipRackWellState
 
 from ._abstract_store import HasState, HandlesActions
-from ._well_math import wells_covered_dense
-from ..actions import Action, ResetTipsAction, get_state_updates
+from ._well_math import (
+    wells_covered_dense,
+    wells_covered_by_pipette_configuration,
+    wells_covered_by_physical_pipette,
+)
+from ..actions import Action, get_state_updates
 
 from opentrons.hardware_control.nozzle_manager import NozzleMap
 
 
-class _TipRackWellState(Enum):
-    """The state of a single tip in a tip rack's well."""
-
-    CLEAN = "clean"
-    USED = "used"
-
-
-_TipRackStateByWellName = Dict[str, _TipRackWellState]
+_TipRackStateByWellName = Dict[str, TipRackWellState]
 
 
 @dataclass
@@ -49,19 +46,12 @@ class TipStore(HasState[TipState], HandlesActions):
         for state_update in get_state_updates(action):
             self._handle_state_update(state_update)
 
-        if isinstance(action, ResetTipsAction):
-            labware_id = action.labware_id
-
-            for well_name in self._state.tips_by_labware_id[labware_id].keys():
-                self._state.tips_by_labware_id[labware_id][
-                    well_name
-                ] = _TipRackWellState.CLEAN
-
     def _handle_state_update(self, state_update: update_types.StateUpdate) -> None:
-        if state_update.tips_used != update_types.NO_CHANGE:
-            self._set_used_tips(
-                labware_id=state_update.tips_used.labware_id,
-                well_names=state_update.tips_used.well_names,
+        if state_update.tips_state != update_types.NO_CHANGE:
+            self._set_tip_state(
+                labware_id=state_update.tips_state.labware_id,
+                well_names=state_update.tips_state.well_names,
+                tip_state=state_update.tips_state.tip_state,
             )
 
         if state_update.loaded_labware != update_types.NO_CHANGE:
@@ -69,7 +59,7 @@ class TipStore(HasState[TipState], HandlesActions):
             definition = state_update.loaded_labware.definition
             if definition.parameters.isTiprack:
                 self._state.tips_by_labware_id[labware_id] = {
-                    well_name: _TipRackWellState.CLEAN
+                    well_name: TipRackWellState.CLEAN
                     for column in definition.ordering
                     for well_name in column
                 }
@@ -83,7 +73,7 @@ class TipStore(HasState[TipState], HandlesActions):
                 ]
                 if definition.parameters.isTiprack:
                     self._state.tips_by_labware_id[labware_id] = {
-                        well_name: _TipRackWellState.CLEAN
+                        well_name: TipRackWellState.CLEAN
                         for column in definition.ordering
                         for well_name in column
                     }
@@ -91,10 +81,12 @@ class TipStore(HasState[TipState], HandlesActions):
                         column for column in definition.ordering
                     ]
 
-    def _set_used_tips(self, labware_id: str, well_names: Iterable[str]) -> None:
+    def _set_tip_state(
+        self, labware_id: str, well_names: Iterable[str], tip_state: TipRackWellState
+    ) -> None:
         well_states = self._state.tips_by_labware_id.get(labware_id, {})
         for well_name in well_names:
-            well_states[well_name] = _TipRackWellState.USED
+            well_states[well_name] = tip_state
 
 
 class TipView:
@@ -117,226 +109,15 @@ class TipView:
         starting_tip_name: Optional[str],
         nozzle_map: Optional[NozzleMapInterface],
     ) -> Optional[str]:
-        """Get the next available clean tip. Does not support use of a starting tip if the pipette used is in a partial configuration."""
-        wells = self._state.tips_by_labware_id.get(labware_id, {})
-        columns = self._state.columns_by_labware_id.get(labware_id, [])
+        """Gets the next available clean tip.
 
-        # TODO(sf): I'm pretty sure this can be replaced with wells_covered_96 but I'm not quite sure how
-        def _identify_tip_cluster(
-            active_columns: int,
-            active_rows: int,
-            critical_column: int,
-            critical_row: int,
-            entry_well: str,
-        ) -> Optional[List[str]]:
-            tip_cluster: list[str] = []
-            for i in range(active_columns):
-                if entry_well == "A1" or entry_well == "H1":
-                    if critical_column - i >= 0:
-                        column = columns[critical_column - i]
-                    else:
-                        return None
-                elif entry_well == "A12" or entry_well == "H12":
-                    if critical_column + i < len(columns):
-                        column = columns[critical_column + i]
-                    else:
-                        return None
-                else:
-                    raise ValueError(
-                        f"Invalid entry well {entry_well} for tip cluster identification."
-                    )
-                for j in range(active_rows):
-                    if entry_well == "A1" or entry_well == "A12":
-                        if critical_row - j >= 0:
-                            well = column[critical_row - j]
-                        else:
-                            return None
-                    elif entry_well == "H1" or entry_well == "H12":
-                        if critical_row + j < len(column):
-                            well = column[critical_row + j]
-                        else:
-                            return None
-                    tip_cluster.append(well)
-
-            if any(well not in [*wells] for well in tip_cluster):
-                return None
-
-            return tip_cluster
-
-        def _validate_tip_cluster(
-            active_columns: int, active_rows: int, tip_cluster: List[str]
-        ) -> Union[str, int, None]:
-            if not any(wells[well] == _TipRackWellState.USED for well in tip_cluster):
-                return tip_cluster[0]
-            elif all(wells[well] == _TipRackWellState.USED for well in tip_cluster):
-                return None
-            else:
-                # In the case of an 8ch pipette where a column has mixed state tips we may simply progress to the next column in our search
-                if nozzle_map is not None and nozzle_map.physical_nozzle_count == 8:
-                    return None
-
-                # In the case of a 96ch we can attempt to index in by singular rows and columns assuming that indexed direction is safe
-                # The tip cluster list is ordered: Each row from a column in order by columns
-                tip_cluster_final_column: list[str] = []
-                for i in range(active_rows):
-                    tip_cluster_final_column.append(
-                        tip_cluster[((active_columns * active_rows) - 1) - i]
-                    )
-                tip_cluster_final_row: list[str] = []
-                for i in range(active_columns):
-                    tip_cluster_final_row.append(
-                        tip_cluster[(active_rows - 1) + (i * active_rows)]
-                    )
-                if all(
-                    wells[well] == _TipRackWellState.USED
-                    for well in tip_cluster_final_column
-                ):
-                    return None
-                elif all(
-                    wells[well] == _TipRackWellState.USED
-                    for well in tip_cluster_final_row
-                ):
-                    return None
-                else:
-                    # Tiprack has no valid tip selection, cannot progress
-                    return -1
-
-        # Search through the tiprack beginning at A1
-        def _cluster_search_A1(active_columns: int, active_rows: int) -> Optional[str]:
-            critical_column = active_columns - 1
-            critical_row = active_rows - 1
-
-            while critical_column < len(columns):
-                tip_cluster = _identify_tip_cluster(
-                    active_columns, active_rows, critical_column, critical_row, "A1"
-                )
-                if tip_cluster is not None:
-                    result = _validate_tip_cluster(
-                        active_columns, active_rows, tip_cluster
-                    )
-                    if isinstance(result, str):
-                        return result
-                    elif isinstance(result, int) and result == -1:
-                        return None
-                if critical_row + 1 < len(columns[0]):
-                    critical_row = critical_row + 1
-                else:
-                    critical_column += 1
-                    critical_row = active_rows - 1
-            return None
-
-        # Search through the tiprack beginning at A12
-        def _cluster_search_A12(active_columns: int, active_rows: int) -> Optional[str]:
-            critical_column = len(columns) - active_columns
-            critical_row = active_rows - 1
-
-            while critical_column >= 0:
-                tip_cluster = _identify_tip_cluster(
-                    active_columns, active_rows, critical_column, critical_row, "A12"
-                )
-                if tip_cluster is not None:
-                    result = _validate_tip_cluster(
-                        active_columns, active_rows, tip_cluster
-                    )
-                    if isinstance(result, str):
-                        return result
-                    elif isinstance(result, int) and result == -1:
-                        return None
-                if critical_row + 1 < len(columns[0]):
-                    critical_row = critical_row + 1
-                else:
-                    critical_column -= 1
-                    critical_row = active_rows - 1
-            return None
-
-        # Search through the tiprack beginning at H1
-        def _cluster_search_H1(active_columns: int, active_rows: int) -> Optional[str]:
-            critical_column = active_columns - 1
-            critical_row = len(columns[critical_column]) - active_rows
-
-            while critical_column <= len(columns):  # change to max size of labware
-                tip_cluster = _identify_tip_cluster(
-                    active_columns, active_rows, critical_column, critical_row, "H1"
-                )
-                if tip_cluster is not None:
-                    result = _validate_tip_cluster(
-                        active_columns, active_rows, tip_cluster
-                    )
-                    if isinstance(result, str):
-                        return result
-                    elif isinstance(result, int) and result == -1:
-                        return None
-                if critical_row - 1 >= 0:
-                    critical_row = critical_row - 1
-                else:
-                    critical_column += 1
-                    if critical_column >= len(columns):
-                        return None
-                    critical_row = len(columns[critical_column]) - active_rows
-            return None
-
-        # Search through the tiprack beginning at H12
-        def _cluster_search_H12(active_columns: int, active_rows: int) -> Optional[str]:
-            critical_column = len(columns) - active_columns
-            critical_row = len(columns[critical_column]) - active_rows
-
-            while critical_column >= 0:
-                tip_cluster = _identify_tip_cluster(
-                    active_columns, active_rows, critical_column, critical_row, "H12"
-                )
-                if tip_cluster is not None:
-                    result = _validate_tip_cluster(
-                        active_columns, active_rows, tip_cluster
-                    )
-                    if isinstance(result, str):
-                        return result
-                    elif isinstance(result, int) and result == -1:
-                        return None
-                if critical_row - 1 >= 0:
-                    critical_row = critical_row - 1
-                else:
-                    critical_column -= 1
-                    if critical_column < 0:
-                        return None
-                    critical_row = len(columns[critical_column]) - active_rows
-            return None
-
-        if starting_tip_name is None and nozzle_map is not None and columns:
-            num_channels = nozzle_map.physical_nozzle_count
-            num_nozzle_cols = len(nozzle_map.columns)
-            num_nozzle_rows = len(nozzle_map.rows)
-            # Each pipette's cluster search is determined by the point of entry for a given pipette/configuration:
-            # - Single channel pipettes always search a tiprack top to bottom, left to right
-            # - Eight channel pipettes will begin at the top if the primary nozzle is H1 and at the bottom if
-            #   it is A1. The eight channel will always progress across the columns left to right.
-            # - 96 Channel pipettes will begin in the corner opposite their primary/starting nozzle (if starting nozzle = A1, enter tiprack at H12)
-            #   The 96 channel will then progress towards the opposite corner, either going up or down, left or right depending on configuration.
-
-            if num_channels == 1:
-                return _cluster_search_A1(num_nozzle_cols, num_nozzle_rows)
-            elif num_channels == 8:
-                if nozzle_map.starting_nozzle == "A1":
-                    return _cluster_search_H1(num_nozzle_cols, num_nozzle_rows)
-                elif nozzle_map.starting_nozzle == "H1":
-                    return _cluster_search_A1(num_nozzle_cols, num_nozzle_rows)
-            elif num_channels == 96:
-                if nozzle_map.starting_nozzle == "A1":
-                    return _cluster_search_H12(num_nozzle_cols, num_nozzle_rows)
-                elif nozzle_map.starting_nozzle == "A12":
-                    return _cluster_search_H1(num_nozzle_cols, num_nozzle_rows)
-                elif nozzle_map.starting_nozzle == "H1":
-                    return _cluster_search_A12(num_nozzle_cols, num_nozzle_rows)
-                elif nozzle_map.starting_nozzle == "H12":
-                    return _cluster_search_A1(num_nozzle_cols, num_nozzle_rows)
-                else:
-                    raise ValueError(
-                        f"Nozzle {nozzle_map.starting_nozzle} is an invalid starting tip for automatic tip pickup."
-                    )
-            else:
-                raise RuntimeError(
-                    "Invalid number of channels for automatic tip tracking."
-                )
+        Does not support use of a starting tip if the pipette used is in a partial configuration.
+        """
+        if starting_tip_name is None and nozzle_map is not None:
+            return self._get_next_tip_with_nozzle_map(labware_id, nozzle_map)
         else:
+            wells = self._state.tips_by_labware_id.get(labware_id, {})
+            columns = self._state.columns_by_labware_id.get(labware_id, [])
             if columns and num_tips == len(columns[0]):  # Get next tips for 8-channel
                 column_head = [column[0] for column in columns]
                 starting_column_index = 0
@@ -350,17 +131,15 @@ class TipView:
                                 starting_column_index = idx
 
                 for column in columns[starting_column_index:]:
-                    if not any(
-                        wells[well] == _TipRackWellState.USED for well in column
-                    ):
+                    if all(wells[well] == TipRackWellState.CLEAN for well in column):
                         return column[0]
 
             elif num_tips == len(wells.keys()):  # Get next tips for 96 channel
                 if starting_tip_name and starting_tip_name != columns[0][0]:
                     return None
 
-                if not any(
-                    tip_state == _TipRackWellState.USED for tip_state in wells.values()
+                if all(
+                    tip_state == TipRackWellState.CLEAN for tip_state in wells.values()
                 ):
                     return next(iter(wells))
 
@@ -369,10 +148,74 @@ class TipView:
                     wells = _drop_wells_before_starting_tip(wells, starting_tip_name)
 
                 for well_name, tip_state in wells.items():
-                    if tip_state == _TipRackWellState.CLEAN:
+                    if tip_state == TipRackWellState.CLEAN:
                         return well_name
         return None
 
+    def _get_next_tip_with_nozzle_map(
+        self,
+        labware_id: str,
+        nozzle_map: NozzleMapInterface,
+    ) -> Optional[str]:
+        """Get the next available clean tip for given nozzle configuration if one can be found."""
+        tip_well_states = self._state.tips_by_labware_id.get(labware_id, {})
+        wells_by_columns = self._state.columns_by_labware_id.get(labware_id, [])
+
+        def _validate_wells(well_list: Set[str], target_well: str) -> bool:
+            # If we are not picking up the correct number of tips it's not valid
+            if len(well_list) != nozzle_map.tip_count:
+                return False
+            # If not all the tips we'll be picking up are clean it's not valid
+            target_well_states = [tip_well_states[well_name] for well_name in well_list]
+            if not all(state == TipRackWellState.CLEAN for state in target_well_states):
+                return False
+            # Since we know a full configuration will always produce zero non-active overlapping wells
+            # we can skip the following checks if it is a full configuration.
+            if nozzle_map.configuration != NozzleConfigurationType.FULL:
+                # If we have a partial configuration we need to ensure that any wells in the way are NOT present
+                wells_covered_physically = set(
+                    wells_covered_by_physical_pipette(
+                        nozzle_map=nozzle_map,  # type: ignore[arg-type]
+                        target_well=target_well,
+                        labware_wells_by_column=wells_by_columns,
+                    )
+                )
+                wells_in_way_well_state = [
+                    tip_well_states[well_name]
+                    for well_name in wells_covered_physically.difference(well_list)
+                ]
+                # TODO(jbl 2025-08-25) this should be changed to ensure all these extra wells are EMPTY when further
+                #   tip return work occurs
+                if any(
+                    well_state == TipRackWellState.CLEAN
+                    for well_state in wells_in_way_well_state
+                ):
+                    return False
+
+            return True
+
+        # Get an ordered list of wells to most efficiently search, depending on pipette configuration
+        target_well_list = _resolve_well_order(wells_by_columns, nozzle_map)
+
+        for well in target_well_list:
+            # If the target well/tip isn't clean, skip to the next one. This will be checked
+            # again in _validate_wells, but we can short circuit the following checks if this is False
+            if tip_well_states[well] != TipRackWellState.CLEAN:
+                continue
+            # Get list of all wells (i.e. tips) that would be covered by the active nozzles
+            targeted_wells = set(
+                wells_covered_by_pipette_configuration(
+                    nozzle_map=nozzle_map,  # type: ignore[arg-type]
+                    target_well=well,
+                    labware_wells_by_column=wells_by_columns,
+                )
+            )
+            # If we are picking up the correct number of tips, return that target well
+            if _validate_wells(targeted_wells, target_well=well):
+                return well
+
+        return None
+
     def has_clean_tip(self, labware_id: str, well_name: str) -> bool:
         """Get whether a well in a labware has a clean tip.
 
@@ -387,12 +230,12 @@ class TipView:
         tip_rack = self._state.tips_by_labware_id.get(labware_id)
         well_state = tip_rack.get(well_name) if tip_rack else None
 
-        return well_state == _TipRackWellState.CLEAN
+        return well_state == TipRackWellState.CLEAN
 
-    def compute_tips_to_mark_as_used(
+    def compute_tips_to_mark_as_used_or_empty(
         self, labware_id: str, well_name: str, nozzle_map: NozzleMap
     ) -> list[str]:
-        """Compute which tips a hypothetical tip pickup should mark as "used".
+        """Compute which tips a hypothetical tip pickup/drop should mark as "used" or "empty".
 
         Params:
             labware_id: The labware ID of the tip rack.
@@ -403,7 +246,15 @@ class TipView:
             The well names of all the tips that the operation will use.
         """
         columns = self._state.columns_by_labware_id.get(labware_id, [])
-        return list(wells_covered_dense(nozzle_map, well_name, columns))
+        return list(
+            wells_covered_dense(
+                nozzle_map.columns,
+                nozzle_map.rows,
+                nozzle_map.starting_nozzle,
+                well_name,
+                columns,
+            )
+        )
 
 
 def _drop_wells_before_starting_tip(
@@ -411,10 +262,78 @@ def _drop_wells_before_starting_tip(
 ) -> _TipRackStateByWellName:
     """Drop any wells that come before the starting tip and return the remaining ones after."""
     seen_starting_well = False
-    remaining_wells: dict[str, _TipRackWellState] = {}
+    remaining_wells: dict[str, TipRackWellState] = {}
     for well_name, tip_state in wells.items():
         if well_name == starting_tip_name:
             seen_starting_well = True
         if seen_starting_well:
             remaining_wells[well_name] = tip_state
     return remaining_wells
+
+
+def _resolve_well_order(  # noqa: C901
+    well_list: List[List[str]], nozzle_map: NozzleMapInterface
+) -> List[str]:
+    """Given a list of ordered columns and pipette information, returns a flat list of wells ordered for tip pick up.
+
+    Wells can be ordered in four different ways:
+        - Top to bottom, left to right (A1, B1, ... A2, B2, ... G12, H12)
+        - Top to bottom, right to left (A12, B12, ... A11, B11, ... G1, H1)
+        - Bottom to top, left to right (H1, G1, ... H2, G2, ... B12, A12)
+        - Bottom to top, right to left (A12, B12, ... A11, B11, ... G1, H1)
+
+    - Full configurations (which will always cover a single channel) will go top to bottom, left to right.
+    - A partial 8-channel pipette configuration will always search left to right, starting at either top to bottom for
+        starting nozzle H1 or bottom to top for starting nozzle A1
+    - A partial 96-channel pipette configuration will always begin in the opposite corner of the starting nozzle
+    """
+    if nozzle_map.configuration == NozzleConfigurationType.FULL:
+        return _get_top_to_bottom_left_to_right(well_list)
+    elif nozzle_map.physical_nozzle_count == 8:
+        if nozzle_map.starting_nozzle == "A1":
+            return _get_bottom_to_top_left_to_right(well_list)
+        elif nozzle_map.starting_nozzle == "H1":
+            return _get_top_to_bottom_left_to_right(well_list)
+        else:
+            raise ValueError(
+                f"Nozzle {nozzle_map.starting_nozzle} is an invalid starting tip for"
+                " 8-channel pipette automatic tip pickup."
+            )
+    elif nozzle_map.physical_nozzle_count == 96:
+        if nozzle_map.starting_nozzle == "A1":
+            return _get_bottom_to_top_right_to_left(well_list)
+        elif nozzle_map.starting_nozzle == "A12":
+            return _get_bottom_to_top_left_to_right(well_list)
+        elif nozzle_map.starting_nozzle == "H1":
+            return _get_top_to_bottom_right_to_left(well_list)
+        elif nozzle_map.starting_nozzle == "H12":
+            return _get_top_to_bottom_left_to_right(well_list)
+        else:
+            raise ValueError(
+                f"Nozzle {nozzle_map.starting_nozzle} is an invalid starting tip for 96-channel automatic tip pickup."
+            )
+    else:
+        raise ValueError(
+            f"Automatic tip pickup does not support {nozzle_map.physical_nozzle_count}-channel pipettes"
+        )
+
+
+def _get_top_to_bottom_left_to_right(well_list: List[List[str]]) -> List[str]:
+    return [well for column in well_list for well in column]
+
+
+def _get_bottom_to_top_left_to_right(well_list: List[List[str]]) -> List[str]:
+    reverse_column_ordering = [list(reversed(column)) for column in well_list]
+    return [well for column in reverse_column_ordering for well in column]
+
+
+def _get_top_to_bottom_right_to_left(well_list: List[List[str]]) -> List[str]:
+    reverse_row_ordering = list(reversed(well_list))
+    return [well for column in reverse_row_ordering for well in column]
+
+
+def _get_bottom_to_top_right_to_left(well_list: List[List[str]]) -> List[str]:
+    reverse_row_column_ordering = [
+        list(reversed(column)) for column in reversed(well_list)
+    ]
+    return [well for column in reverse_row_column_ordering for well in column]

opentrons/protocol_engine/state/update_types.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import dataclasses
 import enum
 import typing
-from typing_extensions import Self, Optional
+from typing_extensions import Self
 from datetime import datetime
 
 from opentrons.hardware_control.nozzle_manager import NozzleMap
@@ -15,6 +15,7 @@ from opentrons.protocol_engine.types import (
     LabwareLocation,
     OnLabwareLocation,
     TipGeometry,
+    TipRackWellState,
     AspiratedFluid,
     LiquidClassRecord,
     ABSMeasureMode,
@@ -23,6 +24,7 @@ from opentrons.protocol_engine.types import (
     ModuleModel,
     ModuleDefinition,
     LabwareWellId,
+    PreconditionTypes,
 )
 from opentrons.types import MountType, DeckSlotName
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
@@ -235,8 +237,10 @@ class PipetteAspirateReadyUpdate:
 
 
 @dataclasses.dataclass
-class TipsUsedUpdate:
-    """Represents an update that marks tips in a tip rack as used."""
+class TipsStateUpdate:
+    """Represents an update that marks tips in a tip rack as the requested state."""
+
+    tip_state: TipRackWellState
 
     labware_id: str
     """The labware ID of the tip rack."""
@@ -398,6 +402,13 @@ class FilesAddedUpdate:
     file_ids: list[str]
 
 
+@dataclasses.dataclass
+class PreconditionUpdate:
+    """An update that changes command preconditions flags."""
+
+    preconditions: dict[PreconditionTypes, bool]
+
+
 @dataclasses.dataclass
 class AddressableAreaUsedUpdate:
     """An update that says an addressable area has been used."""
@@ -413,7 +424,7 @@ class LoadModuleUpdate:
     definition: ModuleDefinition
     slot_name: DeckSlotName
     requested_model: ModuleModel
-    serial_number: Optional[str]
+    serial_number: typing.Optional[str]
 
 
 @dataclasses.dataclass
@@ -452,7 +463,7 @@ class StateUpdate:
 
     labware_lid: LabwareLidUpdate | NoChangeType = NO_CHANGE
 
-    tips_used: TipsUsedUpdate | NoChangeType = NO_CHANGE
+    tips_state: TipsStateUpdate | NoChangeType = NO_CHANGE
 
     liquid_loaded: LiquidLoadedUpdate | NoChangeType = NO_CHANGE
 
@@ -474,6 +485,8 @@ class StateUpdate:
 
     ready_to_aspirate: PipetteAspirateReadyUpdate | NoChangeType = NO_CHANGE
 
+    precondition_update: PreconditionUpdate | NoChangeType = NO_CHANGE
+
     def append(self, other: Self) -> Self:
         """Apply another `StateUpdate` "on top of" this one.
 
@@ -682,7 +695,7 @@ class StateUpdate:
         definition: ModuleDefinition,
         slot_name: DeckSlotName,
         requested_model: ModuleModel,
-        serial_number: Optional[str],
+        serial_number: typing.Optional[str],
     ) -> Self:
         """Add a new module to state. See `LoadModuleUpdate`."""
         self.loaded_module = LoadModuleUpdate(
@@ -729,9 +742,13 @@ class StateUpdate:
         )
         return self
 
-    def mark_tips_as_used(self: Self, labware_id: str, well_names: list[str]) -> Self:
-        """Mark tips in a tip rack as used. See `TipsUsedUpdate`."""
-        self.tips_used = TipsUsedUpdate(labware_id=labware_id, well_names=well_names)
+    def update_tip_rack_well_state(
+        self: Self, tip_state: TipRackWellState, labware_id: str, well_names: list[str]
+    ) -> Self:
+        """Marks tips in a tip rack to provided tip state. See `TipsStateUpdate`."""
+        self.tips_state = TipsStateUpdate(
+            tip_state=tip_state, labware_id=labware_id, well_names=well_names
+        )
         return self
 
     def set_liquid_loaded(