feat(api): allow disposal locations as destinations for transfer and consolidate with liquid class

[jbleon95]

Overview

Addresses AUTH-1477.

This PR adds support for having a trash bin or waste chute as a destination for transfer_with_liquid_class and consolidate_with_liquid_class. Only one trash bin or waste chute can be assigned as the destination, and this is separate from the trash_location argument (though there is nothing stopping one from making it the same).

When a trash bin is a destination, a few steps of the liquid class transfer process are modified. We will not submerge or retract into the trash bin or waste chute, but simply just move to the default location (unless a trash bin/waste chute with an offset is given via .top()) and dispense from there. Additionally, we will not touch tip inside the trash bin or waste chute, but we will still blow-out.

Test Plan and Hands on Testing

Tested the following protocol on a robot

requirements = {
    "robotType": "Flex",
    "apiLevel": "2.23"
}

metadata = {
    "protocolName":'Liquid Class Transfers with Trash',
}

def run(protocol_context):
    tiprack = protocol_context.load_labware("opentrons_flex_96_tiprack_50ul", "C2")
    trash = protocol_context.load_trash_bin('A3')
    pipette_1k = protocol_context.load_instrument("flex_1channel_50", "left", tip_racks=[tiprack])
    arma_plate = protocol_context.load_labware("armadillo_96_wellplate_200ul_pcr_full_skirt", "D1")

    water_class = protocol_context.define_liquid_class("water")

    pipette_1k.transfer_with_liquid_class(
        liquid_class=water_class,
        volume=20,
        source=arma_plate.columns()[0][:2],
        dest=trash,
        new_tip="always",
        trash_location=trash,
    )

    pipette_1k.consolidate_with_liquid_class(
        liquid_class=water_class,
        volume=20,
        source=arma_plate.columns()[0][:2],
        dest=trash,
        new_tip="once",
        trash_location=trash,
    )

Changelog

• transfer_with_liquid_class and consolidate_with_liquid_class dest argument can now accept TrashBin and WasteChute objects

Review requests

Should we keep the delays used after the submerge and retract movement steps? We aren't actually submerging or retracting out of liquid, but it's unclear whether we should leave this in for less differences between well/trash destination, or if they are completely unnecessary.

Also, this PR only allows a singular trash bin or waste chute as a destination for transfer, you can not mix and match disposal locations in a list. This matches what PD allows, but should we be more permissive in the Python API?

Risk assessment

Low-medium. Really only touches liquid class submerge and retract after single dispense steps as far as implementation changes. Any regressions should be caught in snapshot tests.

[ecormany]

A few docstring comments. Thanks for making the initial changes! If you take any of my suggestions, make sure to apply them to the parallel places across the other two _with_liquid methods.

[ecormany]

editor brain, engage

Suggested change

	" to transfer liquid onto one destinations from many sources, use 'consolidate_liquid'."
	" to transfer liquid to one destination from many sources, use 'consolidate_liquid'."

[ecormany]

I get what we're going for here, but maybe it's clearer if we say something like this:

A single well for the pipette to target. Single-channel pipettes and multi-channel pipettes in SINGLE configuration will only aspirate from this well. Multi-channel pipettes in other configurations will place the primary nozzle over this well and aspirate from several wells.

[sanni-t]

@ecormany you are correct that we should rewrite the description to be clearer. But your suggested description implies that one can only specify a single well here, which is not true. If you are using a multi-channel pipette, then you can specify a list of wells here as long as all the wells are simultaneously accessed by the active channels.

[ecormany]

Two options here.

Treat all as equals:

A single well, list of wells, trash bin, or waste chute…

Combine trash containers, using that term:

A single well, list of wells, or trash container…

We use "trash container" in the docstring for several other location-specifying parameters.

[sanni-t]

The term "trash container" includes a labware set as the trash as well, which can be confusing here. I think the 'treat all as equal' option is better here.

[ecormany]

Should we go ahead and give this capability to standard transfer() too? Is it a big or small lift now that you've done the work of implementing it in transfer_with_liquid_class() et al.? #14393 flagged this as a regression early last year.

[sanni-t]

Looks great! Just some small suggestions

[sanni-t]

The term "trash container" includes a labware set as the trash as well, which can be confusing here. I think the 'treat all as equal' option is better here.

[sanni-t]

@ecormany you are correct that we should rewrite the description to be clearer. But your suggested description implies that one can only specify a single well here, which is not true. If you are using a multi-channel pipette, then you can specify a list of wells here as long as all the wells are simultaneously accessed by the active channels.