[Feature] Rewrite tilt module

[fderop]

I've done two things here:

1. Add carrier sites to the tilter. The reason for this is that it's really easy to 3d print a part that slots onto the tilt platform and extends the number of positions.
2. Rewrite logic that calculates the positions. I removed the function that updated the well positions since this is not super useful: it updates the origin of children, but does not apply a rotation to the rest of the geometry. For example, calling child.get_absolute_position("l", "c", "b") did not return an updated value for the well's "absolute bottom" after tilting. Instead, I added two functions: rotate_coordinate_around_hinge rotates any absolute coordinate around the tilt hinge, and return_well_drain_offsets returns the offsets that need to be applied to dispense and aspirate to pipette in the rotated well's "drain point".

In addition I added some minor functionalities:

• Whether the hinge is on the left or right of the box is automatically calculated
• I assume that the user will enter an absolute_angle i.e. if the hinge is positioned left or right of the tilter, the user still just inputs absolute_angle = 10. When coordinates are calculated, this is converted to angle, which has a sign (clockwise is negative, counter-clockwise is positive - this follows Euler rotation conventions and simplifies calculation of rotations).

[ben-ray]

thanks for the concise writeup! very helpful to keep updated

I remember this giving rick & I some trouble, so it's nice we have it properly solved

[rickwierenga]

Thank you for fixing the resource drain location, that's incredibly helpful.

Add carrier sites to the tilter. The reason for this is that it's really easy to 3d print a part that slots onto the tilt platform and extends the number of positions.

My main feedback on this PR is that I think this is slightly too much for the default TiltModule.

An alternative, almost equivalent, approach I would suggest is to 1) make the HamiltonTiltModule an MFXModule. @BioCam introduced this in #77 for working with modules that go on the MFXCarrier, like the tilt module. Specifically, because all (99%) of these modules take a single child, it has this child_resource_location attribute which helps movement of resources onto this mfxmodule resource. We will refactor this in the future to integrate with PlateAdapter, but for now let's use the MFXModule. 2) I would suggest making a new Resource for Retro's tilt-module-carrier, which is a subclass of Carrier and can go onto the MFXModule. The final tree would look like HamiltonTiltModule(Tilter, MFXModule) -> RetroTiltCarrier -> Plate`. This is more extendible and more organized.

[BioCam]

1. make the HamiltonTiltModule an MFXModule

Thank you for pointing this out @rickwierenga.

I agree, and think that we should modify a couple of machines in this way:
I propose machines like the tilt_module, heaters, shakers, thermocyclers, fillable_reservoirs, ... actually have a physical definition that can easily be called by the frontend, like:

frontend(backend=backend, model=resource_definition)

At the moment, the resource definitions appear to be completely handled by the frontend:
e.g.

def HamiltonTiltModule(   # <=== frontend
  name: str,
  com_port: str,
  write_timeout: float = 10, timeout: float = 10
) -> Tilter:
  return Tilter(  # <=== I'm not sure what to call this, in this special case?
    name=name,
    backend=HamiltonTiltModuleBackend( # <=== backend
      com_port=com_port, write_timeout=write_timeout, timeout=timeout
    ),
    size_x=132, # <=== physical definition
    size_y=92.57, # <=== physical definition
    size_z=85.81, # <=== physical definition
  )

This means that while the frontend is easily adaptable / agnostic to the backend, the physical definition is not, making the backend agnosticity impossible to utilise.

I propose that we modularise the physical definition in lockstep to the modularisation of the backend.
This dual modularity would mean that we can mix and match backends and machine definitions, e.g. if a version_2 of a tilt module is being created which has a different geometry but the same control capabilities, we can use the same backend but a new physical definition.

This would be in analogy of how we create liquid handler instances, generating more homogenous frontend instantiation across PLR:

lh = LiquidHandler(backend=backend, deck=STARLetDeck())

Since these machines are physically attached to MFX_carriers and they only take a single child resource, I have been implementing them as instances of MFXModule.

Importantly, this would also mean that we can use these machines as simple holders even if we don't/can't establish computational control of the machine's capabilities (e.g. a tilt module can be a site for a plate [without a pedestal!], an HHC can be a site for a semi-skirted plate, etc). Since machines are a bit of a pain to remove from the deck (removing the shaker_carrier requires bold removal...), this would mean we can keep them between different deck configurations, and make them useful even if the new deck doesn't require the machine's capabilities.

Please let me know what you think?

[rickwierenga]

The backend agnosticity is not impossible to use because the class still inherits from the main frontend Tilter. Restructuring this is a separate discussion, which we can definitely have, but I am honestly pretty happy with the current situation.

[BioCam]

Does this mean that all machines - except for liquid_handler - are defined by...

• "1st" frontend - agnostic interface to interact with the machine inside the script
• backend - code to control the machine programmatically
• "main" frontend - intermediate interface to give box coordinates of the resource and define special behaviour like single-child resource managment
  ?

[rickwierenga]

For now, yes, with a slight exception for LiquidHandler, which always has a Deck as its only child. Let's continue this discussion in a separate thread :)

[fderop]

An alternative, almost equivalent, approach I would suggest is to 1) make the HamiltonTiltModule an MFXModule. @BioCam introduced this in #77 for working with modules that go on the MFXCarrier, like the tilt module. Specifically, because all (99%) of these modules take a single child, it has this child_resource_location attribute which helps movement of resources onto this mfxmodule resource. We will refactor this in the future to integrate with PlateAdapter, but for now let's use the MFXModule. 2) I would suggest making a new Resource for Retro's tilt-module-carrier, which is a subclass of Carrier and can go onto the MFXModule. The final tree would look like HamiltonTiltModule(Tilter, MFXModule) -> RetroTiltCarrier -> Plate`. This is more extendible and more organized.

Thanks for the feedback, I will implement this.

e.g. a tilt module can be a site for a plate [without a pedestal!]

The tilt module's platform has a very pronounced pedestal which lifts the plate significantly. Do you have a writeup somewhere about the pedestal definition, because it's still confusing to me currently

[BioCam]

e.g. a tilt module can be a site for a plate [without a pedestal!]

The tilt module's platform has a very pronounced pedestal which lifts the plate significantly. Do you have a writeup somewhere about the pedestal definition, because it's still confusing to me currently

Yeah, I understand; this issue is quite complicated, and affects PLR utility massively at the moment.
You could read the forum thread PLR Carrier z-Height Issue in which Rick and I figured out together what was actually going wrong. But it's very long, and since we haven't fixed it yet we haven't written up the topic concisely in one place yet.

But since you're asking here and it is important for this PR, a quick attempt:

PlateCarrierSites can be of two types:

1. they have an elevation in their center which PLR now calls pedestal
2. they could just be a flat surface

This feature of the PlateCarrierSite is captured in the PlateCarrierSite attribute pedestal_z_height (if assigned to 0 it is a flat surface).

Importantly though: the PlateCarrierSite origin z-coordinate is always the topmost surface of the site!
This means the top surface of the pedestal (if there is a pedestal).

As a result of all of this there are 2 main possible PlateCarrierSite-to-Plate relationships:

This is what Hamilton software calls "container-based" (left) vs "rack-based" (right). We opted to avoid at least the term "rack-based" because there is no rack anywhere, instead it would be correct to call it "skirt-based" (a well-adapted known term for plates that doesn't have meaning in the labware universe already).

As can be seen in the above comparison, it is very important to get this right because if you don't you cannot use plates on flat surfaces - that is the current problem with Plate in PLR.
You can also see that a Plate placed on PlateCarrierSite with a pedestal actually "sinks" into the site.

There are a couple more details here but that's the basic problem.

For this PR:
In order to prep CarrierSites by giving them the required attribute pedestal_z_height we started to distinguish between "general" CarrierSite (mostly designed for tip_racks) and PlateCarrierSite (which is specifically designed to hold plates and has this new attribute).

Importantly, we do not have the same distinction with MFXModules.
I initially built the MFXModule by giving it a single CarrierSite. But Rick and I discussed this and for multiple reasons refactored it into MFXModules only taking a child_location attribute.
This means MFXModules which are designed for taking a plate (like in the above image) are currently missing the required attribute pedestal_z_height, and we have to figure out a way to add this information (without messing with MFXModules that are not designed for holding plates, e.g. tip_rack modules).

[fderop]

We decided to make the HamiltonTiltModule a child of only MFXModule. Multiple inheritance led to diamond inheritance issues (both MFXModule and Tilter inherited from Resource).

The tilter can be tested as such:

from pylabrobot.tilting.tilter import hamiltonTiltModule

# <Set up your deck here>

tilter_name = "tilter"
tilter = hamiltonTiltModule(name=tilter_name, com_port="/dev/tty.usbserial-FTDINDTT")
await tilter.setup()
print(tilter._setup_finished)
deck.get_resource(carrier_to_calibrate_name)[1] = tilter

plate_to_calibrate_name = "plate_to_calibrate"
plate = Corning_6_WP_Fl(plate_to_calibrate_name)
tilter.assign_child_resource(plate)

from retro_pylabrobot.liquid_classes.retro_liquid_classes import HighVolumeFilter_CellCultureMedium_DispenseJet

transfer_volume = 1000

await tilter.set_angle(10)

z_offset = 0.2

offsets = tilter.return_drain_offsets_of_plate(plate)
for aspirate_index in range(len(plate.children)):
    if aspirate_index != len(plate.children) - 1:
        dispense_index = aspirate_index + 1
    else:
        dispense_index = 0

    offset_adj = offsets[aspirate_index]
    offset_adj.z = offset_adj.z + z_offset
    await lh.aspirate(
        vols=[transfer_volume],
        resources=[plate.children[aspirate_index]],
        use_channels=[calibration_tip],
        offsets=[offset_adj],
        hamilton_liquid_classes=[HighVolumeFilter_CellCultureMedium_DispenseJet],
        immersion_depth=[0],
    )

    offset_adj = offsets[dispense_index]
    offset_adj.z = offset_adj.z + z_offset
    await lh.dispense(
        vols=[transfer_volume],
        resources=[plate.children[dispense_index]],
        use_channels=[calibration_tip],
        offsets=[offset_adj],
        hamilton_liquid_classes=[HighVolumeFilter_CellCultureMedium_DispenseJet],
        immersion_depth=[0],
    )

This should sequentially pipet from one well in a 6 well plate to the next. It should look like so:

https://youtu.be/03nXvlDh-l0

[rickwierenga]

I just updated:

• I am not sure where we decided to make HamiltonTiltModule an MFXModule, but Tilter definitely take precedence because it gives us hardware agnosticity.
• I kept hinge_coordinate and child_resource_location as attributes of Tilter because every tilt module is reasonably expected to use those attributes. This makes the logic you wrote for HamiltonTiltModule generalizable across all tilt modules.
• Now that HamiltonTiltModule is not an MFXModule, it's slightly unfortunate that we need to get child_resource_location "manually" in LiquidHandler, but it's similar with PlateReader, and just something to update in a future PR. If you think about it, we'd have to do this anyway for any new tilt module we might implement, and so either way requires a refactor for resources that specify child_resource_location.
• I kept pedestal_size_z as an attribute for future use in HamiltonTiltModule. We don't use it yet, and so that's also for another update soon.

Is it correct that return_drain_offsets_of_plate is a helper function for use during liquid handling, and that rotate_coordinate_around_hinge is a helper for return_drain_offsets_of_plate? (as discussed, we should combine this with the rotation update in the future, but for now I just want to know what these functions are intended for)

[fderop]

So now, adding assigning a plate to the tilter must be done as such: tilter.assign_child_resource(resource=plate, location=tilter.child_resource_location)

[fderop]

• I am not sure where we decided to make HamiltonTiltModule an MFXModule, but Tilter definitely take precedence because it gives us hardware agnosticity.

Just for clarity, I thought we decided this collectively based on the thread above - either way is fine though

[fderop]

I added the kwarg additional_z because it's really difficult to calibrate a tilt module with rotation properly (hinge coordinate for example, and instead of only having issues in z, you now have issues in x and y as well if you want to find the drain point properly). However, I also think there's a strong argument to be made that once get_well_drain_offsets() returns the offsets, z can be added outside of the function call - what do you think?

[rickwierenga]

I agree that it's better to apply the additional_z (or additional_{x,y}) on the user end, after calling get_well_drain_offsets. This way, get_well_drain_offsets stays well-defined. (otherwise, where does its functionality stop?) I removed it for now.

After this PR, I would love to replace .get_absolute_location("c", "c", "b") on line 129 of tilter.py with .get_drain_location() which will look at all rotations in the tree and get the drain location.

[rickwierenga]

I marked

• experimental_rotate_coordinate_around_hinge
• experimental_get_plate_drain_offsets
• experimental_get_well_drain_offsets

experimental because I anticipate we remove them very soon in favor of Rotation-based manipulations.

[rickwierenga]

i think it's good to merge! lmk!

sorry for the delays

[fderop]

i think it's good to merge! lmk!

sorry for the delays

Sounds great, thanks Rick!