opentrons 8.7.0a0__py3-none-any.whl → 8.7.0a2__py3-none-any.whl

opentrons/protocol_api/core/legacy/legacy_module_core.py

@@ -263,6 +263,7 @@ class LegacyThermocyclerCore(
     def set_target_block_temperature(
         self,
         celsius: float,
+        ramp_rate: Optional[float],
         hold_time_seconds: Optional[float] = None,
         block_max_volume: Optional[float] = None,
     ) -> None:
@@ -271,6 +272,7 @@ class LegacyThermocyclerCore(
             celsius=celsius,
             hold_time_seconds=hold_time_seconds,
             volume=block_max_volume,
+            ramp_rate=ramp_rate,
         )
 
     def wait_for_block_temperature(self) -> None:

opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, List, Optional, Set, Union, cast, Tuple
+from typing import Dict, List, Optional, Set, Union, cast, Tuple, Sequence
 
 from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
 from opentrons_shared_data.labware.types import LabwareDefinition
@@ -34,6 +34,7 @@ from .legacy_instrument_core import LegacyInstrumentCore
 from .labware_offset_provider import AbstractLabwareOffsetProvider
 from .legacy_labware_core import LegacyLabwareCore
 from .load_info import LoadInfo, InstrumentLoadInfo, LabwareLoadInfo, ModuleLoadInfo
+from .tasks import LegacyTaskCore
 
 logger = logging.getLogger(__name__)
 
@@ -43,6 +44,7 @@ class LegacyProtocolCore(
         LegacyInstrumentCore,
         LegacyLabwareCore,
         legacy_module_core.LegacyModuleCore,
+        LegacyTaskCore,
     ]
 ):
     def __init__(
@@ -610,3 +612,11 @@ class LegacyProtocolCore(
     ]:
         """Get labware parent location."""
         assert False, "get_labware_location only supported on engine core"
+
+    def wait_for_tasks(self, task: Sequence[LegacyTaskCore]) -> None:
+        """Wait for list of tasks to complete before executing subsequent commands."""
+        assert False, "wait_for_tasks only supported on engine core"
+
+    def create_timer(self, seconds: float) -> LegacyTaskCore:
+        """Create a timer task that runs in the background."""
+        assert False, "create_timer only supported on engine core"

opentrons/protocol_api/core/legacy/tasks.py

@@ -0,0 +1,19 @@
+from ..tasks import AbstractTaskCore
+from datetime import datetime
+
+
+class LegacyTaskCore(AbstractTaskCore):
+    def __init__(self, created_at: datetime) -> None:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def get_created_at_timestamp(self) -> datetime:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def is_done(self) -> bool:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def is_started(self) -> bool:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def get_finished_at_timestamp(self) -> datetime | None:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")

opentrons/protocol_api/core/legacy_simulator/legacy_protocol_core.py

@@ -1,5 +1,5 @@
 import logging
-from typing import Dict, Optional
+from typing import Dict, Optional, Sequence
 
 from opentrons_shared_data.pipette.types import PipetteNameType
 from opentrons_shared_data.pipette.pipette_load_name_conversions import (
@@ -16,6 +16,7 @@ from ..legacy.legacy_module_core import LegacyModuleCore
 from ..legacy.load_info import InstrumentLoadInfo
 
 from .legacy_instrument_core import LegacyInstrumentCoreSimulator
+from .tasks import LegacyTaskCore
 
 logger = logging.getLogger(__name__)
 
@@ -23,7 +24,10 @@ logger = logging.getLogger(__name__)
 class LegacyProtocolCoreSimulator(
     LegacyProtocolCore,
     AbstractProtocol[
-        LegacyInstrumentCoreSimulator, LegacyLabwareCore, LegacyModuleCore
+        LegacyInstrumentCoreSimulator,
+        LegacyLabwareCore,
+        LegacyModuleCore,
+        LegacyTaskCore,
     ],
 ):
     _instruments: Dict[Mount, Optional[LegacyInstrumentCoreSimulator]]  # type: ignore[assignment]
@@ -83,3 +87,11 @@ class LegacyProtocolCoreSimulator(
         )
 
         return new_instr
+
+        def wait_for_tasks(self, task: Sequence[LegacyTaskCore]) -> None:
+            """Wait for list of tasks to complete before executing subsequent commands."""
+            assert False, "wait_for_tasks only supported on engine core"
+
+        def create_timer(self, seconds: float) -> LegacyTaskCore:
+            """Create a timer task that runs in the background."""
+            assert False, "create_timer only supported on engine core"

opentrons/protocol_api/core/legacy_simulator/tasks.py

@@ -0,0 +1,19 @@
+from ..tasks import AbstractTaskCore
+from datetime import datetime
+
+
+class LegacyTaskCore(AbstractTaskCore):
+    def __init__(self, created_at: datetime) -> None:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def get_created_at_timestamp(self) -> datetime:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def is_done(self) -> bool:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def is_started(self) -> bool:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")
+
+    def get_finished_at_timestamp(self) -> datetime | None:
+        raise NotImplementedError("Legacy protocols do not implement tasks.")

opentrons/protocol_api/core/module.py

@@ -161,6 +161,7 @@ class AbstractThermocyclerCore(
     def set_target_block_temperature(
         self,
         celsius: float,
+        ramp_rate: Optional[float],
         hold_time_seconds: Optional[float] = None,
         block_max_volume: Optional[float] = None,
     ) -> None:

opentrons/protocol_api/core/protocol.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import abstractmethod, ABC
-from typing import Generic, List, Optional, Union, Tuple, Dict, TYPE_CHECKING
+from typing import Generic, List, Optional, Union, Tuple, Dict, TYPE_CHECKING, Sequence
 
 from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
 from opentrons_shared_data.pipette.types import PipetteNameType
@@ -24,6 +24,7 @@ from opentrons.protocols.api_support.util import AxisMaxSpeeds
 from .instrument import InstrumentCoreType
 from .labware import LabwareCoreType, LabwareLoadParams
 from .module import ModuleCoreType
+from .tasks import TaskCoreType
 from .._liquid import Liquid, LiquidClass
 from .robot import AbstractRobot
 from .._types import OffDeckType
@@ -34,7 +35,7 @@ if TYPE_CHECKING:
 
 
 class AbstractProtocol(
-    ABC, Generic[InstrumentCoreType, LabwareCoreType, ModuleCoreType]
+    ABC, Generic[InstrumentCoreType, LabwareCoreType, ModuleCoreType, TaskCoreType]
 ):
     @property
     @abstractmethod
@@ -192,6 +193,14 @@ class AbstractProtocol(
     def delay(self, seconds: float, msg: Optional[str]) -> None:
         ...
 
+    @abstractmethod
+    def wait_for_tasks(self, task_cores: Sequence[TaskCoreType]) -> None:
+        ...
+
+    @abstractmethod
+    def create_timer(self, seconds: float) -> TaskCoreType:
+        ...
+
     @abstractmethod
     def home(self) -> None:
         ...

opentrons/protocol_api/core/tasks.py

@@ -0,0 +1,31 @@
+from abc import abstractmethod, ABC
+from datetime import datetime
+from typing import TypeVar
+
+
+class AbstractTaskCore(ABC):
+    @abstractmethod
+    def get_created_at_timestamp(self) -> datetime:
+        """Get the createdAt timestamp of the task."""
+        ...
+
+    @abstractmethod
+    def is_done(self) -> bool:
+        """Returns ``True`` if the task is done."""
+        ...
+
+    @abstractmethod
+    def is_started(self) -> bool:
+        """Returns ``True`` if the task has started."""
+        ...
+
+    @abstractmethod
+    def get_finished_at_timestamp(self) -> datetime | None:
+        """The timestamp of the when the task finished.
+
+        Returns ``None`` if the task hasn't finished yet.
+        """
+        ...
+
+
+TaskCoreType = TypeVar("TaskCoreType", bound=AbstractTaskCore)

opentrons/protocol_api/module_contexts.py

@@ -686,6 +686,7 @@ class ThermocyclerContext(ModuleContext):
             celsius=temperature,
             hold_time_seconds=seconds,
             block_max_volume=block_max_volume,
+            ramp_rate=ramp_rate,
         )
         self._core.wait_for_block_temperature()
 

opentrons/protocol_api/protocol_context.py

@@ -89,6 +89,7 @@ from .module_contexts import (
     FlexStackerContext,
     ModuleContext,
 )
+from .tasks import Task
 from ._parameters import Parameters
 
 
@@ -234,10 +235,7 @@ class ProtocolContext(CommandPublisher):
     @property
     @requires_version(2, 22)
     def robot(self) -> RobotContext:
-        """The :py:class:`.RobotContext` for the protocol.
-
-        :meta private:
-        """
+        """The :py:class:`.RobotContext` for the protocol."""
         if self._core.robot_type != "OT-3 Standard" or not self._robot:
             raise RobotTypeError("The RobotContext is only available on Flex robots.")
         return self._robot
@@ -1289,6 +1287,30 @@ class ProtocolContext(CommandPublisher):
         delay_time = seconds + minutes * 60
         self._core.delay(seconds=delay_time, msg=msg)
 
+    @publish(command=cmds.wait_for_tasks)
+    @requires_version(2, 27)
+    def wait_for_tasks(self, tasks: list[Task]) -> None:
+        """Wait for a list of tasks to complete before executing subsequent commands.
+
+        :param list Task: tasks: A list of Task objects to wait for.
+
+        Task objects can be commands that are allowed to run concurrently.
+        """
+        task_cores = [task._core for task in tasks]
+        self._core.wait_for_tasks(task_cores)
+
+    @publish(command=cmds.create_timer)
+    @requires_version(2, 27)
+    def create_timer(self, seconds: float) -> Task:
+        """Create a timer task that runs in the background.
+
+        :param float seconds: The time to delay in seconds.
+
+        This timer will continue to run until it is complete and will not block subsequent commands.
+        """
+        task_core = self._core.create_timer(seconds=seconds)
+        return Task(core=task_core, api_version=self._api_version)
+
     @requires_version(2, 0)
     def home(self) -> None:
         """Home the movement system of the robot."""

opentrons/protocol_api/robot_context.py

@@ -46,7 +46,7 @@ class RobotContext(publisher.CommandPublisher):
     Objects in this class should not be instantiated directly. Instead, instances are
     returned by :py:meth:`ProtocolContext.robot`.
 
-    .. versionadded:: 2.20
+    .. versionadded:: 2.22
 
     """
 
@@ -83,15 +83,19 @@ class RobotContext(publisher.CommandPublisher):
         speed: Optional[float] = None,
     ) -> None:
         """
-        Move a specified mount to a destination location on the deck.
+        Move a specified mount to a location on the deck.
 
         :param mount: The mount of the instrument you wish to move.
                       This can either be an instance of :py:class:`.types.Mount` or one
                       of the strings ``"left"``, ``"right"``, ``"extension"``, ``"gripper"``. Note
                       that the gripper mount can be referred to either as ``"extension"`` or ``"gripper"``.
         :type mount: types.Mount or str
-        :param Location destination:
-        :param speed:
+        :param destination: Any location on the deck, specified as:
+
+              -  a slot, like ``"A1"``
+              -  a defined location, like labware in a deck slot
+              -  an absolute location, like a point {x=10 , y=10, z=10} or a deck location and point ("A1" + point {x=10 , y=10, z=10})
+        :param speed: The absolute speed in mm/s.
         """
         mount = validation.ensure_instrument_mount(mount)
         with publisher.publish_context(
@@ -116,10 +120,9 @@ class RobotContext(publisher.CommandPublisher):
         Move a set of axes to an absolute position on the deck.
 
         :param axis_map: A dictionary mapping axes to an absolute position on the deck in mm.
-        :param critical_point: The critical point to move the axes with. It should only
-        specify the gantry axes (i.e. `x`, `y`, `z`).
-        :param float speed: The maximum speed with which you want to move all the axes
-        in the axis map.
+        :param critical_point: The critical point, or specific point on the object being moved, to move the axes with. It should only specify the gantry axes (i.e. `x`, `y`, `z`). When you specify a critical point, you're specifying the object on the gantry to be moved. If not specified, the critical point defaults to the center of the carriage attached to the gantry.
+        :param float speed: The maximum speed with which to move all axes in mm/s.
+
         """
         instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
         is_96_channel = instrument_on_left == PipetteNameType.P1000_96
@@ -154,11 +157,9 @@ class RobotContext(publisher.CommandPublisher):
         """
         Move a set of axes to a relative position on the deck.
 
-        :param axis_map: A dictionary mapping axes to relative movements in mm.
-        :type mount: types.Mount or str
+        :param axis_map: A dictionary mapping axes to relative movements from the current position in mm.
 
-        :param float speed: The maximum speed with which you want to move all the axes
-        in the axis map.
+        :param float speed: The maximum speed with which to move all axes in mm/s.
         """
         instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
         is_96_channel = instrument_on_left == PipetteNameType.P1000_96
@@ -177,7 +178,10 @@ class RobotContext(publisher.CommandPublisher):
             self._core.move_axes_relative(axis_map, speed)
 
     def close_gripper_jaw(self, force: Optional[float] = None) -> None:
-        """Command the gripper closed with some force."""
+        """Closes the Flex Gripper jaws with a specified force.
+
+        :param force: Force with which to close the gripper jaws in newtons.
+        """
         with publisher.publish_context(
             broker=self.broker,
             command=cmds.close_gripper(
@@ -187,7 +191,10 @@ class RobotContext(publisher.CommandPublisher):
             self._core.close_gripper(force)
 
     def open_gripper_jaw(self) -> None:
-        """Command the gripper open."""
+        """Opens the Flex Gripper jaws with a specified force.
+
+        :param force: Force with which to open the gripper jaws in newtons.
+        """
         with publisher.publish_context(
             broker=self.broker,
             command=cmds.open_gripper(),
@@ -200,9 +207,9 @@ class RobotContext(publisher.CommandPublisher):
         location: Union[Location, ModuleContext, DeckLocation],
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` from a location to be compatible with
+        Build an axis map from a location to provide to
         either :py:meth:`.RobotContext.move_axes_to` or :py:meth:`.RobotContext.move_axes_relative`.
-        You must provide only one of `location`, `slot`, or `module` to build
+        You must provide only one of either a `location`, `slot`, or `module` to build
         the axis map.
 
         :param mount: The mount of the instrument you wish create an axis map for.
@@ -210,7 +217,10 @@ class RobotContext(publisher.CommandPublisher):
                       of the strings ``"left"``, ``"right"``, ``"extension"``, ``"gripper"``. Note
                       that the gripper mount can be referred to either as ``"extension"`` or ``"gripper"``.
         :type mount: types.Mount or str
-        :param location: The location to format an axis map for.
+        :param location: Any location on the deck, specified as:
+
+              -  a deck location, like slot ``"A1"``.
+              -  a defined location, like a module on the deck.
         :type location: `Well`, `ModuleContext`, `DeckLocation` or `OffDeckType`
         """
         mount = validation.ensure_instrument_mount(mount)
@@ -248,7 +258,11 @@ class RobotContext(publisher.CommandPublisher):
         self, mount: Union[Mount, str], volume: float, action: PipetteActionTypes
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from volume.
+        Build an axis map to move a pipette plunger motor to complete liquid handling actions.
+
+        :mount: The left or right instrument mount the pipette is attached to.
+        :param volume: A volume to convert to an axis map for linear plunger displacement.
+        :param action: Choose to ``aspirate`` or ``dispense``.
 
         """
         pipette_name = self._core.get_pipette_type_from_engine(mount)
@@ -268,7 +282,9 @@ class RobotContext(publisher.CommandPublisher):
         self, mount: Union[Mount, str], position_name: PlungerPositionTypes
     ) -> AxisMapType:
         """
-        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from position_name.
+        Build an axis map to move a pipette plunger motor to a named position.
+
+        :param position_name: A named position to move the pipette plunger to. Choose from ``top``, ``bottom``, ``blowout``, or ``drop`` plunger positions.
 
         """
         pipette_name = self._core.get_pipette_type_from_engine(mount)
@@ -284,8 +300,9 @@ class RobotContext(publisher.CommandPublisher):
         return {pipette_axis: pipette_position}
 
     def build_axis_map(self, axis_map: StringAxisMap) -> AxisMapType:
-        """Take in a :py:class:`.types.StringAxisMap` and output a :py:class:`.types.AxisMapType`.
-        A :py:class:`.types.StringAxisMap` is allowed to contain any of the following strings:
+        """Take in a :py:class:`.types.StringAxisMap` and output an axis map.
+
+        The :py:class:`.types.StringAxisMap` is allowed to contain any of the following strings:
         ``"x"``, ``"y"``, "``z_l"``, "``z_r"``, "``z_g"``, ``"q"``.
 
         An example of a valid axis map could be:

opentrons/protocol_api/tasks.py

@@ -0,0 +1,48 @@
+"""Data for concurrent protocol tasks."""
+from typing import TYPE_CHECKING
+from datetime import datetime
+from opentrons.protocols.api_support.util import requires_version
+from opentrons.protocols.api_support.types import APIVersion
+
+if TYPE_CHECKING:
+    from .core.common import TaskCore
+
+
+class Task:
+    """A concurrent protocol task created by a protocol API function.
+
+    .. versionadded:: 2.27
+    """
+
+    def __init__(self, core: "TaskCore", api_version: APIVersion) -> None:
+        """Initialize a Task."""
+        self._core = core
+        self._api_version = api_version
+
+    @property
+    @requires_version(2, 27)
+    def created_at(self) -> datetime:
+        """The timestamp of when the task was created."""
+        return self._core.get_created_at_timestamp()
+
+    @property
+    @requires_version(2, 27)
+    def done(self) -> bool:
+        """Returns ``True`` if the task is done."""
+        return self._core.is_done()
+
+    @property
+    @requires_version(2, 27)
+    def started(self) -> bool:
+        """Returns ``True`` if the task has started."""
+        return self._core.is_started()
+        ...
+
+    @property
+    @requires_version(2, 27)
+    def finished_at(self) -> datetime | None:
+        """The timestamp of the when the task finished.
+
+        Returns ``None`` if the task hasn't finished yet.
+        """
+        return self._core.get_finished_at_timestamp()

opentrons/protocol_api/validation.py

@@ -489,6 +489,7 @@ def ensure_thermocycler_profile_steps(
         temperature = step.get("temperature")
         hold_mins = step.get("hold_time_minutes")
         hold_secs = step.get("hold_time_seconds")
+        ramp_rate = step.get("ramp_rate")
         if temperature is None:
             raise ValueError("temperature must be defined for each step in cycle")
         if hold_mins is None and hold_secs is None:
@@ -496,10 +497,14 @@ def ensure_thermocycler_profile_steps(
                 "either hold_time_minutes or hold_time_seconds must be"
                 "defined for each step in cycle"
             )
+        if ramp_rate is not None and ramp_rate <= 0:
+            raise ValueError("Ramp rate must be greater than 0.")
         validated_seconds = ensure_hold_time_seconds(hold_secs, hold_mins)
         validated_steps.append(
             ThermocyclerStep(
-                temperature=temperature, hold_time_seconds=validated_seconds
+                temperature=temperature,
+                hold_time_seconds=validated_seconds,
+                ramp_rate=ramp_rate,
             )
         )
     return validated_steps

opentrons/protocol_engine/actions/__init__.py

@@ -26,8 +26,9 @@ from .actions import (
     AddModuleAction,
     FinishErrorDetails,
     DoorChangeAction,
-    ResetTipsAction,
     SetPipetteMovementSpeedAction,
+    StartTaskAction,
+    FinishTaskAction,
 )
 from .get_state_update import get_state_updates
 
@@ -55,8 +56,9 @@ __all__ = [
     "AddAddressableAreaAction",
     "AddModuleAction",
     "DoorChangeAction",
-    "ResetTipsAction",
     "SetPipetteMovementSpeedAction",
+    "StartTaskAction",
+    "FinishTaskAction",
     # action payload values
     "PauseSource",
     "FinishErrorDetails",

opentrons/protocol_engine/actions/actions.py

@@ -3,6 +3,7 @@
 Actions can be passed to the ActionDispatcher, where they will trigger
 reactions in objects that subscribe to the pipeline, like the StateStore.
 """
+
 import dataclasses
 from datetime import datetime
 from enum import Enum
@@ -20,6 +21,7 @@ from ..commands import (
     CommandDefinedErrorData,
 )
 from ..error_recovery_policy import ErrorRecoveryPolicy, ErrorRecoveryType
+from ..errors import ErrorOccurrence
 from ..notes.notes import CommandNote
 from ..state.update_types import StateUpdate
 from ..types import (
@@ -27,6 +29,7 @@ from ..types import (
     ModuleDefinition,
     Liquid,
     DeckConfigurationType,
+    Task,
 )
 
 
@@ -60,7 +63,7 @@ class PauseAction:
 class StopAction:
     """Request engine execution to stop soon."""
 
-    from_estop: bool = False
+    from_asynchronous_error: bool = False
 
 
 @dataclasses.dataclass(frozen=True)
@@ -201,6 +204,22 @@ class FailCommandAction:
     """The command to fail, in its prior `running` state."""
 
 
+@dataclasses.dataclass(frozen=True)
+class StartTaskAction:
+    """Store new task in state."""
+
+    task: Task
+
+
+@dataclasses.dataclass(frozen=True)
+class FinishTaskAction:
+    """Mark task as finished in state."""
+
+    task_id: str
+    finished_at: datetime
+    error: ErrorOccurrence | None
+
+
 @dataclasses.dataclass(frozen=True)
 class AddLabwareOffsetAction:
     """Add a labware offset, to apply to subsequent `LoadLabwareCommand`s."""
@@ -253,13 +272,6 @@ class AddModuleAction:
     module_live_data: LiveData
 
 
-@dataclasses.dataclass(frozen=True)
-class ResetTipsAction:
-    """Reset the tip tracking state of a given tip rack."""
-
-    labware_id: str
-
-
 @dataclasses.dataclass(frozen=True)
 class SetPipetteMovementSpeedAction:
     """Set the speed of a pipette's X/Y/Z movements. Does not affect plunger speed.
@@ -296,7 +308,8 @@ Action = Union[
     SetDeckConfigurationAction,
     AddAddressableAreaAction,
     AddLiquidAction,
-    ResetTipsAction,
     SetPipetteMovementSpeedAction,
     SetErrorRecoveryPolicyAction,
+    StartTaskAction,
+    FinishTaskAction,
 ]

opentrons/protocol_engine/clients/sync_client.py

@@ -65,6 +65,12 @@ class SyncClient:
     ) -> commands.LoadLabwareResult:
         pass
 
+    @overload
+    def execute_command_without_recovery(
+        self, params: commands.CreateTimerParams
+    ) -> commands.CreateTimerResult:
+        pass
+
     @overload
     def execute_command_without_recovery(
         self, params: commands.LoadModuleParams
@@ -149,13 +155,6 @@ class SyncClient:
         """Add a liquid to the engine."""
         return self._transport.call_method("add_liquid", name=name, color=color, description=description)  # type: ignore[no-any-return]
 
-    def reset_tips(self, labware_id: str) -> None:
-        """Reset a labware's tip tracking state.."""
-        self._transport.call_method(
-            "reset_tips",
-            labware_id=labware_id,
-        )
-
     def add_labware_offset(self, request: LabwareOffsetCreate) -> None:
         """Add a labware offset."""
         self._transport.call_method("add_labware_offset", request=request)