feat(api): add execution of aspirate steps in a liquid class based transfer

[sanni-t]

Addresses AUTH-866

Overview

Part 1 of three-part series of implementing transfer function.

This PR adds a TransferComponentsExecutor class that executes individual parts of the overarching 'aspiration' process. These components are-

1. Submerge
2. Aspirate and wait
3. Dispense and wait
4. Mix
5. Pre-wet
6. Add/remove air gap
7. Retract

The InstrumentCore gets a new method aspirate_liquid_class() which utilizes the above executor to execute the aspiration steps in a specific order. aspirate_liquid_class() will then be utilized by the InstrumentCore.transfer_liquid() method to perform aspiration during each transfer step.
This method can also be accessed in the protocol by using private API accessors for testing purposes.

Test Plan and Hands on Testing

• Integrated and on-robot testing will have to wait until this implementation is wired up to the public API
• Added unit tests for all new functions and classes

Review requests

I landed on this architecture as it allows us to unit test the transfer using different configurations of the liquid class easily.
It also allows us to build the transfer step by step, and very importantly, allows hardware testing using individual aspirate and dispense steps (instead of testing one big transfer all at once).

Still, open to improvement suggestions.

There are a few TODOs in the code so far. Most of them will be addressed by the last PR of this 3-part series.

Risk assessment

Low. Makes no changes to the existing code.

[ddcc4]

Hey, does the upcoming get_next_tip() return the tip to use (stateless), or does it alter some internal state to indicate the tip it chose?

[sanni-t]

It returns the tip to use in a stateless way

[ddcc4]

lol

[ddcc4]

Does this just call the aspirate_liquid_class() function below?

[sanni-t]

aspirate_liquid_class and the upcoming dispense_liquid_class functions

[ddcc4]

So this PR primarily implements aspirate, which would not use functions like dispense_and_wait(), right? This is just here for illustration?

Edit: Oh wait, maybe you do use it because mix() is part of aspirate? Can you move this function below mix() so that the functions are arranged in roughly the order that they would be called during a transfer, so that a reader can read this file top-down and follow the program flow?

[ddcc4]

Hehe, this name is really too long. Maybe just transfer_executor?

But it doesn't even behave like the traditional meaning of an executor, which is a thing where you submit high-level tasks to and it decides when and how to run the tasks -- here, you the caller are the one choosing when and how to invoke the functions in the executor.

I hate the name helper, but this file really is just a transfer_helper. Hm ...

[sanni-t]

Ya I struggled with the name..

[ddcc4]

Hm, I'm not a fan of this get_...() function. It makes it look like you're calling a method on an object named tx_comps_executor. (I was confused because you had renamed the file in your import, and I didn't realize that you had done that, so I assumed tx_comps_executor was a variable name.)

If get_transfer_components_executor() doesn't do anything besides call the TransferComponentsExecutor constructor, can you just invoke the constructor directly here, to make it more obvious what's going on?

[sanni-t]

I had to add the get..() function in order to create a mock of the TransferComponentsExecutor in the tests.

[sanni-t]

Oh, also, another thought was to lru_cache to cache the TransferComponentsExecutor instance so only one instance would be created when the same liquid class and (source well -> dest-well) combo is being used. The getter would allow us to do that.

[ddcc4]

I had to add the get..() function in order to create a mock of the TransferComponentsExecutor in the tests.

Hm, is there a way to mock out the class itself? (In my past projects, we used unittest.mock instead of PyTest, which let you mock the class constructor itself, so that you wouldn't need to create get_ function just for testing.)

[ddcc4]

But secondly, I think the only reason that TransferComponentsExecutor is a class at all is to save you the trouble of passing in arguments like aspirate_location and source_well to the method calls every time, right?

TransferComponentsExecutor doesn't really have any state of its own and it doesn't manage any state, right? In that case, I'm not sure it deserves to be a class. How bad would it be to make transfer_components_executor.py just a flat file of stateless helper functions, and to pass in the necessary arguments on every call?

[sanni-t]

Ya, that's another decision I struggled with. This class originally contained the aspirate_liquid_class and dispense_liquid_class implementations too and was built to manage state between aspirates and dispenses since we do have to keep track of air gaps between the aspirates and dispenses (and some more stuff when implementing consolidate and distribute).

But then we needed to have aspirate_liquid_class and dispense_liquid_class available in the core (or some way to call the aspirate process and dispense process separately instead of in a big transfer) because of two reasons-

1. It's necessary for hardware testing since they need to run test scripts after each aspirate/ dispense process. With these in the instrument core, they can access them using private methods in their scripts.
2. We anticipate needing a public API for these liquid-class-based aspirate and dispense processes in the near future. At which point we will face this question again.

So I had to move a lot of things around to facilitate this and wasn't fully satisfied with the final architecture.
Splitting the TransferComponentsExecutor into individual functions will make the arguments list for each of these functions quite long but it's not a bad option.

[ddcc4]

Hey, so I don't know if you're planning to give TransferComponentsExecutor any internal state that it needs to manage on its own. But from the code so far in this PR, it looks like TransferComponentsExecutor's only reason for existing is so that we can split out some of the transfer-related functions so that we don't have to dump them all into InstrumentCore.

I think one typical way to do that is to define a mixin. So you would have something like:

class InstrumentCore(TransferHelperMixin):
  # The fields here are shared between this parent class and the mixin, e.g.:
  def move_to(): ...


class TransferHelperMixin:
  def submerge():
    ...
    self.move_to(...)
    ...

Depending on the type checker we're using, you may need to do a bit more work to tell the type checker that TransferHelperMixin has access to everything in InstrumentCore when it's mixed-in.