From 44f33eef9f7a3a00e95b19ff1a1979dd050948db Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Wed, 24 Apr 2024 15:05:58 -0400 Subject: [PATCH 1/2] probably don't use column 1 partial pickup --- api/docs/v2/pipettes/partial_tip_pickup.rst | 33 ++++--------------- api/docs/v2/versioning.rst | 4 +++ .../protocol_api/instrument_context.py | 13 +++++--- 3 files changed, 18 insertions(+), 32 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index a1e78fed570..c50016fdc80 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -135,12 +135,7 @@ The API will raise errors for potential labware crashes when using a column nozz - Simulate your protocol and compare the run preview to your expectations of where the pipette will travel. - Perform a dry run with only tip racks on the deck. Have the Emergency Stop Pendant handy in case you see an impending crash. -For column pickup, Opentrons recommends using the nozzles in column 12 of the pipette. - -Using Column 12 ---------------- - -The examples in this section use a 96-channel pipette configured to pick up tips with column 12:: +For column pickup, Opentrons recommends using the nozzles in column 12 of the pipette:: pipette.configure_nozzle_layout( style=COLUMN, @@ -164,26 +159,10 @@ You would get a similar error trying to aspirate from or dispense into a well pl 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. -Using Column 1 --------------- - -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", - ) - -The major drawback of this configuration, compared to using column 12, is that tip tracking is not available with column 1. You must always specify a ``location`` parameter for :py:meth:`.pick_up_tip`. This *requires careful tip tracking* so you don't place the pipette over more than a single column of unused tips at once. You can write some additional code to manage valid tip pickup locations, like this:: - - tip_rack = protocol.load_labware("opentrons_flex_96_tiprack_1000ul", "C1") - pipette.configure_nozzle_layout(style=COLUMN, start="A1") - row_a = tip_rack.rows()[0] - pipette.pick_up_tip(row_a.pop()) # pick up A12-H12 - pipette.drop_tip() - pipette.pick_up_tip(row_a.pop()) # pick up A11-H11 - pipette.drop_tip() +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, but this is not recommended. Column 1 pickup has several drawbacks: -This code first constructs a list of all the wells in row A of the tip rack. Then, when picking up a tip, instead of referencing one of those wells directly, the ``location`` is set to ``row_a.pop()``. This uses the `built-in pop method `_ to get the last item from the list and remove it from the list. If you keep using this approach to pick up tips, you'll get an error once the tip rack is empty — not from the API, but from Python itself, since you're trying to ``pop`` an item from an empty list. +- Tip pickup force may be incorrect, leading to poor tip fit and loss of positional accuracy. +- Automatic tip tracking is not available +- The rightmost columns in labware in column 3 may be inaccessible, if they are beyond the movement limit of the pipette (within 29 mm of the right edge of the slot). -Additionally, you can't access the rightmost columns in labware in column 3, since they are beyond the movement limit of the pipette. The exact number of inaccessible columns varies by labware type. Any well that is within 29 mm of the right edge of the slot may be inaccessible in a column 1 configuration. Call ``configure_nozzle_layout()`` again to switch to a column 12 layout if you need to pipette in that area. +For these reasons, use column 12 whenever possible. \ No newline at end of file diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index 5819bee4b47..bc44a6413cd 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -155,6 +155,10 @@ This version introduces new features for Flex and adds and improves methods for - :py:obj:`.ProtocolContext.fixed_trash` and :py:obj:`.InstrumentContext.trash_container` now return :py:class:`.TrashBin` objects instead of :py:class:`.Labware` objects. - Flex will no longer automatically drop tips in the trash at the end of a protocol. You can add a :py:meth:`.drop_tip()` command to your protocol or use the Opentrons App to drop the tips. +- Known limitations + + - Using ``configure_nozzle_layout()`` with ``COLUMN`` layout and ``start="A1"`` is not fully supported and may lead to unreliable pipetting behavior. + Version 2.15 ------------ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 316625d44c9..8302e89e6c5 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -1947,11 +1947,14 @@ def configure_nozzle_layout( should be of the same format used when identifying wells by name. Required unless setting ``style=ALL``. - .. note:: - When using the ``COLUMN`` layout, the only fully supported value is - ``start="A12"``. You can use ``start="A1"``, but this will disable tip - tracking and you will have to specify the ``location`` every time you - call :py:meth:`.pick_up_tip`, such that the pipette picks up columns of + .. warning:: + Specifying ``COLUMN`` layout and ``start="A1"`` is not fully supported. + Tip pickup force may be incorrect, leading to poor tip fit and loss of + positional accuracy. + + Additionally, ``start="A1"`` disables automatic tip tracking, + so you must specify the ``location`` every time you call + :py:meth:`.pick_up_tip`, ensuring that the pipette picks up columns of tips *from right to left* on the tip rack. :type start: str or ``None`` From 4dc27cf3c8c88ec8600403f3e66a987874c76809 Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Fri, 26 Apr 2024 21:56:09 -0400 Subject: [PATCH 2/2] second draft. columns 1 and 12 are both ok if not mixed. --- api/docs/v2/pipettes/partial_tip_pickup.rst | 21 ++++++++++++------- api/docs/v2/versioning.rst | 4 ---- .../protocol_api/instrument_context.py | 12 +++-------- 3 files changed, 17 insertions(+), 20 deletions(-) diff --git a/api/docs/v2/pipettes/partial_tip_pickup.rst b/api/docs/v2/pipettes/partial_tip_pickup.rst index c50016fdc80..a2ca1e614a3 100644 --- a/api/docs/v2/pipettes/partial_tip_pickup.rst +++ b/api/docs/v2/pipettes/partial_tip_pickup.rst @@ -23,7 +23,7 @@ For greater convenience, also import the individual layout constants that you pl from opentrons.protocol_api import COLUMN, ALL -Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=COLUMN``. +Then when you call ``configure_nozzle_layout`` later in your protocol, you can set ``style=COLUMN``. 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. @@ -106,6 +106,10 @@ When switching between full and partial pickup, you may want to organize your ti partial_tip_racks = [tips_1, tips_2] full_tip_racks = [tips_3, tips_4] +.. 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. + Now, when you configure the nozzle layout, you can reference the appropriate list as the value of ``tip_racks``:: pipette.configure_nozzle_layout( @@ -120,7 +124,7 @@ Now, when you configure the nozzle layout, you can reference the appropriate lis tip_racks=full_tip_racks ) pipette.pick_up_tip() # picks up full rack in C1 - + 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. @@ -159,10 +163,13 @@ You would get a similar error trying to aspirate from or dispense into a well pl 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, but this is not recommended. Column 1 pickup has several drawbacks: +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", + ) -- Tip pickup force may be incorrect, leading to poor tip fit and loss of positional accuracy. -- Automatic tip tracking is not available -- The rightmost columns in labware in column 3 may be inaccessible, if they are beyond the movement limit of the pipette (within 29 mm of the right edge of the slot). +.. note:: -For these reasons, use column 12 whenever possible. \ No newline at end of file + 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 diff --git a/api/docs/v2/versioning.rst b/api/docs/v2/versioning.rst index bc44a6413cd..5819bee4b47 100644 --- a/api/docs/v2/versioning.rst +++ b/api/docs/v2/versioning.rst @@ -155,10 +155,6 @@ This version introduces new features for Flex and adds and improves methods for - :py:obj:`.ProtocolContext.fixed_trash` and :py:obj:`.InstrumentContext.trash_container` now return :py:class:`.TrashBin` objects instead of :py:class:`.Labware` objects. - Flex will no longer automatically drop tips in the trash at the end of a protocol. You can add a :py:meth:`.drop_tip()` command to your protocol or use the Opentrons App to drop the tips. -- Known limitations - - - Using ``configure_nozzle_layout()`` with ``COLUMN`` layout and ``start="A1"`` is not fully supported and may lead to unreliable pipetting behavior. - Version 2.15 ------------ diff --git a/api/src/opentrons/protocol_api/instrument_context.py b/api/src/opentrons/protocol_api/instrument_context.py index 8302e89e6c5..4c2c02d4242 100644 --- a/api/src/opentrons/protocol_api/instrument_context.py +++ b/api/src/opentrons/protocol_api/instrument_context.py @@ -1947,15 +1947,9 @@ def configure_nozzle_layout( should be of the same format used when identifying wells by name. Required unless setting ``style=ALL``. - .. warning:: - Specifying ``COLUMN`` layout and ``start="A1"`` is not fully supported. - Tip pickup force may be incorrect, leading to poor tip fit and loss of - positional accuracy. - - Additionally, ``start="A1"`` disables automatic tip tracking, - so you must specify the ``location`` every time you call - :py:meth:`.pick_up_tip`, ensuring that the pipette picks up columns of - tips *from right to left* on the tip rack. + .. note:: + If possible, don't use both ``start="A1"`` and ``start="A12"`` to pick up + tips *from the same rack*. Doing so can affect positional accuracy. :type start: str or ``None`` :param tip_racks: Behaves the same as setting the ``tip_racks`` parameter of