From 45e54bd37ae5c389a5e9de5c12670972b23eaed9 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 10:26:09 -0500 Subject: [PATCH 1/9] version 2.18 --- api/src/opentrons/protocol_api/instrument_context.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 3e2d6cac2a2..394c6aa1b1a 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -327,6 +327,9 @@ def dispense( # noqa: C901 liquid aspirated into the pipette will be dispensed (the amount is accessible through :py:attr:`current_volume`). + .. versionchanged:: 2.18 + Accepts ``TrashBin`` and ``WasteChute`` values. + :param rate: How quickly a pipette dispenses liquid. The speed in µL/s is calculated as ``rate`` multiplied by :py:attr:`flow_rate.dispense `. If not specified, defaults to 1.0. See @@ -551,6 +554,9 @@ def blow_out( without first calling a method that takes a location, like :py:meth:`.aspirate` or :py:meth:`dispense`. :returns: This instance. + + .. versionchanged:: 2.18 + The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ well: Optional[labware.Well] = None move_to_location: types.Location @@ -1015,6 +1021,9 @@ def drop_tip( position. :returns: This instance. + + .. versionchanged:: 2.18 + The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ alternate_drop_location: bool = False if location is None: @@ -1445,6 +1454,9 @@ def move_to( :param publish: Whether to list this function call in the run preview. Default is ``True``. + + .. versionchanged:: 2.18 + The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ with ExitStack() as contexts: if isinstance(location, (TrashBin, WasteChute)): From 6d9c62fd821c5fdbc5aa1776d4b03cd81a51892b Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Mon, 4 Mar 2024 16:19:02 -0500 Subject: [PATCH 2/9] fix typo+environs --- api/docs/v2/robot_position.rst | 35 ++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/api/docs/v2/robot_position.rst b/api/docs/v2/robot_position.rst index a7b014b187f..65cc1b9a799 100644 --- a/api/docs/v2/robot_position.rst +++ b/api/docs/v2/robot_position.rst @@ -21,6 +21,8 @@ Top, Bottom, and Center Every well on every piece of labware has three addressable positions: top, bottom, and center. The position is determined by the labware definition and what the labware is loaded on top of. You can use these positions as-is or calculate other positions relative to them. +.. _well-top: + Top ^^^^ @@ -116,6 +118,39 @@ All positions relative to labware are adjusted automatically based on labware of You should only adjust labware offsets in your Python code if you plan to run your protocol in Jupyter Notebook or from the command line. See :ref:`using_lpc` in the Advanced Control article for information. +.. _position-relative-trash: + +Position Relative to Trash Containers +===================================== + +In API version 2.15 and earlier, trash containers are :py:class:`.Labware` objects that have a single well. Use the above techniques for labware to adjust position relative to trash containers in protocols specifying these API versions. + +Starting in API version 2.16, trash containers are :py:class:`.TrashBin` or :py:class:`.WasteChute` objects. The API calculates movement to these objects based on the horizontal *center* of the pipette, rather than its primary channel (the back channel on 8-channel pipettes, and the back-left channel on 96-channel pipettes in default configuration). This ensures that all tips attached to the pipette are placed over the trash container for blowing out, dropping tips, or other operations. + +You can adjust the position of the pipette center with the :py:meth:`.TrashBin.top` and :py:meth:`.WasteChute.top` methods. These methods allow adjustments along the x-, y-, and z-axes. In contrast, ``Well.top()``, :ref:`covered above `, only allows z-axis adjustment. With no adjustments, the "top" position is centered on the x- and y-axes and is just below the opening of the trash container. + +.. code-block:: python + + trash = protocol.load_trash_bin("A3") + + trash # pipette center just below trash top center + trash.top() # same position + trash.top(z=10) # 10 mm higher + trash.top(y=10) # 10 mm towards back, default height + +.. versionadded:: 2.16 + +Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This means that you can use their output anywhere that accepts objects of those types. + +One example is the :py:obj:`.InstrumentContext.trash_container` property. Because this property is settable, if you always want to drop tips at an offset from the default location, you can overwrite the default for a given pipette:: + + chute = protocol.load_waste_chute() + + pipette.trash_container = chute.top(z=-5) + pipette.pick_up_tip() + pipette.drop_tip() # drop in waste chute, 5 mm lower than default + + .. _protocol-api-deck-coords: Position Relative to the Deck From f36a95c6607aae6222372b217bda9cd268d24813 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 5 Mar 2024 14:46:42 -0500 Subject: [PATCH 3/9] reframe .top() return type --- api/docs/v2/robot_position.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/api/docs/v2/robot_position.rst b/api/docs/v2/robot_position.rst index 65cc1b9a799..b48137fd1ec 100644 --- a/api/docs/v2/robot_position.rst +++ b/api/docs/v2/robot_position.rst @@ -140,16 +140,8 @@ You can adjust the position of the pipette center with the :py:meth:`.TrashBin.t .. versionadded:: 2.16 -Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This means that you can use their output anywhere that accepts objects of those types. - -One example is the :py:obj:`.InstrumentContext.trash_container` property. Because this property is settable, if you always want to drop tips at an offset from the default location, you can overwrite the default for a given pipette:: - - chute = protocol.load_waste_chute() - - pipette.trash_container = chute.top(z=-5) - pipette.pick_up_tip() - pipette.drop_tip() # drop in waste chute, 5 mm lower than default - +.. note:: + Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This helps prevent performing undesired actions in trash containers. For example, you can :py:meth:`.aspirate` at a location or from a well, but not from a trash container. On the other hand, you can :py:meth:`.blow_out` at a location, well, trash bin, or waste chute. .. _protocol-api-deck-coords: From f8980c03609a174fc629cf2ff551451b94c786a9 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 5 Mar 2024 17:03:22 -0500 Subject: [PATCH 4/9] versionchanged for location params --- api/src/opentrons/protocol_api/instrument_context.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 394c6aa1b1a..3dfdad01e4d 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -306,8 +306,8 @@ def dispense( # noqa: C901 :type volume: int or float :param location: Tells the robot where to dispense liquid held in the pipette. - The location can be a :py:class:`.Well` or a - :py:class:`.Location`. + The location can be a :py:class:`.Well`, :py:class:`.Location`, + :py:class:`.TrashBin`, or :py:class:`.WasteChute`. - If the location is a ``Well``, the pipette will dispense at or above the bottom center of the well. The distance (in From e15a920dd161004e1967668559cb980f8759edf3 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 11:53:27 -0500 Subject: [PATCH 5/9] move versionchanged from methods to params --- .../protocol_api/instrument_context.py | 27 ++++++++++--------- 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 3dfdad01e4d..991a24287cd 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -546,7 +546,11 @@ def blow_out( :ref:`blow-out`. :param location: The blowout location. If no location is specified, the pipette - will blow out from its current position. + will blow out from its current position. + + .. versionchanged:: 2.18 + Accepts ``TrashBin`` and ``WasteChute`` values. + :type location: :py:class:`.Well` or :py:class:`.Location` or ``None`` :raises RuntimeError: If no location is specified and the location cache is @@ -554,9 +558,6 @@ def blow_out( without first calling a method that takes a location, like :py:meth:`.aspirate` or :py:meth:`dispense`. :returns: This instance. - - .. versionchanged:: 2.18 - The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ well: Optional[labware.Well] = None move_to_location: types.Location @@ -1009,7 +1010,11 @@ def drop_tip( ``pipette.drop_tip(location=waste_chute)``. :param location: - The location to drop the tip. + Where to drop the tip. + + .. versionchanged:: 2.16 + Accepts ``TrashBin`` and ``WasteChute`` values. + :type location: :py:class:`~.types.Location` or :py:class:`.Well` or ``None`` :param home_after: @@ -1021,9 +1026,6 @@ def drop_tip( position. :returns: This instance. - - .. versionchanged:: 2.18 - The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ alternate_drop_location: bool = False if location is None: @@ -1436,7 +1438,11 @@ def move_to( See :ref:`move-to` for examples. - :param location: The location to move to. + :param location: Where to move to. + + .. versionchanged:: 2.18 + Accepts ``TrashBin`` and ``WasteChute`` values. + :type location: :py:class:`~.types.Location` :param force_direct: If ``True``, move directly to the destination without arc motion. @@ -1454,9 +1460,6 @@ def move_to( :param publish: Whether to list this function call in the run preview. Default is ``True``. - - .. versionchanged:: 2.18 - The ``location`` parameter accepts ``TrashBin`` and ``WasteChute`` values. """ with ExitStack() as contexts: if isinstance(location, (TrashBin, WasteChute)): From 23086414d9613dd5b0f627917bec52cf5aff4124 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 12:19:07 -0500 Subject: [PATCH 6/9] expand dispense location docstring --- .../protocol_api/instrument_context.py | 20 +++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 991a24287cd..cc394fda254 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -306,21 +306,25 @@ def dispense( # noqa: C901 :type volume: int or float :param location: Tells the robot where to dispense liquid held in the pipette. - The location can be a :py:class:`.Well`, :py:class:`.Location`, - :py:class:`.TrashBin`, or :py:class:`.WasteChute`. + The location can be a :py:class:`.Well`, :py:class:`.Location`, + :py:class:`.TrashBin`, or :py:class:`.WasteChute`. - - If the location is a ``Well``, the pipette will dispense + - If a ``Well``, the pipette will dispense at or above the bottom center of the well. The distance (in mm) from the well bottom is specified by :py:obj:`well_bottom_clearance.dispense `. - - If the location is a ``Location`` (e.g., the result of - :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the robot - will dispense into that specified position. + - If a ``Location`` (e.g., the result of + :py:meth:`.Well.top` or :py:meth:`.Well.bottom`), the pipette + will dispense at that specified position. - - If the ``location`` is unspecified, the robot will - dispense into its current position. + - If a trash container, the pipette will dispense at a location + relative to its center and the trash container's top center. + See :ref:`position-relative-trash` for details. + + - If unspecified, the pipette will + dispense at its current position. If only a ``location`` is passed (e.g., ``pipette.dispense(location=plate['A1'])``), all of the From 8c4e5803b58085fe9822cd882010ad924728fe50 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 12:21:47 -0500 Subject: [PATCH 7/9] 2.18 in robot_position --- api/docs/v2/robot_position.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/api/docs/v2/robot_position.rst b/api/docs/v2/robot_position.rst index b48137fd1ec..2036d00ea89 100644 --- a/api/docs/v2/robot_position.rst +++ b/api/docs/v2/robot_position.rst @@ -138,7 +138,7 @@ You can adjust the position of the pipette center with the :py:meth:`.TrashBin.t trash.top(z=10) # 10 mm higher trash.top(y=10) # 10 mm towards back, default height -.. versionadded:: 2.16 +.. versionadded:: 2.18 .. note:: Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This helps prevent performing undesired actions in trash containers. For example, you can :py:meth:`.aspirate` at a location or from a well, but not from a trash container. On the other hand, you can :py:meth:`.blow_out` at a location, well, trash bin, or waste chute. From 1bc1e2e5bc653d4ea2b9b940bde797c7e9ded97c Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 17:13:53 -0500 Subject: [PATCH 8/9] =?UTF-8?q?reorder=20=C2=A7=20on=20position,=20remove?= =?UTF-8?q?=20outdated=20note=20on=20deck=20slots?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api/docs/v2/deck_slots.rst | 3 --- api/docs/v2/robot_position.rst | 8 ++++---- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/api/docs/v2/deck_slots.rst b/api/docs/v2/deck_slots.rst index 2c38e70755f..6441ab0d562 100644 --- a/api/docs/v2/deck_slots.rst +++ b/api/docs/v2/deck_slots.rst @@ -149,9 +149,6 @@ Starting in API version 2.16, you must load trash bin fixtures in your protocol .. versionadded:: 2.16 -.. note:: - The :py:class:`.TrashBin` class doesn't have any callable methods, so you don't have to save the result of ``load_trash_bin()`` to a variable, especially if your protocol only loads a single trash container. Being able to reference the trash bin by name is useful when dealing with multiple trash containers. - Call ``load_trash_bin()`` multiple times to add more than one bin. See :ref:`pipette-trash-containers` for more information on using pipettes with multiple trash bins. .. _configure-waste-chute: diff --git a/api/docs/v2/robot_position.rst b/api/docs/v2/robot_position.rst index 2036d00ea89..ab20d1c2fc7 100644 --- a/api/docs/v2/robot_position.rst +++ b/api/docs/v2/robot_position.rst @@ -123,9 +123,10 @@ You should only adjust labware offsets in your Python code if you plan to run yo Position Relative to Trash Containers ===================================== -In API version 2.15 and earlier, trash containers are :py:class:`.Labware` objects that have a single well. Use the above techniques for labware to adjust position relative to trash containers in protocols specifying these API versions. +Movement to :py:class:`.TrashBin` or :py:class:`.WasteChute` objects is based on the horizontal *center* of the pipette. This is different than movement to labware, which is based on the primary channel (the back channel on 8-channel pipettes, and the back-left channel on 96-channel pipettes in default configuration). Using the center of the pipette ensures that all attached tips are over the trash container for blowing out, dropping tips, or other disposal operations. -Starting in API version 2.16, trash containers are :py:class:`.TrashBin` or :py:class:`.WasteChute` objects. The API calculates movement to these objects based on the horizontal *center* of the pipette, rather than its primary channel (the back channel on 8-channel pipettes, and the back-left channel on 96-channel pipettes in default configuration). This ensures that all tips attached to the pipette are placed over the trash container for blowing out, dropping tips, or other operations. +.. note:: + In API version 2.15 and earlier, trash containers are :py:class:`.Labware` objects that have a single well. See :py:obj:`.fixed_trash` and :ref:`position-relative-labware` above. You can adjust the position of the pipette center with the :py:meth:`.TrashBin.top` and :py:meth:`.WasteChute.top` methods. These methods allow adjustments along the x-, y-, and z-axes. In contrast, ``Well.top()``, :ref:`covered above `, only allows z-axis adjustment. With no adjustments, the "top" position is centered on the x- and y-axes and is just below the opening of the trash container. @@ -140,8 +141,7 @@ You can adjust the position of the pipette center with the :py:meth:`.TrashBin.t .. versionadded:: 2.18 -.. note:: - Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This helps prevent performing undesired actions in trash containers. For example, you can :py:meth:`.aspirate` at a location or from a well, but not from a trash container. On the other hand, you can :py:meth:`.blow_out` at a location, well, trash bin, or waste chute. +Another difference between the trash container ``top()`` methods and ``Well.top()`` is that they return an object of the same type, not a :py:class:`.Location`. This helps prevent performing undesired actions in trash containers. For example, you can :py:meth:`.aspirate` at a location or from a well, but not from a trash container. On the other hand, you can :py:meth:`.blow_out` at a location, well, trash bin, or waste chute. .. _protocol-api-deck-coords: From 6590f443fd3affb70e92c35c7f7b54fcc19937ce Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Thu, 7 Mar 2024 17:21:16 -0500 Subject: [PATCH 9/9] oops, 2.16 in instrument_context --- api/src/opentrons/protocol_api/instrument_context.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index cc394fda254..b5a0531495e 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -331,7 +331,7 @@ def dispense( # noqa: C901 liquid aspirated into the pipette will be dispensed (the amount is accessible through :py:attr:`current_volume`). - .. versionchanged:: 2.18 + .. versionchanged:: 2.16 Accepts ``TrashBin`` and ``WasteChute`` values. :param rate: How quickly a pipette dispenses liquid. The speed in µL/s is @@ -552,7 +552,7 @@ def blow_out( :param location: The blowout location. If no location is specified, the pipette will blow out from its current position. - .. versionchanged:: 2.18 + .. versionchanged:: 2.16 Accepts ``TrashBin`` and ``WasteChute`` values. :type location: :py:class:`.Well` or :py:class:`.Location` or ``None`` @@ -1444,7 +1444,7 @@ def move_to( :param location: Where to move to. - .. versionchanged:: 2.18 + .. versionchanged:: 2.16 Accepts ``TrashBin`` and ``WasteChute`` values. :type location: :py:class:`~.types.Location`