Make Plate Site-adaptive (Fix PLR plate location 3)

[BioCam]

Hi everyone,

In this PR I am adding conditional logic to enable correct Plate placements on PlateCarrierSites with and without pedestals, a bug that has been dramatically reducing adaptability and utility of PLR deck configurations so far.

This is the 3rd (and hopefully last) PR in a series of careful changes to fix Plate.
Previous associated PRs:

• Integrate material_z_thickness (Container) & skirt_base_to_well_base (Plate) (fix PLR Plate location 2) #183
• Implement pedestal for CarrierSite & MFXModule (fix PLR Plate location 1) #143

Summary of the issue

The world of PlateCarrierSites, i.e. the "slots" / "positions" / "sites" on a machine that a Plate can be placed upon, can be classified into two simple categories:

• site with a pedestal
• site without a pedestal

Figure 1 - PlateCarrierSite classification based on existence of pedestal (i.e. central elevation)

Any automation control system that wants to enable users to conduct experiments (i.e. tasks in which deck configurations can rapidly changed - as opposed to "process churning", i.e. tasks in which the exact same actions are performed repeatedly) has to account for this difference in PlateCarrierSites.
If ignored Plates cannot freely move between different sites, will crash if they do or require careful manual readjustment of every plate location based on the site it is being moved to.

In PLR a series of bugs prevented the implementation of a self-adjusting Plate placement feature.
I summarised them in this infographic:

Figure 2 - High-level summary of bugs, information previously missing, and actions needed to fix them

In short:

1. Plate - was wrongly defined: did not account for the clearance space between the outside bottom of a well and the bottom of the plate skirt (i.e. the dz), incorrectly labelled the material thickness of the well in the z dimension as dz, did not have a clearly defined geometric classification scheme.
2. Site - treated all sites the same (e.g. for tipracks and for plates), and required the creation of the PlateCarrierSite to enable the addition of information regarding the height/depth of a pedestal.
3. Site - required more precise definition: the topmost surface of a PlateCarrierSite is always its location's z-coordinate: if there is a pedestal, then the top of the pedestal is the z-coordinate.

PR Content

After adding material_z_thickness as an attribute to Container (and hence to Well), correcting Well's indirect attribute dz (which is equivalent to the Well's anchor z-coordinate after creating a clear definition), and adding pedestal_z_height to PlateCarrierSite in the previous 2 PRs...

...in this PR I merged all this information in...

• the assign_child_resource() method of PlateCarrierSite, and
• the lh.move_plate() method...
  ... to deal with the 3 possible scenarios of Plate-to-PlateCarrierSite relationships:

1. no pedestal
2. pedestal taller than plate.well.dz
3. pedestal shorter than plate.well.dz

I also updated the definitions of 5 plates to showcase examples of how plates of different types can be defined to enable accurate dynamical movement between different PlateCarrierSites.

Figure 3 - Possible Plate-to-PlateCarrierSite relationships

NB.: The PlateCarrierSite z-coordinate is above the z-coordinate of the Plate in scenario 2 and 3 -> This reflects the physical reality of the Plate "sinking" into the PlateCarrierSite and dramatically simplifies the conditional logic needed to represent this phenomenon:

pylabrobot/resources/carrier.py

class PlateCarrierSite(CarrierSite):
...
  def assign_child_resource(self, resource: Resource, location: Coordinate = Coordinate.zero(),
                            reassign: bool = True):
    if isinstance(resource, Plate):
      # Sanity check for equal well clearances / dz
      well_dz_set = {round(well.location.z, 2) for well in resource.get_all_children()
               if all([well.category == "well", well.location is not None])}
      assert len(well_dz_set) == 1, "All wells must have the same dz"
      well_dz = well_dz_set.pop()
      # Plate "sinking" logic based on well dz to pedestal relationship
      pedestal_size_z = abs(self.pedestal_size_z)
      z_sinking_depth = min(pedestal_size_z, well_dz)
      location = Coordinate(location.x, location.y, location.z - z_sinking_depth)

    return super().assign_child_resource(resource, location, reassign)

Next Steps

Still in this PR to figure out:
As a result of these changes plates can be used on different PlateCarrierSites.

But the location of a Well in relationship to its parent Plate is now corrected while the aspirate, dispense, move_to_z commands have not been adjusted to compensate for the new Well changes.
I.e. if one would aspirate from the "bottom" of a well now the pipette tip will crash into the bottom of the well by a distance equivalent to material_z_thickness.
This must not be the case.

Question to the PLR community: Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

At the moment, this dynamic plate placement only works when placing a Plate on a PlateCarrierSite.

I can see one other important instance in which we must enable the exact same dynamic plate placement: when placing a Plate on a MFXModule.
I initially built the MFXModule using a CarrierSite on it to place single plates onto it but we refactored this implementation into a specific-location based one instead (#77 ).
We could e.g.
(1) revert back to the old implementation but using PlateCarrierSite instead (that way we carry over the placement logic, or
(2) continue with MFXModule as a single-child location implementation and copy the plate placement from PlateCarrierSite onto it (but then have to also figure out how to navigate the difference between MFXModules that take Plate, TipRack, or Trough.

Please let me know what you think :)

Furthermore, once this PR is completed I will write a post-mortem of the entire Plate issue on the labautomation forum, and generate some docs information for a streamlined workflow to identify (1) a Well's material_z_thickness, and (2) a Plate.Well's correct dz value.

[BioCam]

I'm tagging a couple of people who I believe will be affected by the changes and who I would like to ask for feedback on the questions raised:

• @rickwierenga
• @ben-ray
• @jkhales
• @fderop

[fderop]

Thanks for tagging us @BioCam

Inconsequential, but the "sinking" terminology in my mind conflicts with the "pedestal" terminology - a pedestal lifts something up above a surface, just like the pedestal lifts up the well bottoms if pedestal height > well dz + material thickness.

Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

I think ideally nowhere, and we just make sure that the z origin coincides with the well bottom, which I think this PR is setting us up for.

At the moment, this dynamic plate placement only works when placing a Plate on a PlateCarrierSite.

I think ideally all resources with sites that potentially have a pedestal should inherit from a class where assign_child_resource applies the pedestal logic. Pedestal z could be 0 for sites without a pedestal. In this spirit, it seems like applying multiple inheritance to MFXModule could be a third option. If I'm not mistake, this would be the first multiple inheritance in PLR, so adding that will set us up for future multiple inheritance cases (I tried with the Tilt module, but it became too complicated due to diamond inheritance issues).

[ben-ray]

Once we have this PR merged, we could replace detailed manual plate definitions with an automatic calibration tool where:

• developer specifies dx and dy between center of wells, well cross-section(circle/square), plus an approx height above the well
• use collision detection to determine hard bottom of plate when mounted on carrier
• pipette water into the well & use cLLD to determine well geometry at a few different well volumes

i think dx, dy, liquid height, and bottom height are the only 4 geometric details that matter for most liquid handling. (plus iSWAP stuff, let's ignore that for now) if this is true, could the plate definition process be fully automated after the user specifies a minimal set of values for the plate? will the generated definition be accurate enough for use our protocols? unsure

[BioCam]

Inconsequential, but the "sinking" terminology in my mind conflicts with the "pedestal" terminology - a pedestal lifts something up above a surface, just like the pedestal lifts up the well bottoms if pedestal height > well dz + material thickness.

@fderop I see your point regarding the nomenclature. In that sense the word "pedestal" might be the misleading word:
The topmost surface of a PlateCarrierSite is its origin's z-coordinate (also according to VENUS).
If a "pedestal" (central elevation) exists, that means the plate does then "sink" into the PlateCarrierSite.
Not sure whether we should then try and find a better word for PlateCarrierSite.pedestal_z_height?

Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

I think ideally nowhere, and we just make sure that the z origin coincides with the well bottom, which I think this PR is setting us up for.

Are you suggesting we change the PLR definition of what a Well is?
In the last PR #183 we discussed whether a Well is just the empty cavity or is the empty cavity + the material that creates the cavity and found that
(1) the Well.material_z_thickness is an integral part of the definition (-> had to be considered part of the Well), and
(2) that the Well.material_x_thickness & Well.material_y_thickness are too ambiguous to be measured accurate (-> had to not be considered part of the Well).

Your message indicates that you are suggesting that we change this current PLR Well definition to only count the empty cavity as Well, and make material_z_thickness an associated attribute to Well but not a direct part of it?

I think ideally all resources with sites that potentially have a pedestal should inherit from a class where assign_child_resource applies the pedestal logic.

I think this is a very good point: so you are suggesting we add the pedestal placement logic maybe to assign_child_resource at the super class level of Resource?

[BioCam]

i think dx, dy, liquid height, and bottom height are the only 4 geometric details that matter for most liquid handling.

I don't think so. The issue with Plate was missing information. Specifically, not having information regarding the clearance below the outside of a well, i.e. dz, and the ambiguity of not having a dedicated material_z_thickness meant that until now it was not possible to use the same plate on PlateCarrierSites with and without pedestals.
It also meant that plate movements moved the plate into the wrong position on a PlateCarrierSite with a pedestal until this PR (i.e. it moved it at the z-coordinate of the PlateCarrierSite when it should, and now does, move the plate into the "sunk" position below the PlateCarrierSite z-coordinate - you guys might have noticed how the plates always require a push from the the top after being moved?).

Altogether this indicates that the growing set of attributes of plate definitions are needed.
I also think that plate definitions are maintainable while the alternative - writing automation protocols that are dependent on offsets - is not maintainable long term.

This does not mean that we shouldn't work on developing an automated plate definition tool like the one you are describing though.
I have actually already started 😅
But it is quite difficult and there are at least half a dozen implementation methods which might be able to do the job, from simple camera/computer vision-based systems to figuring out how to retrieve the z-touchoff crash-coordinate from the STAR to some fancy 3D-scanning approaches... the difficulty is to address time-constraint and what will actually work robustly.
But I would like this tool to give us the full set of plate definition attributes that we need to cover all possible use cases of the plate :)

[fderop]

Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

I think ideally nowhere, and we just make sure that the z origin coincides with the well bottom, which I think this PR is setting us up for.

Are you suggesting we change the PLR definition of what a Well is? In the last PR #183 we discussed whether a Well is just the empty cavity or is the empty cavity + the material that creates the cavity and found that (1) the Well.material_z_thickness is an integral part of the definition (-> had to be considered part of the Well), and (2) that the Well.material_x_thickness & Well.material_y_thickness are too ambiguous to be measured accurate (-> had to not be considered part of the Well).

Oh no, I thought with "command stacks" you meant as a kwarg somewhere in the commands that call Well, I think what you propose is good.

I was looking at heater-shakers earlier, and in theory a case could exist where the depth of a well is too great to fit into the "wells" on the heat block. The "wells" of the heater-shaker would thus elevate the plate independently of the "pedestal" height of the heater-shaker block. How would you implement that?

[rickwierenga]

Thank you, Camillo, for the continued work on this, and Ben and Florian for providing feedback.

Regarding pedestals rising or sinking: Camillo previously convinced me (on a call) it's easiest that carrier sites have z=0 at the top of the pedestal, if it exists, because it's not ambiguous what z=0 is in that case. Some carrier sites have complex geometries, for example in the image from the docs below you can see two lower levels and screws. We only care about the highest level below the pedestal surface because plates would rest on that. I am open to re-having this discussion if you have new arguments. I think renaming pedestal might be good, but I don't think pedestal is a bad name.

Regarding single-resource-taking-resource: I think this should be a shared base class for MFXModule and CarrierSite, and TiltModule, HeaterShaker, etc. I propose we define the pedestal height and potetially child_resource_location in that class. As we found with the Tilter, diamond inheritance is not good.

Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

For lh.aspirate and lh.dispense, this can be handled on the backend, where backends automatically add the material thickness to the well_bottom they computed from get_absolute_location.

For manual pipette movements with move_channel, I think well.get_absolute_position(..., z="b") + Coordinate(z=well.material_thickness) is most explicit, but it's not concise. How about well.get_cavity_bottom() or similar, which will add the material thickness. You could imagine get_absolute_cavity(z={"b","c","t"})

The "wells" of the heater-shaker would thus elevate the plate independently of the "pedestal" height of the heater-shaker block. How would you implement that?

I think the following "highest level below the pedestal surface", the pedestal should in that case be the bottom of heater-shaker cavities.

[fderop]

Regarding pedestals rising or sinking: Camillo previously convinced me (on a call) it's easiest that carrier sites have z=0 at the top of the pedestal, if it exists, because it's not ambiguous what z=0 is in that case. Some carrier sites have complex geometries, for example in the image from the docs below you can see two lower levels and screws. We only care about the highest level below the pedestal surface because plates would rest on that. I am open to re-having this discussion if you have new arguments.

I think this is convincing!

The "wells" of the heater-shaker would thus elevate the plate independently of the "pedestal" height of the heater-shaker block. How would you implement that?

I think the following "highest level below the pedestal surface", the pedestal should in that case be the bottom of heater-shaker cavities.

Ok, what happens when the well is shorter in depth than the "heat block well", and thus the origin of the well is lifted above the pedestal?

[BioCam]

I was looking at heater-shakers earlier, and in theory a case could exist where the depth of a well is too great to fit into the "wells" on the heat block. The "wells" of the heater-shaker would thus elevate the plate independently of the "pedestal" height of the heater-shaker block. How would you implement that?

Ok, what happens when the well is shorter in depth than the "heat block well", and thus the origin of the well is lifted above the pedestal?

@fderop, are you talking about this when talking about the "'wells' on a heat block"?

Are you familiar with the Resource subclass PlateAdapter I created in #152?

All these adapters are instances of PlateAdapter, i.e. the PlateAdapter's "hole-grid" is used to self-adjust the placement of plates onto the PlateAdapter.
There is a current caveat though: I've mentioned in the PR, PlateAdapter is missing the correction in the z-dimension due to the ongoing Plate issue (which this current PR is [hopefully] fixing).
I believe that now we have all the information to build a z-dimension correction into PlateAdapter (in addition to the existing x-y correction).

Therefore to answer your question...

Ok, what happens when the well is shorter in depth than the "heat block well", and thus the origin of the well is lifted above the pedestal?

...we can write a condition statement that checks this and correctly represents the plate sitting with its top plate on the holes?

[BioCam]

Regarding pedestals rising or sinking: Camillo previously convinced me (on a call) it's easiest that carrier sites have z=0 at the top of the pedestal, if it exists, because it's not ambiguous what z=0 is in that case. Some carrier sites have complex geometries, for example in the image from the docs below you can see two lower levels and screws. We only care about the highest level below the pedestal surface because plates would rest on that. I am open to re-having this discussion if you have new arguments. I think renaming pedestal might be good, but I don't think pedestal is a bad name.

I agree - then we leave PlateCarrierSite.pedestal_z_height and "sinking" terminology (at least for the moment).

Regarding single-resource-taking-resource: I think this should be a shared base class for MFXModule and CarrierSite, ...

Interesting... at the moment, these are direct subclasses of Resource - are you saying we should create a new Resource-subclass to place in between Resource & MFXModule/CarrierSite in this PR, something like SingleChildTakingResource?
This would give all of these a pedestal_z_height attribute.

...and TiltModule, HeaterShaker, etc. I propose we define the pedestal height and potetially child_resource_location in that class. As we found with the Tilter, diamond inheritance is not good.

I am a bit confused by the inheritance pattern:
So far I was under the impression that the mfx_plate_modules, mfx_tip_modules, heaters, shakers, tilters, ... are - physically speaking - instances of MFXModules because they share the single-child resource taking and are flexibly fixed onto a carrier and easily modifiable.
This list makes it seem to me as if they are seen as being at the same level as MFXModules in the inheritance tree?

Where should we add material_z_thickness to command stacks that go to the inside bottom of a Well?

For lh.aspirate and lh.dispense, this can be handled on the backend, where backends automatically add the material thickness to the well_bottom they computed from get_absolute_location.

For manual pipette movements with move_channel, I think well.get_absolute_position(..., z="b") + Coordinate(z=well.material_thickness) is most explicit, but it's not concise. How about well.get_cavity_bottom() or similar, which will add the material thickness. You could imagine get_absolute_cavity(z={"b","c","t"})

Excellent! 👍🏻

lh.backend (in this case STAR) is where I will then add the material_z_thickness for the aspirate and dispense functions.

• Important question though: Who would be willing to add the equivalent changes to PLR's other backends?
  This change is affecting Plate and will therefore propagate to all machines. As a result, all backends will have to update to include the material_z_thickness in their aspirate and dispense functions(?)

I also agree that manual pipette movement should be separate and be accessible using get_absolute_cavity(z={"b","c","t"}) but would add to that the ability to say get_absolute_cavity(x={"l","c","r"},y={"f","c","b"}, z={"b","c","t"}), i.e. make it the equivalent to get_absolute_location for the cavity.

The "wells" of the heater-shaker would thus elevate the plate independently of the "pedestal" height of the heater-shaker block. How would you implement that?

I think the following "highest level below the pedestal surface", the pedestal should in that case be the bottom of heater-shaker cavities.

I disagree:
As I mentioned above, this physical adapter is easily exchangeable and I would recommend digitally representing it as a PlateAdapter and beefing out PlateAdapter's handling of special child resources like the case described by @fderop here.

Furthermore, PlateCarrierSite does not have the necessary attributes to deal with this situation; e.g. it is missing the hole-grid's dx and dy. That's why I invented PlateAdapter :)

[rickwierenga]

are you saying we should create a new Resource-subclass to place in between Resource & MFXModule/CarrierSite in this PR, something like SingleChildTakingResource?

yes, in another PR, i think that would be good.

This list makes it seem to me as if they are seen as being at the same level as MFXModules in the inheritance tree?

HamiltonTiltModule was still be inheriting from MFXModule, but additionally from Tilter. Both MFXModule and Tilter inherited from Resource. If you draw this out, there is a diamond, which is difficult to initialize, so we decided Tilter takes precedence over MFXModule as a superclass for HamiltonTiltModule. This is because Tilter is a machine front end, and not all tilt modules are Hamilton/MFX. In the diamond, Tilter and MFXModule were at the same level, below Resource and above HamiltonTiltModule. But again, the MFXModule path was scrapped for convenience.

In the future, we can fix this with the intermediary class like SingleChildTakingResource that is the parent of Tilter and could replace MFXModule (MFXModule has the same code that would be in SingleChildTakingResource and at that point it would only exist for semantic reasons.) That's for a different PR :)

lh.backend (in this case STAR) is where I will then add the material_z_thickness for the aspirate and dispense functions.

Thanks! Do you want to do that in this PR?

Important question though: Who would be willing to add the equivalent changes to PLR's other backends?

For Vantage, I will do it.

For Tecan, these carriers do not have the pedestal_size_z attribute, which means the carriers cannot even be initialized. So it's really up to the next person who uses the next person who uses the EVO backend to fix it, along with adding the pedestal_size_z. If I get my hands on a Tecan again, I suppose I can be that person.

For Opentrons, it should not change anything because there is no pedestal on the Deck.

As I mentioned above, this physical adapter is easily exchangeable and I would recommend digitally representing it as a PlateAdapter and beefing out PlateAdapter's handling of special child resources like the case described by @fderop here.

For these specialized PlateAdapters, yes, strongly agree. But for PlateCarriers, the "highest level below the pedestal surface" should be the definition we use.

[BioCam]

Thanks! Do you want to do that in this PR?

Yes, I will add this today.

For Vantage, I will do it.

Awesome, thank you @rickwierenga.

For Tecan, these carriers do not have the pedestal_size_z attribute, which means the carriers cannot even be initialized.

That makes sense for the Plate-to-PlateCarrierSite relationship modelling.

But I am a bit concerned about the fact that this change will also affect all other Plate operations on all PLR-integrated machines:
We are here implementing the updated Plate definition of well_cavity_bottom_z_coordinate = plate_z_origin + well.dz + well.material_z_thickness (same goes for all other Containers, i.e. Tube, Trough and PetriDish).
This will affect everything in PLR.

Which means I don't think this is correct:

For Opentrons, it should not change anything because there is no pedestal on the Deck.

[BioCam]

@rickwierenga, I am not entirely sure where the z-coordinates are actually defined for different lld_modes:

For lld_mode=0 "aspirate from bottom of the well" it appears that firmware parameter C0AS zl is responsible for sending aspirate_pip to the correct z-coordinate?

zl is in turn defined in aspirate via STAR.py:1578:

liquid_surfaces_no_lld = [wb + (op.liquid_height or 1)
                          for wb, op in zip(well_bottoms, ops)]

But I'm not sure why 1 mm is added here?

I'm starting to think that changing the well_cavity_bottom_z_coordinate at this stage could be very cumbersome for every lld_mode.

Update:

I guess its actually pretty simple to change STAR.py:1577

  def aspirate():
    ...
    well_bottoms = [op.resource.get_absolute_location().z + op.offset.z + op.resource.material_z_thickness for op in ops]
   ...

We just have to do this for every operation (i.e. aspirate, aspirate96, dispense, dispense96)?

[rickwierenga]

But I'm not sure why 1 mm is added here?

I added that because I was just going from rck files -> observed firmware commands, and this constant was needed. I was just thinking in terms of variables at that time, not really the physical they represent. This may actually have been the material z thickness. It looks like in this PR we can finally make this sensible.

We just have to do this for every operation (i.e. aspirate, aspirate96, dispense, dispense96)?

That looks right!

I am working on fixing the tests (the plate definition I used for writing the STAR tests is now no longer usable because it is missing the material z thickness, but I think i can figure it out).

[rickwierenga]

Can you confirm that this code is working physically on your machine for aspirating?

[rickwierenga]

is movement with iswap currently broken for you @BioCam? My guess is that the hard-coded pickup_distance_from_top: float = 13.2, in LH is wrong, and again simply a constant that I needed when writing this code, that implicitly factored in the material z thickness.

[BioCam]

is movement with iswap currently broken for you @BioCam?

@rickwierenga, I don't have an iSWAP 😅

But with CO-RE grippers I am always adjusting the pickup_distance_from_top to the specific resource anyway, so I might not have noticed anything.

My guess is that the hard-coded pickup_distance_from_top: float = 13.2, in LH is wrong, and again simply a constant that I needed when writing this code, that implicitly factored in the material z thickness

There are two things that don't sound right about this:

1. This is in liquid_handler.py which means it affects all PLR liquid handlers, including Tecans and the OT-2, is that correct?
   If yes, I don't think these offsets based on one machine should automatically be applied to all machines?

2. Do you remember whether you got these 13.2 (mm or dmm?) from a parsed definition of a specific plate?
   We can then check the plate.

Either way, anything between 1.32 - 13.2 mm pick pickup_distance_from_top is a reasonable default value for most plates.
The default value should just be small enough to ensure the grippers aren't sent crashing into the PlateCarrierSite (e.g. if the Plate.get_size_z()==10 (mm) and the pickup_distance_from_top==13.2 mm).

Most "microtiter plates" are between 13-20 mm tall, and any "deepwell plate" would be okay.
I wonder whether the 13.2 mm is actually the maximal distance that a CO-RE gripper can tolerate: if CO-RE grippers are asked to grip too low, the channels instead of the grippers will squeeze the plate because the grippers have a smaller cross-section than the channels lol

[rickwierenga]

The heights of plates have not changed as a result of these changes. But, now that plates sink into the plate carrier sites (with skirted plates), the top z location is (correctly) lower than what we previously thought. Previously, the height of the plate was (wrongly) the z-bottom of wells + total height of plate.

In STAR_tests.py, we use a Cor_96_wellplate_360ul_Fb plate with a PLT_CAR_L5AC_A00 carrier. The sinking depth is 3.03. I also started using Cor_96_wellplate_360ul_Fb instead of Cos_96_EZWash for STAR_tests.py. Cos_96_EZWash was the VENUS-imported plate definition we used in the Esvelt lab, and what I used for developing most of PLR tests. The reason for this change is Cos_96_EZWash does not have material_z_thickness. Cor_96_wellplate_360ul_Fb's height is 14.2mm, 0.3mm lower than Cos_96_EZWash (14.5). Together, these changes mean the height of the plate is 3.03+0.3 = 3.33 lower than before.

This has important implications for resource movements, where the pick up z location is partially defined by the distance from the top of the resource (pickup_distance_from_top). Previously, the top here was actually too high, as explained above. So in order to fix this, we need to decrease pickup_distance_from_top by 3.33 in these tests. I did this in 9ac2e62.

user action required: In the general case, the pickup_distance_from_top for a plate movement to/from a carrier needs to be decreased by the z_sinking_depth as computed in PlateCarrierSite.assign_child_resource.

I already made this change in LiquidHandler.py for the default parameter value. It obviously still depends on a person's setup, and people will likely want to use a custom value, but from what I have seen the carrier and plate used in the tests is pretty typical, so hopefully we approximate the same default behavior as before.

[rickwierenga]

Another problem was with modifying the location in PlateCarrierSite.assign_child_resource. When deserializing, the location passed to this method is already correct ("sinked") and sinking again is not necessary. It is impossible to generally determine whether sinking has been applied.

As with other resources, I made it so that location is an optional, and that the to-be-parent-resource can choose the best child location if None is passed. When a specific location is passed, that location is used (eg when deserializing). I made this change for CarrierSite and PlateCarrierSite. To allow PlateCarrierSite to use the super class location modification (for rotation), I introduced a new private function for those classes named _get_child_location.

(I also fixed two other tests)

[rickwierenga]

to answer your questions:

This is in liquid_handler.py which means it affects all PLR liquid handlers, including Tecans and the OT-2, is that correct?

Yes, it would be, but:

• OT2 doens't have grippers
• pickup_distance_from_top is not implemented for EVO yet

Do you remember whether you got these 13.2 (mm or dmm?) from a parsed definition of a specific plate?

From the odd Cos_96_EZWash. By the same principle: trying to find a function rck file info -> number observed in trace file.

[rickwierenga]

awaiting your grace before merging @BioCam

[BioCam]

Thank you for reviewing the changes and fixing the tests, @rickwierenga!

All good to merge from my end.

[rickwierenga]

As evidenced by the CHANGELOG, a massive & phenomenal PR. Thanks a lot!!

I initially made the decision when looking at VENUS and firmware commands without really considering physical reality, which led to inaccurate and non-understandable code because I imported the VENUS mindset. This is now fixed, thanks to your huge effort. PLR is probably the world's first interface to lab automation that correctly places skirted plates on pedestals automatically. 🎉

[BioCam]

Thank you @rickwierenga!

The issue fixed here and the previous 2 associated PRs (of Plate definitions and correct Plate placements) has in the end taken about 6 months to fix, including periods of placing it behind main/other work priorities.
This has been an incredible team effort, and I am very excited about the new potential of PLR.
(I definitely think this is one of those classic issues that everyone ignores because the functionality of placing a Plate correctly is just so simple it's assumed to be self-explanatory - which we show here, it isn't -, but when fixed it actually makes processes work 😅 )

Tagging some specific people to make them aware that these changes have now been deployed: @fderop, @ben-ray, @jkhales.

@fderop: The issue we previously discussed of not being able to use the same Plate in two different locations should now be fixed. Please let us know if you still encounter issues with it.