Starlet Carrier Module Classifications

[linx5o]

Looking to identify and get profiles for these modules in PLR.

[CamilloMoschner]

Let’s do this

Task: generate PLR definition for @linx5o’s unique MFX carrier configuration.

---

Background

Hamilton’s MFX Carrier System consists of 2 component groups:

1. a “base carrier”
   (i.e. a metal plate with holes in it at pre-defined locations)
2. a repository of “MFX Modules”, i.e. resource/labware holders that can be screwed onto the “base carrier” where the holes are
   (I could never get an answer how many official Hamilton “MFX Modules” exist; Hamilton doesn’t have a catalogue that would help customers purchase from them; I estimate up to 40 exist; assuming 5 module positions on a base carrier there are 40**5 possible configurations, not including self-made modules… very clever way to enable customization)

The good thing: there are only 4 Hamilton MFX “base carriers” and you seem to only have 1 of them, which is (currently) defined in PLR as MFX_CAR_L5_base() (we’re aiming to update the naming in the next 2 months).

This means we just have to figure out how to define your “MFX Modules”.
“MFX Modules” are modelled in PLR as instances of PlateHolder().
PlateHolders are simply cuboids with a child_location attribute, i.e. the location at which a plate could be placed relative to the cuboids front-left-bottom / origin.

(this is a simple but highly effective definition that can be applied to “MFX Modules” but also a range of other resources, e.g. plate readers, microscopes, incubated shakers, … anything that takes a plate at a pre-defined location).

You can find the pre-made definitions for already integrated “MFX Modules” here: pylabrobot/pylabrobot/resources/hamilton/mfx_modules.py at main · PyLabRobot/pylabrobot · GitHub
&
Hamilton STAR “ML_STAR” — PyLabRobot documentation

Visually speaking:

---

Your modules

You have highlighted 3 different PlateHolders in your images which we’ll have to generate definitions for individually:

Note:

• Since you are placing them on top of MFX_CAR_L5_base() you are not interested in measuring the lowest-to-highest position of the final carrier.
  Instead we just want to measure the part that can easily be removed by (un)screwing it, i.e. the PlateHolder itself. The MFX_CAR_L5_base() is 18.2 mm tall. We can therefore just subtract that value from your measurements.

Example for PlateHolder / “MFX Module” #2

Could be defined as…

def Hamilton_MFX_plateholder_flat_short(name: str) -> PlateHolder:
  """
  Hamilton cat. no.: ?
  """
  return PlateHolder(
    name=name,
    size_x=135.0,
    size_y=94.0,
    size_z=82.4 - 18.2,
    child_location=Coordinate(4.0, 3.5, 82.4-18.2-4), # TODO: measure top surface height?
    model=Hamilton_MFX_plateholder_flat_short.__name__,
    pedestal_size_z=0,
  )

To now combinatorially generate your specific MFX carrier you can instantiate its definition (at runtime or in a separate .py file from which you import at runtime) like this …

mfx_module_labelled_2 = Hamilton_MFX_plateholder_flat_short(name="hamilton_mfx_plateholder_flat_short")

mfx_carrier_1 = MFX_CAR_L5_base(
  name="mfx_carrier_1",
  modules={
      3: ?,
      2: <Hamilton_MFX_plateholder_flat_tall>, # TODO: generate definition & instance
      1: <Hamilton_MFX_plateholder_flat_tall>,
      0: mfx_module_labelled_2 ,
  }
)

These are not the final definitions because I don’t have these “MFX Modules” and the pictures you shared don’t have all the required measurements marked yet.
Instead I hope to showcase in these definitions the bigger picture which helps measure the needed dimensions correctly.

This definition system requires one to precisely measure the relative positions of different resources.
I don’t know how you made your measurements.
But in PLR I developed 2 STAR methods that allow you to use the liquid handling machine itself to take measurements for you:

1. using capacitive detection (use for anything conductive, e.g. your MFX PlateHolders):
2. using force detection (use for anything plastic/non-conductive, e.g. plates, tubes)
   See: Z-probing — PyLabRobot documentation

You now have to use the same principles as above to measure the PlateHolder dimension for #1, and you can use the exact same principles for measuring ResourceHolder #3 (I believe this is a Nested Tip Rack [NTR]-holding module, i.e. use the ResourceHolder class instead of the PlateHolder class for its definition (this removes the need to define a pedestal_size_z attribute).

There is a lot going on, please don’t hesitate to ask questions.

Once new definitions have been verified we need to add them to the GitHub repo via a pull request.
This gives others the opportunity to peer-review and verify your definition in other labs, accelerating everyone’s development & real-world verification processes.
To enable others to use these definitions each definition function must contain the manufacturer catalogue number in its docstring.

[linx5o]

Thank you for such a detailed response. I will try to implement my modules in the coming days.

Question

1. How can we find the catalog number? (No past info on the machine. No receipt. Visual inspections show no tags.)

[CamilloMoschner]

@linx5o

1. How can we find the catalog number? (No past info on the machine. No receipt. Visual inspections show no tags.)

That is a good question. I have come up with a series of approaches to “triangulate” the true Hamilton catalogue number:

1. Check whether something similar can be found in the Hamilton materials shared by Eric Sindelar (senior Hamilton employee) on the labautomation.io forum. Specifically, even though Hamilton doesn’t provide a catalogue online with images and explanations, Eric shared a PDF titled VENUS four Operators Manual.pdf.
   It contains an incomplete list of Hamilton-sold materials.
   This has been shared by Hamilton directly
   

   

2. Google, find a reseller who explains the product in more detail than Hamilton does (e.g. ebay)

3. Ask a Hamilton employee whether they can just tell you what the resource in question’s catalogue number is (and whether they want money for that information).

4. For “MFX Modules”, Hamilton created a separate executable file called LabwareAssistant3D.exe that allows clicking and dropping pictures of “MFX Modules” onto a carrier model. Thereby this .exe file connects pictures of the modules to their catalogue number.
   Again, this has been freely shared by Hamilton via the labautomation.io forum (so in theory anyone can access it… if they know how to search for it )
   

   

5. Peer-validation:
   Generate a PLR script that measures out a specific resource you are investigating using the PLR-unique z-probing features (and a y-probing feature I currently have in a PR)
   → share script with someone who knows the catalogue number of their resources
   → if all parties get the same results from their scripts (inside tolerances to account for e.g. machine calibration differences, sensor variations, …) everyone knows what we’re working with.

---

Having a look at your “MFX Module” my first impressions are:

#1

…is kind of ambiguous:
it is a flat PlateHolder that is tall, i.e. a MicroTubePlate (aka MTP - ill-defined jargon, roughly translates to plates with size_z < 20mm), can be placed on top of it but a DeepWellPlate (aka DWP - ill-defined jargon, roughly translates to plates with size_z > 20mm) cannot be placed on it (to be clear, a tall plate could still be placed there but the plate would then reach into what I call the “danger volume” inside the Hamilton STAR(let), i.e. z-height > 145 mm above the deck surface → long tips can now crash into it during lateral/traverse movement.
→ there are a hole array of modules this could be
→ the LabwareAssistant3D executable shows an odd catalogue number (looks like an old indexing system?), but the Venus four Operators Manual shows something different:

#2

This one looks to me like MFX_DWP_rackbased_module (cat. no.: 188229), i.e. a PlateHolder I integrated into PLR last year:

…but I don’t understand the z measurement in your image (is 82.4 the top surface height or the height of the little ‘walls’ around the top surface?)

#3

Hamilton_MFX_resourceholder_NTR → cat. no.: 191425 ?
Note: Because this resourceholder is so idiosyncratic we have high confidence in what it is. As a result we can use Labware Assistant 3D to generate a “ground” truth for it (which I would highly recommend you verify before use though), i.e. we use the available Hamilton software to identify where the child_location is believed to be.

---

I hope this shows the fun detective work we have to go through to make PLR as powerful as it is
(not just to control machines but to navigate the automation maze)

I also hope this shows why it is so important that PLR users contribute new definitions to the PLR Resource Library (/ GitHub repo) → we’re all struggling with the same issues, but the open-source nature of PLR can tap into everyone who solved their sourcing problem to share what they found & make all of us more efficient

I should also mention that I’ve experienced that all these approaches can fail and a Hamilton sales representative sold us a completely different catalogue number that I couldn’t find anywhere else.
My best guess is that there are location-based dependencies on what they can sell where.

[linx5o]

For #2 it was measured to the pedestal, not including the lips. I will be making more detailed and precise measurements soon. I think the dimensions line up with the one on PLR.