From 1a42392cfc0dd4d4a9ff8e3a87a32f388e8ae233 Mon Sep 17 00:00:00 2001 From: Ed Cormany Date: Thu, 15 Aug 2024 22:30:58 -0400 Subject: [PATCH] docs(api): additional partial tip pickup layouts in 2.20 (#15778) # Overview Document the new `ROW`, `SINGLE`, and `PARTIAL_COLUMN` configurations for partial tip pickup. # Test Plan - [Sandbox](http://sandbox.docs.opentrons.com/docs-more-partial-pickup/v2/pipettes/partial_tip_pickup.html) - Code snippets passed simulation. # Changelog - Added three new sections to the Partial Tip Pickup page, one for each layout. - Added new layouts to Versioning page. - Various consistency edits throughout the docs. # Review requests - Double check code (eye test and simulate). - Keep an eye out for any other inconsistencies / dependencies between Partial Tip Pickup and other pages. - Confirm that the explanations make sense and there are no pitfalls for API users. # Risk assessment v low --- api/docs/v2/conf.py | 2 +- api/docs/v2/new_pipette.rst | 6 +- api/docs/v2/pipettes/characteristics.rst | 2 +- api/docs/v2/pipettes/partial_tip_pickup.rst | 285 ++++++++++++++++-- api/docs/v2/versioning.rst | 5 +- .../protocol_api/instrument_context.py | 24 +- 6 files changed, 275 insertions(+), 49 deletions(-) diff --git a/api/docs/v2/conf.py b/api/docs/v2/conf.py index 1913abbfe1a..7f791b17d35 100644 --- a/api/docs/v2/conf.py +++ b/api/docs/v2/conf.py @@ -99,7 +99,7 @@ # use rst_prolog to hold the subsitution # update the apiLevel value whenever a new minor version is released rst_prolog = f""" -.. |apiLevel| replace:: 2.19 +.. |apiLevel| replace:: 2.20 .. |release| replace:: {release} """ diff --git a/api/docs/v2/new_pipette.rst b/api/docs/v2/new_pipette.rst index dfeee1ed169..840e962aafc 100644 --- a/api/docs/v2/new_pipette.rst +++ b/api/docs/v2/new_pipette.rst @@ -18,11 +18,7 @@ Pages in this section of the documentation cover: - :ref:`Loading pipettes ` into your protocol. - :ref:`Pipette characteristics `, such as how fast they can move liquid and how they move around the deck. - - The :ref:`partial tip pickup ` configuration for the Flex 96-Channel Pipette, which uses only 8 channels for pipetting. Full and partial tip pickup can be combined in a single protocol. + - :ref:`Partial tip pickup ` configurations for multi-channel pipettes. Full and partial tip pickup configurations can be combined in a single protocol. - The :ref:`volume modes ` of Flex 50 µL pipettes, which must operate in low-volume mode to accurately dispense very small volumes of liquid. For information about liquid handling, see :ref:`v2-atomic-commands` and :ref:`v2-complex-commands`. - - - - diff --git a/api/docs/v2/pipettes/characteristics.rst b/api/docs/v2/pipettes/characteristics.rst index a91f58d55e2..8aaf8751dd0 100644 --- a/api/docs/v2/pipettes/characteristics.rst +++ b/api/docs/v2/pipettes/characteristics.rst @@ -21,7 +21,7 @@ Multi-Channel Movement All :ref:`building block ` and :ref:`complex commands ` work with single- and multi-channel pipettes. -To keep the protocol API consistent when using single- and multi-channel pipettes, commands treat the back left channel of a multi-channel pipette as its *primary channel*. Location arguments of pipetting commands use the primary channel. The :py:meth:`.InstrumentContext.configure_nozzle_layout` method can change the pipette's primary channel, using its ``start`` parameter. See :ref:`partial-tip-pickup` for more information. +To keep the protocol API consistent when using single- and multi-channel pipettes, location arguments of pipetting commands use the pipette's *primary channel*. For multi-channel pipettes picking up tips with all of their channels, the back-left channel is considered primary. When using fewer channels, the ``start`` parameter of the :py:meth:`.InstrumentContext.configure_nozzle_layout` method can change the pipette's primary channel. See :ref:`partial-tip-pickup` for more information. With a pipette's default settings, you can generally access the wells indicated in the table below. Moving to any other well may cause the pipette to crash. diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index a2ca1e614a3..e799d25554f 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -6,26 +6,54 @@ Partial Tip Pickup ****************** -The 96-channel pipette occupies both pipette mounts on Flex, so it's not possible to attach another pipette at the same time. Partial tip pickup lets you perform some of the same actions that you would be able to perform with a second pipette. As of version 2.16 of the API, you can configure the 96-channel pipette to pick up a single column of tips, similar to the behavior of an 8-channel pipette. +By default, multi-channel pipettes always use all of their nozzles to pick up tips and handle liquids: an 8-channel pipette picks up 8 tips at once, and a 96-channel pipette picks up 96 tips at once. Partial tip pickup lets you configure a multi-channel pipette to use fewer tips. This expands the liquid handling capabilities of your robot without having to physically switch pipettes, and is especially useful for the Flex 96-Channel Pipette, which occupies both pipette mounts. -Nozzle Layout -============= +Before getting started with partial tip pickup, make sure your protocol specifies an API version that supports the configuration you need. -Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips the 96-channel pipette will pick up. The method's ``style`` parameter accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. +.. list-table:: + :header-rows: 1 + + * - Pipette + - Partial configuration + - Minimum API version + * - Flex 96-Channel Pipette + - Column + - 2.16 + * - Flex 96-Channel Pipette + - Single, row + - 2.20 + * - Flex 8-Channel Pipettes + - Single, partial column + - 2.20 + * - OT-2 Multi-Channel Pipettes + - Single, partial column + - 2.20 + +.. _nozzle-layouts: + +Nozzle Layouts +============== + +Use the :py:meth:`.configure_nozzle_layout` method to choose how many tips a pipette will pick up. The method's required ``style`` parameter only accepts special layout constants. You must import these constants at the top of your protocol, or you won't be able to configure the pipette for partial tip pickup. At minimum, import the API from the ``opentrons`` package:: from opentrons import protocol_api -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=protocol_api.COLUMN``. +This import statement lets you configure a layout with a parameter like ``style=protocol_api.COLUMN``. For greater convenience, also import the individual layout constants that you plan to use in your protocol:: from opentrons.protocol_api import COLUMN, ALL -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=COLUMN``. +This more specific import statement lets you configure a layout with a parameter like ``style=COLUMN``. However, you wouldn't be able to set ``style=ROW`` without also importing that constant. -Here is the start of a protocol that performs both imports, loads a 96-channel pipette, and sets it to pick up a single column of tips. +The examples in the sections below use the shorter style and show the other required parameters of ``configure_nozzle_layout()``. + +Column Layout +------------- + +Here is the start of a protocol that imports the ``COLUMN`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single column of tips. .. code-block:: python :substitutions: @@ -36,7 +64,7 @@ Here is the start of a protocol that performs both imports, loads a 96-channel p requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} def run(protocol: protocol_api.ProtocolContext): - column_rack = protocol.load_labware( + partial_rack = protocol.load_labware( load_name="opentrons_flex_96_tiprack_1000ul", location="D3" ) @@ -45,26 +73,25 @@ Here is the start of a protocol that performs both imports, loads a 96-channel p pipette.configure_nozzle_layout( style=COLUMN, start="A12", - tip_racks=[column_rack] + tip_racks=[partial_rack] ) .. versionadded:: 2.16 Let's unpack some of the details of this code. -First, we've given a special name to the tip rack, ``column_rack``. You can name your tip racks whatever you like, but if you're performing full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. +First, we've given a special name to the tip rack, ``partial_rack``. You can name your tip racks whatever you like, but if you're using a 96-channel pipette for full pickup and partial pickup in the same protocol, you'll need to keep them separate. See :ref:`partial-tip-rack-adapters` below. Next, we load the 96-channel pipette. Note that :py:meth:`.load_instrument` only has a single argument. The 96-channel pipette occupies both mounts, so ``mount`` is omissible. The ``tip_racks`` argument is always optional. But it would have no effect to declare it here, because every call to ``configure_nozzle_layout()`` resets the pipette's :py:obj:`.InstrumentContext.tip_racks` property. Finally, we configure the nozzle layout, with three arguments. - The ``style`` parameter directly accepts the ``COLUMN`` constant, since we imported it at the top of the protocol. - - The ``start`` parameter accepts a nozzle name, representing the back-left nozzle in the layout, as a string. ``"A12"`` tells the pipette to use its rightmost column of nozzles for pipetting. + - The ``start`` parameter accepts a nozzle name, representing the primary nozzle in the layout, as a string. ``"A12"`` tells the pipette to use its rightmost column of nozzles for pipetting. - The ``tip_racks`` parameter tells the pipette which racks to use for tip tracking, just like :ref:`adding tip racks ` when loading a pipette. In this configuration, pipetting actions will use a single column:: - # configured in COLUMN mode pipette.pick_up_tip() # picks up A1-H1 from tip rack pipette.drop_tip() pipette.pick_up_tip() # picks up A2-H2 from tip rack @@ -73,16 +100,219 @@ In this configuration, pipetting actions will use a single column:: :py:meth:`.InstrumentContext.pick_up_tip` always accepts a ``location`` argument, regardless of nozzle configuration. Do not pass a value that would lead the pipette to line up over more unused tips than specified by the current layout. For example, setting ``COLUMN`` layout and then calling ``pipette.pick_up_tip(tip_rack["A2"])`` on a full tip rack will lead to unexpected pipetting behavior and potential crashes. +Row Layout +---------- + +Here is the start of a protocol that imports the ``ROW`` and ``ALL`` layout constants, loads a 96-channel pipette, and sets it to pick up a single row of tips. + +.. code-block:: python + :substitutions: + + from opentrons import protocol_api + from opentrons.protocol_api import ROW, ALL + + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} + + def run(protocol: protocol_api.ProtocolContext): + partial_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="D3" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument("flex_96channel_1000") + pipette.configure_nozzle_layout( + style=ROW, + start="H1", + tip_racks=[partial_rack] + ) + +.. versionadded:: 2.20 + +Setting ``start="H1"`` means the pipette will use its frontmost nozzles to pick up tips, starting from the back of the tip rack:: + + pipette.pick_up_tip() # picks up A1-A12 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up B1-B12 from tip rack + +You can also set ``start="A1"`` to use the backmost nozzles and pick up from the front of the tip rack. + +.. note:: + + Consider the placement of your tip rack when choosing the ``start`` value for row pickup. The pipette cannot pick up from back to front (``start="H1"``) on tip racks in row A of the deck, nor can it pick up from front to back (``start="A1"``) on tip racks in row D of the deck. This is because the pipette can't move far enough backward or forward, respectively, to align over those tips. + + Use a different ``start`` value, or load the tip rack in row B or C. + +Single Layout +------------- + +Single-tip pickup is available on both 8-channel and 96-channel pipettes. 8-channel pipettes can pick up a single tip with either the front or back nozzle. 96-channel pipettes can pick up a single tip with any of the corner nozzles. + +.. note:: + Remember that only the A1 and H12 nozzles of the 96-channel pipette contain pressure sensors. Avoid using the A12 and H1 nozzles for single-tip pickup if you need to detect liquid presence within wells. + +The ``start`` parameter sets the first and only nozzle used in the configuration. It also affects the order in which the pipette picks up tips. When using automatic tip tracking, single-tip configurations always consume all tips within a single column before proceeding to another column. + +.. list-table:: + :header-rows: 1 + + * - Pipette type + - ``start`` well + - Pickup order + * - 8-channel + - A1 + - | Front to back, left to right + | (H1 through A1, H2 through A2, …) + * - 8-channel + - H1 + - | Back to front, left to right + | (A1 through H1, A2 through H2, …) + * - 96-channel + - A1 + - | Front to back, right to left + | (H12 through A12, H11 through A11, …) + * - 96-channel + - H1 + - | Back to front, right to left + | (A12 through H12, A11 through H11, …) + * - 96-channel + - A12 + - | Front to back, left to right + | (H1 through A1, H2 through A2, …) + * - 96-channel + - H12 + - | Back to front, left to right + | (A1 through H1, A2 through H2, …) + +Since they follow the same pickup order as a single-channel pipette, Opentrons recommends using the following configurations: + +- For 8-channel pipettes, ``start="H1"``. +- For 96-channel pipettes, ``start="H12"``. + +Here is the start of a protocol that imports the ``SINGLE`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up a single tip. + +.. code-block:: python + :substitutions: + + from opentrons import protocol_api + from opentrons.protocol_api import SINGLE, ALL + + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} + + def run(protocol: protocol_api.ProtocolContext): + partial_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="D3" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument( + instrument_name="flex_8channel_1000", + mount="left" + ) + pipette.configure_nozzle_layout( + style=SINGLE, + start="H12", + tip_racks=[partial_rack] + ) + +.. versionadded:: 2.20 + +Since this configuration uses ``start="H12"``, it will pick up tips in the usual order:: + + pipette.pick_up_tip() # picks up A1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up B1 from tip rack + +.. note:: + + You can pick up tips row by row, rather than column by column, by specifying a location for :py:meth:`.pick_up_tip` each time you use it in ``SINGLE`` configuration. However, as with all partial tip layouts, be careful that you don't place the pipette in a position where it overlaps more tips than intended. + + +Partial Column Layout +--------------------- + +Partial column pickup is available on 8-channel pipettes only. Partial columns contain 2 to 7 consecutive tips in a single column. The pipette always picks up partial columns with its frontmost nozzles (``start="H1"``). + +To specify the number of tips to pick up, add the ``end`` parameter when calling :py:meth:`.configure_nozzle_layout`. Use the chart below to determine the end row (G through B) for your desired number of tips. The end column should be the same as your start column (1 or 12). + +.. list-table:: + :stub-columns: 1 + + * - Number of tips + - 2 + - 3 + - 4 + - 5 + - 6 + - 7 + * - ``end`` row + - G + - F + - E + - D + - C + - B + +When picking up 3, 5, 6, or 7 tips, extra tips will be left at the front of each column. You can use these tips with a different nozzle configuration, or you can manually re-rack them at the end of your protocol for future use. + +Here is the start of a protocol that imports the ``PARTIAL_COLUMN`` and ``ALL`` layout constants, loads an 8-channel pipette, and sets it to pick up four tips: + +.. code-block:: python + :substitutions: + + from opentrons import protocol_api + from opentrons.protocol_api import PARTIAL_COLUMN, ALL + + requirements = {"robotType": "Flex", "apiLevel": "|apiLevel|"} + + def run(protocol: protocol_api.ProtocolContext): + partial_rack = protocol.load_labware( + load_name="opentrons_flex_96_tiprack_1000ul", + location="B2" + ) + trash = protocol.load_trash_bin("A3") + pipette = protocol.load_instrument("flex_8channel_1000", mount="left") + pipette.configure_nozzle_layout( + style=PARTIAL_COLUMN, + start="H1", + end="E1", + tip_racks=[partial_rack] + ) + +.. versionadded:: 2.20 + +This configuration will pick up tips from the back half of column 1, then the front half of column 1, then the back half of column 2, and so on:: + + pipette.pick_up_tip() # picks up A1-D1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up E1-H1 from tip rack + pipette.drop_tip() + pipette.pick_up_tip() # picks up A2-D2 from tip rack + +When handling liquids in partial column configuration, remember that *the frontmost channel of the pipette is its primary channel*. For example, to use the same configuration as above to transfer liquid from wells A1–D1 to wells A2–D2 on a plate, you must use the wells in row D as the source and destination targets:: + + # pipette in 4-nozzle partial column layout + pipette.transfer( + volume=100, + source=plate["D1"], # aspirate from A1-D1 + dest=plate["D2"], # dispense into A2-D2 + ) + +.. warning:: + + Do not move the pipette to row A of labware when in ``PARTIAL_COLUMN`` configuration! This is different than when pipetting to a full column, either with the 8-channel pipette in ``ALL`` configuration or with the 96-channel pipette in ``COLUMN`` configuration. + + If you pipette to row A, the frontmost tip will move to row A and the other tips — further back in the layout — will hang over the back edge of the labware. They will not enter the correct wells and they will likely cause a crash. + .. _partial-tip-rack-adapters: Tip Rack Adapters ================= -You can use both partial and full tip pickup in the same protocol. This requires having some tip racks directly on the deck, and some tip racks in the tip rack adapter. +You can use both partial and full tip pickup in the same protocol. When using both with a 96-channel pipette, you must load some tip racks directly on the deck, and some tip racks in a tip rack adapter. -Do not use a tip rack adapter when performing partial tip pickup. Instead, place the tip rack on the deck. During partial tip pickup, the 96-channel pipette lowers onto the tip rack in a horizontally offset position. If the tip rack were in its adapter, the pipette would collide with the adapter's posts, which protrude above the top of the tip rack. If you configure the pipette for partial pickup and then call ``pick_up_tip()`` on a tip rack that's loaded onto an adapter, the API will raise an error. +Do not use a tip rack adapter when performing partial tip pickup with a 96-channel pipette. Instead, place the tip rack on the deck. During partial tip pickup, the 96-channel pipette lowers onto the tip rack in an offset position. If the tip rack were in its adapter, the pipette could collide with the adapter's posts, which protrude above the top of the tip rack. If you configure the 96-channel pipette for partial pickup and then call ``pick_up_tip()`` on a tip rack that's loaded onto an adapter, the API will raise an error. -On the other hand, you must use the tip rack adapter for full tip pickup. If the 96-channel pipette is in a full layout, either by default or by configuring ``style=ALL``, and you then call ``pick_up_tip()`` on a tip rack that's not in an adapter, the API will raise an error. +On the other hand, you must use the tip rack adapter for full rack pickup. If the 96-channel pipette is in a full layout, either by default or by configuring ``style=ALL``, and you then call ``pick_up_tip()`` on a tip rack that's not in an adapter, the API will raise an error. When switching between full and partial pickup, you may want to organize your tip racks into lists, depending on whether they're loaded on adapters or not. @@ -108,7 +338,7 @@ When switching between full and partial pickup, you may want to organize your ti .. Tip:: - It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (i.e., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. + It's also good practice to keep separate lists of tip racks when using multiple partial tip pickup configurations (e.g., using both column 1 and column 12 in the same protocol). This improves positional accuracy when picking up tips. Additionally, use Labware Position Check in the Opentrons App to ensure that the partial configuration is well-aligned to the rack. Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``:: @@ -123,7 +353,7 @@ Now, when you configure the nozzle layout, you can reference the appropriate lis style=ALL, tip_racks=full_tip_racks ) - pipette.pick_up_tip() # picks up full rack in C1 + pipette.pick_up_tip() # picks up full rack in C3 This keeps tip tracking consistent across each type of pickup. And it reduces the risk of errors due to the incorrect presence or absence of a tip rack adapter. @@ -131,9 +361,9 @@ This keeps tip tracking consistent across each type of pickup. And it reduces th Tip Pickup and Conflicts ======================== -During partial tip pickup, 96-channel pipette moves into spaces above adjacent slots. To avoid crashes, the API prevents you from performing partial tip pickup when there is tall labware in these spaces. The current nozzle layout determines which labware can safely occupy adjacent slots. +During partial tip pickup, pipettes move into spaces above adjacent slots. To avoid crashes, the API prevents you from performing partial tip pickup when there is tall labware in these spaces. The current nozzle layout determines which labware can safely occupy adjacent slots. -The API will raise errors for potential labware crashes when using a column nozzle configuration. Nevertheless, it's a good idea to do the following when working with partial tip pickup: +The API will raise errors for potential labware crashes when using a partial nozzle configuration. Nevertheless, it's a good idea to do the following when working with partial tip pickup: - Plan your deck layout carefully. Make a diagram and visualize everywhere the pipette will travel. - Simulate your protocol and compare the run preview to your expectations of where the pipette will travel. @@ -146,6 +376,10 @@ For column pickup, Opentrons recommends using the nozzles in column 12 of the pi start="A12", ) +.. note:: + + When using a column 1 layout, the pipette can't reach the rightmost portion of labware in slots A3–D3. Any well that is within 29 mm of the right edge of the slot may be inaccessible. Use a column 12 layout if you need to pipette in that area. + When using column 12, the pipette overhangs space to the left of wherever it is picking up tips or pipetting. For this reason, it's a good idea to organize tip racks front to back on the deck. If you place them side by side, the rack to the right will be inaccessible. For example, let's load three tip racks in the front left corner of the deck:: tips_C1 = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "C1") @@ -161,15 +395,6 @@ You would get a similar error trying to aspirate from or dispense into a well pl .. tip:: - When using column 12 for partial tip pickup and pipetting, generally organize your deck with the shortest labware on the left side of the deck, and the tallest labware on the right side. - -If your application can't accommodate a deck layout that works well with column 12, you can configure the 96-channel pipette to pick up tips with column 1:: - - pipette.configure_nozzle_layout( - style=COLUMN, - start="A1", - ) - -.. note:: + When using column 12 nozzles for partial tip pickup and pipetting, generally organize your deck with the shortest labware on the left side of the deck, and the tallest labware on the right side. - When using a column 1 layout, the pipette can't reach the rightmost portion of labware in slots A3–D3. Any well that is within 29 mm of the right edge of the slot may be inaccessible. Use a column 12 layout if you need to pipette in that area. \ No newline at end of file + Similarly, when using the frontmost row of nozzles for partial tip pickup and pipetting, organize your deck with the shortest labware towards the back of the deck, and the tallest labware towards the front of the deck. diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index 9c4ccc62a0d..8a4eae39718 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -68,7 +68,7 @@ The maximum supported API version for your robot is listed in the Opentrons App If you upload a protocol that specifies a higher API level than the maximum supported, your robot won't be able to analyze or run your protocol. You can increase the maximum supported version by updating your robot software and Opentrons App. -Opentrons robots running the latest software (7.3.0) support the following version ranges: +Opentrons robots running the latest software (8.0.0) support the following version ranges: * **Flex:** version 2.15–|apiLevel|. * **OT-2:** versions 2.0–|apiLevel|. @@ -84,6 +84,8 @@ This table lists the correspondence between Protocol API versions and robot soft +-------------+------------------------------+ | API Version | Introduced in Robot Software | +=============+==============================+ +| 2.20 | 8.0.0 | ++-------------+------------------------------+ | 2.19 | 7.3.1 | +-------------+------------------------------+ | 2.18 | 7.3.0 | @@ -135,6 +137,7 @@ Changes in API Versions Version 2.20 ------------ +- :py:meth:`.configure_nozzle_layout` now accepts row, single, and partial column layout constants. See :ref:`partial-tip-pickup`. - You can now call :py:obj:`.ProtocolContext.define_liquid()` without supplying a ``description`` or ``display_color``. Version 2.19 diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 65d6cc63ff8..719bbb369f3 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -2012,16 +2012,19 @@ def configure_nozzle_layout( # noqa: C901 tips from a tip rack that is in an adapter, the API will raise an error. :param style: The shape of the nozzle layout. + You must :ref:`import the layout constant ` in order to use it. - - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single of well on labware. - - ``COLUMN`` sets the pipette to use 8 nozzles, aligned from front to back - with respect to the deck. This corresponds to a column of wells on labware. - - ``PARTIAL_COLUMN`` sets the pipette to use 2-7 nozzles, aligned from front to back - with respect to the deck. - - ``ROW`` sets the pipette to use 12 nozzles, aligned from left to right - with respect to the deck. This corresponds to a row of wells on labware. - ``ALL`` resets the pipette to use all of its nozzles. Calling ``configure_nozzle_layout`` with no arguments also resets the pipette. + - ``COLUMN`` sets a 96-channel pipette to use 8 nozzles, aligned from front to back + with respect to the deck. This corresponds to a column of wells on labware. + For 8-channel pipettes, use ``ALL`` instead. + - ``PARTIAL_COLUMN`` sets an 8-channel pipette to use 2--7 nozzles, aligned from front to back + with respect to the deck. Not compatible with the 96-channel pipette. + - ``ROW`` sets a 96-channel pipette to use 12 nozzles, aligned from left to right + with respect to the deck. This corresponds to a row of wells on labware. + Not compatible with 8-channel pipettes. + - ``SINGLE`` sets the pipette to use 1 nozzle. This corresponds to a single well on labware. :type style: ``NozzleLayout`` or ``None`` :param start: The primary nozzle of the layout, which the robot uses @@ -2039,16 +2042,15 @@ def configure_nozzle_layout( # noqa: C901 should be of the same format used when identifying wells by name. Required when setting ``style=PARTIAL_COLUMN``. - .. note:: - Nozzle layouts numbering between 2-7 nozzles, account for the distance from - ``start``. For example, 4 nozzles would require ``start="H1"`` and ``end="E1"``. - :type end: str or ``None`` :param tip_racks: Behaves the same as setting the ``tip_racks`` parameter of :py:meth:`.load_instrument`. If not specified, the new configuration resets :py:obj:`.InstrumentContext.tip_racks` and you must specify the location every time you call :py:meth:`~.InstrumentContext.pick_up_tip`. :type tip_racks: List[:py:class:`.Labware`] + + .. versionchanged:: 2.20 + Added partial column, row, and single layouts. """ # TODO: add the following back into the docstring when QUADRANT is supported #