Looking to identify and get profiles for these modules in PLR.
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:
- a âbase carrierâ
(i.e. a metal plate with holes in it at pre-defined locations) - 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 resource
s, 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 PlateHolder
s 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. thePlateHolder
itself. TheMFX_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:
- using capacitive detection (use for anything conductive, e.g. your MFX PlateHolders):
- 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.
Thank you for such a detailed response. I will try to implement my modules in the coming days.
Question
- 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:
-
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
-
Google, find a reseller who explains the product in more detail than Hamilton does (e.g. ebay)
-
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). -
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)
-
Peer-validation:
Generate a PLR script that measures out a specificresource
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 theirresources
â 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.
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.