From 4cfb58fdf577bc909205ad5bd4aebfdb200858c3 Mon Sep 17 00:00:00 2001 From: Ed Cormany Date: Wed, 14 Feb 2024 11:14:50 -0500 Subject: [PATCH 1/2] docs(api): describe new `distribute()` volume clamping behavior (#14315) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * move and rewrite note * update versioning entry * "API version" instead of "version…of the API" Co-authored-by: Joe Wojak * revise note text * clean up dispense() docstring * get location out of volume --------- Co-authored-by: Joe Wojak --- api/docs/v2/basic_commands/liquids.rst | 10 +++++++--- api/docs/v2/versioning.rst | 5 +++++ .../opentrons/protocol_api/instrument_context.py | 15 +++++++-------- 3 files changed, 19 insertions(+), 11 deletions(-) diff --git a/api/docs/v2/basic_commands/liquids.rst b/api/docs/v2/basic_commands/liquids.rst index f5f4d670319..06f5dfd3bf8 100644 --- a/api/docs/v2/basic_commands/liquids.rst +++ b/api/docs/v2/basic_commands/liquids.rst @@ -75,6 +75,13 @@ To dispense liquid from a pipette tip, call the :py:meth:`.InstrumentContext.dis pipette.dispense(200, plate["B1"]) +.. note:: + In API version 2.16 and earlier, you could pass a ``volume`` argument to ``dispense()`` greater than what was aspirated into the pipette. In this case, the API would ignore ``volume`` and dispense the pipette's :py:obj:`~.InstrumentContext.current_volume`. The robot *would not* move the plunger lower as a result. + + In version 2.17 and later, passing such values raises an error. + + To move the plunger a small extra amount, add a :ref:`push out `. Or to move it a large amount, use :ref:`blow out `. + If the pipette doesn’t move, you can specify an additional dispense action without including a location. To demonstrate, this code snippet pauses the protocol, automatically resumes it, and dispense a second time from location B1. .. code-block:: python @@ -129,9 +136,6 @@ For example, this dispense action moves the plunger the equivalent of an additio .. versionadded:: 2.15 -.. note:: - In version 7.0.2 and earlier of the robot software, you could accomplish a similar result by dispensing a volume greater than what was aspirated into the pipette. In version 7.1.0 and later, the API will return an error. Calculate the difference between the two amounts and use that as the value of ``push_out``. - .. _new-blow-out: .. _blow-out: diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index 10cd50d7392..8b4caa34a5e 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -126,6 +126,11 @@ This table lists the correspondence between Protocol API versions and robot soft Changes in API Versions ======================= +Version 2.17 +------------ + +- :py:meth:`.dispense` now raises an error if you try to dispense more than :py:obj:`.InstrumentContext.current_volume`. + Version 2.16 ------------ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index e92c1bb6bab..b0d225ceda9 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -289,15 +289,14 @@ def dispense( # noqa: C901 See :ref:`new-dispense` for more details and examples. - :param volume: The volume to dispense, measured in µL. If unspecified, - defaults to :py:attr:`current_volume`. If only a volume is - passed, the pipette will dispense from its current position. + :param volume: The volume to dispense, measured in µL. - If ``dispense`` is called with a volume of precisely 0, its behavior - depends on the API level of the protocol. On API levels below 2.16, - it will behave the same as a volume of ``None``/unspecified: dispense - all liquid in the pipette. On API levels at or above 2.16, no liquid - will be dispensed. + - If unspecified or ``None``, dispense the :py:attr:`current_volume`. + + - If 0, the behavior of ``dispense()`` depends on the API level + of the protocol. In API version 2.16 and earlier, dispense all + liquid in the pipette (same as unspecified or ``None``). In API + version 2.17 and later, dispense no liquid. :type volume: int or float :param location: Tells the robot where to dispense liquid held in the pipette. From 18bc645c5ee2fe1a01778e9c0147b4504587ae2e Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Wed, 6 Mar 2024 15:01:10 -0500 Subject: [PATCH 2/2] version table + touch up dispense() --- api/docs/v2/versioning.rst | 2 ++ api/src/opentrons/protocol_api/instrument_context.py | 9 +++++++++ 2 files changed, 11 insertions(+) diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index 8b4caa34a5e..91d2fcfd924 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -84,6 +84,8 @@ This table lists the correspondence between Protocol API versions and robot soft +-------------+------------------------------+ | API Version | Introduced in Robot Software | +=============+==============================+ +| 2.17 | 7.2.0 | ++-------------+------------------------------+ | 2.16 | 7.1.0 | +-------------+------------------------------+ | 2.15 | 7.0.0 | diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index b0d225ceda9..3e2d6cac2a2 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -297,6 +297,12 @@ def dispense( # noqa: C901 of the protocol. In API version 2.16 and earlier, dispense all liquid in the pipette (same as unspecified or ``None``). In API version 2.17 and later, dispense no liquid. + + - If greater than :py:obj:`.current_volume`, the behavior of + ``dispense()`` depends on the API level of the protocol. In API + version 2.16 and earlier, dispense all liquid in the pipette. + In API version 2.17 and later, raise an error. + :type volume: int or float :param location: Tells the robot where to dispense liquid held in the pipette. @@ -343,6 +349,9 @@ def dispense( # noqa: C901 .. versionchanged:: 2.15 Added the ``push_out`` parameter. + + .. versionchanged:: 2.17 + Behavior of the ``volume`` parameter. """ if self.api_version < APIVersion(2, 15) and push_out: raise APIVersionError(