opentrons 8.3.0a0__py2.py3-none-any.whl → 8.3.0a2__py2.py3-none-any.whl

opentrons/protocol_api/module_contexts.py

@@ -125,6 +125,7 @@ class ModuleContext(CommandPublisher):
         namespace: Optional[str] = None,
         version: Optional[int] = None,
         adapter: Optional[str] = None,
+        lid: Optional[str] = None,
     ) -> Labware:
         """Load a labware onto the module using its load parameters.
 
@@ -180,6 +181,19 @@ class ModuleContext(CommandPublisher):
             version=version,
             location=load_location,
         )
+        if lid is not None:
+            if self._api_version < validation.LID_STACK_VERSION_GATE:
+                raise APIVersionError(
+                    api_element="Loading a lid on a Labware",
+                    until_version="2.23",
+                    current_version=f"{self._api_version}",
+                )
+            self._protocol_core.load_lid(
+                load_name=lid,
+                location=labware_core,
+                namespace=namespace,
+                version=version,
+            )
 
         if isinstance(self._core, LegacyModuleCore):
             labware = self._core.add_labware_core(cast(LegacyLabwareCore, labware_core))
@@ -608,7 +622,7 @@ class ThermocyclerContext(ModuleContext):
         .. note::
 
             The Thermocycler will proceed to the next command immediately after
-            ``temperature`` has been reached.
+            ``temperature`` is reached.
 
         """
         self._core.set_target_lid_temperature(celsius=temperature)
@@ -625,28 +639,18 @@ class ThermocyclerContext(ModuleContext):
         """Execute a Thermocycler profile, defined as a cycle of
         ``steps``, for a given number of ``repetitions``.
 
-        :param steps: List of unique steps that make up a single cycle.
-                      Each list item should be a dictionary that maps to
-                      the parameters of the :py:meth:`set_block_temperature`
-                      method with a ``temperature`` key, and either or both of
+        :param steps: List of steps that make up a single cycle.
+                      Each list item should be a dictionary that maps to the parameters
+                      of the :py:meth:`set_block_temperature` method. The dictionary's
+                      keys must be ``temperature`` and one or both of
                       ``hold_time_seconds`` and ``hold_time_minutes``.
         :param repetitions: The number of times to repeat the cycled steps.
         :param block_max_volume: The greatest volume of liquid contained in any
                                  individual well of the loaded labware, in µL.
                                  If not specified, the default is 25 µL.
 
-        .. note::
-
-            Unlike with :py:meth:`set_block_temperature`, either or both of
-            ``hold_time_minutes`` and ``hold_time_seconds`` must be defined
-            and for each step.
-
-        .. note::
-
-            Before API Version 2.21, Thermocycler profiles run with this command
-            would be listed in the app as having a number of repetitions equal to
-            their step count. At or above API Version 2.21, the structure of the
-            Thermocycler cycles is preserved.
+        .. versionchanged:: 2.21
+            Fixed run log listing number of steps instead of number of repetitions.
 
         """
         repetitions = validation.ensure_thermocycler_repetition_count(repetitions)

opentrons/protocol_api/protocol_context.py

@@ -186,7 +186,14 @@ class ProtocolContext(CommandPublisher):
         self._commands: List[str] = []
         self._params: Parameters = Parameters()
         self._unsubscribe_commands: Optional[Callable[[], None]] = None
-        self._robot = RobotContext(self._core)
+        try:
+            self._robot: Optional[RobotContext] = RobotContext(
+                core=self._core.load_robot(),
+                protocol_core=self._core,
+                api_version=self._api_version,
+            )
+        except APIVersionError:
+            self._robot = None
         self.clear_commands()
 
     @property
@@ -212,12 +219,14 @@ class ProtocolContext(CommandPublisher):
         return self._api_version
 
     @property
-    @requires_version(2, 21)
+    @requires_version(2, 22)
     def robot(self) -> RobotContext:
         """The :py:class:`.RobotContext` for the protocol.
 
         :meta private:
         """
+        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
 
     @property
@@ -229,7 +238,9 @@ class ProtocolContext(CommandPublisher):
             "This function will be deprecated in later versions."
             "Please use with caution."
         )
-        return self._robot.hardware
+        if self._robot:
+            return self._robot.hardware
+        return HardwareManager(hardware=self._core.get_hardware())
 
     @property
     @requires_version(2, 0)
@@ -388,6 +399,7 @@ class ProtocolContext(CommandPublisher):
         namespace: Optional[str] = None,
         version: Optional[int] = None,
         adapter: Optional[str] = None,
+        lid: Optional[str] = None,
     ) -> Labware:
         """Load a labware onto a location.
 
@@ -432,6 +444,10 @@ class ProtocolContext(CommandPublisher):
             values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
             adapter will use the same namespace as the labware, and the API will
             choose the adapter's version automatically.
+        :param lid: A lid to load the on top of the main labware. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_lid_stack`. The
+            lid will use the same namespace as the labware, and the API will
+            choose the lid's version automatically.
 
                         .. versionadded:: 2.15
         """
@@ -472,6 +488,20 @@ class ProtocolContext(CommandPublisher):
             version=version,
         )
 
+        if lid is not None:
+            if self._api_version < validation.LID_STACK_VERSION_GATE:
+                raise APIVersionError(
+                    api_element="Loading a Lid on a Labware",
+                    until_version="2.23",
+                    current_version=f"{self._api_version}",
+                )
+            self._core.load_lid(
+                load_name=lid,
+                location=labware_core,
+                namespace=namespace,
+                version=version,
+            )
+
         labware = Labware(
             core=labware_core,
             api_version=self._api_version,
@@ -956,7 +986,10 @@ class ProtocolContext(CommandPublisher):
             mount, checked_instrument_name
         )
 
-        is_96_channel = checked_instrument_name == PipetteNameType.P1000_96
+        is_96_channel = checked_instrument_name in [
+            PipetteNameType.P1000_96,
+            PipetteNameType.P200_96,
+        ]
 
         tip_racks = tip_racks or []
 
@@ -1320,6 +1353,94 @@ class ProtocolContext(CommandPublisher):
         """Returns ``True`` if the front door of the robot is closed."""
         return self._core.door_closed()
 
+    @requires_version(2, 23)
+    def load_lid_stack(
+        self,
+        load_name: str,
+        location: Union[DeckLocation, Labware],
+        quantity: int,
+        adapter: Optional[str] = None,
+        namespace: Optional[str] = None,
+        version: Optional[int] = None,
+    ) -> Labware:
+        """
+        Load a stack of Lids onto a valid Deck Location or Adapter.
+
+        :param str load_name: A string to use for looking up a lid definition.
+            You can find the ``load_name`` for any standard lid on the Opentrons
+            `Labware Library <https://labware.opentrons.com>`_.
+        :param location: Either a :ref:`deck slot <deck-slots>`,
+            like ``1``, ``"1"``, or ``"D1"``, or the a valid Opentrons Adapter.
+        :param int quantity: The quantity of lids to be loaded in the stack.
+        :param adapter: An adapter to load the lid stack on top of. Accepts the same
+            values as the ``load_name`` parameter of :py:meth:`.load_adapter`. The
+            adapter will use the same namespace as the lid labware, and the API will
+            choose the adapter's version automatically.
+        :param str namespace: The namespace that the lid labware definition belongs to.
+            If unspecified, the API will automatically search two namespaces:
+
+              - ``"opentrons"``, to load standard Opentrons labware definitions.
+              - ``"custom_beta"``, to load custom labware definitions created with the
+                `Custom Labware Creator <https://labware.opentrons.com/create>`__.
+
+            You might need to specify an explicit ``namespace`` if you have a custom
+            definition whose ``load_name`` is the same as an Opentrons-verified
+            definition, and you want to explicitly choose one or the other.
+
+        :param version: The version of the labware definition. You should normally
+            leave this unspecified to let ``load_lid_stack()`` choose a version
+            automatically.
+
+        :return:  The initialized and loaded labware object representing the Lid Stack.
+        """
+        if self._api_version < validation.LID_STACK_VERSION_GATE:
+            raise APIVersionError(
+                api_element="Loading a Lid Stack",
+                until_version="2.23",
+                current_version=f"{self._api_version}",
+            )
+
+        load_location: Union[DeckSlotName, StagingSlotName, LabwareCore]
+        if isinstance(location, Labware):
+            load_location = location._core
+        else:
+            load_location = validation.ensure_and_convert_deck_slot(
+                location, self._api_version, self._core.robot_type
+            )
+
+        if adapter is not None:
+            if isinstance(load_location, DeckSlotName) or isinstance(
+                load_location, StagingSlotName
+            ):
+                loaded_adapter = self.load_adapter(
+                    load_name=adapter,
+                    location=load_location.value,
+                    namespace=namespace,
+                )
+                load_location = loaded_adapter._core
+            else:
+                raise ValueError(
+                    "Location cannot be a Labware or Adapter when the 'adapter' field is not None."
+                )
+
+        load_name = validation.ensure_lowercase_name(load_name)
+
+        result = self._core.load_lid_stack(
+            load_name=load_name,
+            location=load_location,
+            quantity=quantity,
+            namespace=namespace,
+            version=version,
+        )
+
+        labware = Labware(
+            core=result,
+            api_version=self._api_version,
+            protocol_core=self._core,
+            core_map=self._core_map,
+        )
+        return labware
+
 
 def _create_module_context(
     module_core: Union[ModuleCore, NonConnectedModuleCore],

opentrons/protocol_api/robot_context.py

@@ -1,11 +1,25 @@
-from typing import NamedTuple, Union, Dict, Optional
+from typing import NamedTuple, Union, Optional
 
-from opentrons.types import Mount, DeckLocation, Point
+from opentrons.types import (
+    Mount,
+    DeckLocation,
+    Location,
+    Point,
+    AxisMapType,
+    AxisType,
+    StringAxisMap,
+)
 from opentrons.legacy_commands import publisher
-from opentrons.hardware_control import SyncHardwareAPI, types as hw_types
+from opentrons.hardware_control import SyncHardwareAPI
+from opentrons.protocols.api_support.util import requires_version
+from opentrons.protocols.api_support.types import APIVersion
+from opentrons_shared_data.pipette.types import PipetteNameType
 
-from ._types import OffDeckType
-from .core.common import ProtocolCore
+from . import validation
+from .core.common import ProtocolCore, RobotCore
+from .module_contexts import ModuleContext
+from .labware import Labware
+from ._types import PipetteActionTypes, PlungerPositionTypes
 
 
 class HardwareManager(NamedTuple):
@@ -34,56 +48,214 @@ class RobotContext(publisher.CommandPublisher):
 
     """
 
-    def __init__(self, core: ProtocolCore) -> None:
-        self._hardware = HardwareManager(hardware=core.get_hardware())
+    def __init__(
+        self, core: RobotCore, protocol_core: ProtocolCore, api_version: APIVersion
+    ) -> None:
+        self._hardware = HardwareManager(hardware=protocol_core.get_hardware())
+        self._core = core
+        self._protocol_core = protocol_core
+        self._api_version = api_version
+
+    @property
+    @requires_version(2, 22)
+    def api_version(self) -> APIVersion:
+        return self._api_version
 
     @property
     def hardware(self) -> HardwareManager:
+        # TODO this hardware attribute should be deprecated
+        # in version 3.0+ as we will only support exposed robot
+        # context commands.
         return self._hardware
 
+    @requires_version(2, 22)
     def move_to(
         self,
         mount: Union[Mount, str],
-        destination: Point,
-        velocity: float,
+        destination: Location,
+        speed: Optional[float] = None,
     ) -> None:
-        raise NotImplementedError()
+        """
+        Move a specified mount to a destination 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:
+        """
+        mount = validation.ensure_instrument_mount(mount)
+        self._core.move_to(mount, destination.point, speed)
 
+    @requires_version(2, 22)
     def move_axes_to(
         self,
-        abs_axis_map: Dict[hw_types.Axis, hw_types.AxisMapValue],
-        velocity: float,
-        critical_point: Optional[hw_types.CriticalPoint],
+        axis_map: Union[AxisMapType, StringAxisMap],
+        critical_point: Optional[Union[AxisMapType, StringAxisMap]] = None,
+        speed: Optional[float] = None,
     ) -> None:
-        raise NotImplementedError()
+        """
+        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.
+        """
+        instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
+        is_96_channel = instrument_on_left == PipetteNameType.P1000_96
+        axis_map = validation.ensure_axis_map_type(
+            axis_map, self._protocol_core.robot_type, is_96_channel
+        )
+        if critical_point:
+            critical_point = validation.ensure_axis_map_type(
+                critical_point, self._protocol_core.robot_type, is_96_channel
+            )
+            validation.ensure_only_gantry_axis_map_type(
+                critical_point, self._protocol_core.robot_type
+            )
+        else:
+            critical_point = None
+        self._core.move_axes_to(axis_map, critical_point, speed)
+
+    @requires_version(2, 22)
     def move_axes_relative(
-        self, rel_axis_map: Dict[hw_types.Axis, hw_types.AxisMapValue], velocity: float
+        self,
+        axis_map: Union[AxisMapType, StringAxisMap],
+        speed: Optional[float] = None,
     ) -> None:
-        raise NotImplementedError()
+        """
+        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
 
-    def close_gripper_jaw(self, force: float) -> None:
-        raise NotImplementedError()
+        :param float speed: The maximum speed with which you want to move all the axes
+        in the axis map.
+        """
+        instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
+        is_96_channel = instrument_on_left == PipetteNameType.P1000_96
+
+        axis_map = validation.ensure_axis_map_type(
+            axis_map, self._protocol_core.robot_type, is_96_channel
+        )
+        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."""
+        self._core.close_gripper(force)
 
     def open_gripper_jaw(self) -> None:
-        raise NotImplementedError()
+        """Command the gripper open."""
+        self._core.release_grip()
 
     def axis_coordinates_for(
-        self, mount: Union[Mount, str], location: Union[DeckLocation, OffDeckType]
-    ) -> None:
-        raise NotImplementedError()
+        self,
+        mount: Union[Mount, str],
+        location: Union[Location, ModuleContext, DeckLocation],
+    ) -> AxisMapType:
+        """
+        Build a :py:class:`.types.AxisMapType` from a location to be compatible with
+        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
+        the axis map.
+
+        :param mount: The mount of the instrument you wish create an axis map for.
+                      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: The location to format an axis map for.
+        :type location: `Well`, `ModuleContext`, `DeckLocation` or `OffDeckType`
+        """
+        mount = validation.ensure_instrument_mount(mount)
+
+        mount_axis = AxisType.axis_for_mount(mount)
+        if location:
+            loc: Union[Point, Labware, None]
+            if isinstance(location, ModuleContext):
+                loc = location.labware
+                if not loc:
+                    raise ValueError(f"There must be a labware on {location}")
+                top_of_labware = loc.wells()[0].top()
+                loc = top_of_labware.point
+                return {mount_axis: loc.z, AxisType.X: loc.x, AxisType.Y: loc.y}
+            elif location is DeckLocation and not isinstance(location, Location):
+                slot_name = validation.ensure_and_convert_deck_slot(
+                    location,
+                    api_version=self._api_version,
+                    robot_type=self._protocol_core.robot_type,
+                )
+                loc = self._protocol_core.get_slot_center(slot_name)
+                return {mount_axis: loc.z, AxisType.X: loc.x, AxisType.Y: loc.y}
+            elif isinstance(location, Location):
+                assert isinstance(location, Location)
+                loc = location.point
+                return {mount_axis: loc.z, AxisType.X: loc.x, AxisType.Y: loc.y}
+            else:
+                raise ValueError(
+                    "Location parameter must be a Module, Deck Location, or Location type."
+                )
+        else:
+            raise TypeError("You must specify a location to move to.")
 
     def plunger_coordinates_for_volume(
-        self, mount: Union[Mount, str], volume: float
-    ) -> None:
-        raise NotImplementedError()
+        self, mount: Union[Mount, str], volume: float, action: PipetteActionTypes
+    ) -> AxisMapType:
+        """
+        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from volume.
+
+        """
+        pipette_name = self._core.get_pipette_type_from_engine(mount)
+        if not pipette_name:
+            raise ValueError(
+                f"Expected a pipette to be attached to provided mount {mount}"
+            )
+        mount = validation.ensure_mount_for_pipette(mount, pipette_name)
+        pipette_axis = AxisType.plunger_axis_for_mount(mount)
+
+        pipette_position = self._core.get_plunger_position_from_volume(
+            mount, volume, action, self._protocol_core.robot_type
+        )
+        return {pipette_axis: pipette_position}
 
     def plunger_coordinates_for_named_position(
-        self, mount: Union[Mount, str], position_name: str
-    ) -> None:
-        raise NotImplementedError()
+        self, mount: Union[Mount, str], position_name: PlungerPositionTypes
+    ) -> AxisMapType:
+        """
+        Build a :py:class:`.types.AxisMapType` for a pipette plunger motor from position_name.
 
-    def build_axis_map(
-        self, axis_map: Dict[hw_types.Axis, hw_types.AxisMapValue]
-    ) -> None:
-        raise NotImplementedError()
+        """
+        pipette_name = self._core.get_pipette_type_from_engine(mount)
+        if not pipette_name:
+            raise ValueError(
+                f"Expected a pipette to be attached to provided mount {mount}"
+            )
+        mount = validation.ensure_mount_for_pipette(mount, pipette_name)
+        pipette_axis = AxisType.plunger_axis_for_mount(mount)
+        pipette_position = self._core.get_plunger_position_from_name(
+            mount, position_name
+        )
+        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:
+        ``"x"``, ``"y"``, "``z_l"``, "``z_r"``, "``z_g"``, ``"q"``.
+
+        An example of a valid axis map could be:
+
+        {"x": 1, "y": 2} or {"Z_L": 100}
+
+        Note that capitalization does not matter.
+
+        """
+        instrument_on_left = self._core.get_pipette_type_from_engine(Mount.LEFT)
+        is_96_channel = instrument_on_left == PipetteNameType.P1000_96
+
+        return validation.ensure_axis_map_type(
+            axis_map, self._protocol_core.robot_type, is_96_channel
+        )