Mixing during dispense

I’m looking to implement pipet mixing during my dispense cycles, though it would appear that this is not an allowable parameter for the standard LiquidHandler.dispense frontend method:


It is available via the STAR backend:


But I have to admit some naïveté when it comes to how one would actually use this backend method in practice. Does anyone have en example for how they have implemented mixing in PLR dispense steps? I have to imagine this is a relatively common need.

Any arguments taken by STAR that are not part of the LH method signature/definition can still be passed to LH, and by default these will just be passed onto the backend using the backend_kwargs. (This behavior is adjustable using Strictness.)

Thanks Rick, this makes sense, I think my original concern came because I was getting an error not consistent with the strictness check and was thus quite confused. Must have been another bug on my part.

With that in mind, when I try to run mix parameters with my dispense in the simulator, I see the warning that I assume comes from the default strictness check setting (WARN), but the method continues. Of course, I can’t see if it’s “mixing” as it’s in the simulator, but I assume it is doing so.

However, when I translate these to try and run on the robot itself, it is as if it does not even see the arguments in the method call. There is no mixing happening while I watch the robot, and there is no error or warning about the backend args like there is in the simulator. See below for code:

# defining liquid handle cycle function
async def dilution_cycle(column, cycle):
    await lh.pick_up_tips(growthtiprack[column])
    await lh.aspirate(culture_plate[column], vols=dilute_vollist)
    await lh.dispense(growth_plate[column], vols=dilute_vollist, mix_volume=3000, mix_cycles=10)
    await lh.aspirate(growth_plate[column], vols=dilute_vollist)
    if cycle % 2 == 0:
        await lh.dispense(read_plate[column], vols=read_vollist)
        await lh.dispense(bleach_plate[column], vols=75)
        await lh.dispense(bleach_plate[column], vols=dilute_vollist)
# call function across a number of columns of a plate (cycles)
for c in cycles:
    columnname = "A"+str(c+1)+":"+"H"+str(c+1)
    print(columnname, "+", c)
    await dilution_cycle(columnname, c)
    await lh.drop_tips(growthtiprack[columnname])

When I run this is it proceeds as if the , mix_volume=3000, mix_cycles=4 args are not present.

For some reason, mixing only works when we call lh.aspirate, not on dispense. So to mix, we just add an aspirate function with volume zero. Here is the correct function call:

await self.lh.aspirate(
    [0] * len(growth_plate[column]),
    homogenization_volume = 3000, #in units of 0.1ul
    homogenization_cycles = 10,
    homogenization_speed = 2600   #in units of 0.1ul

Here we use homogenization_volume, homogenization_cycles, and homogenization_speed because they are exactly the parameter names as outlined in the STAR.py backend. mix_volume and mix_cycles might not work.

Thanks Ben, at least I’m not the only one stumped by no mixing with dispense. I wonder if using the “homogenization” verbiage in the dispense call might work, rather than using “mix” as it says in the docs. Perhaps you’ve tried that?

I’ll give this a shot today when I can get back to it.


Can confirm that using the aspirate with vols=0 worked perfectly for me, thanks @ben. As probably expected, trying to plug in homogenization instead of mix with the dispense method did nothing.

Hi all, I’m back with an update on this question. If you’d rather I move it to a new thread, let me know.

In short, this worked quite well for using the span-8, but I wanted to try to do essentially the same thing with the CO-RE 96 head. I made some corresponding modifications to the commands, and am testing now. However, I get the timeout error pasted below.

One detail that might be relevant: You’ll notice the timeout error occurs on the third plate (of four). Before I noticed that the mixing speed arg for the aspirate_plate command (speed_of_homogenization) is different than for aspirate (homogenization_speed), I had kept the span-8 verbiage. In that case, the timeout error occurred on the first of the four plates, rather than the third. Notably the default mixing speed in that case was used, which is much slower than the requested 400 uL/s. In both cases, it occurs at the same point, which is just after finishing the “error” plate and before proceeding to the next plate.

Function definition and error trace

async def mix_plates(vol):
    await lh.dispense_plate(lh.get_resource('plate1'), volume=vol)
    await lh.aspirate_plate(lh.get_resource('plate1'), volume=0, 
                      homogenization_volume = 8000, homogenization_cycles = 4, 
                      speed_of_homogenization = 4000)
    await lh.aspirate_plate(lh.get_resource('plate2'), volume=0, 
                      homogenization_volume = 8000, homogenization_cycles = 4, 
                      speed_of_homogenization = 4000)
    await lh.aspirate_plate(lh.get_resource('plate3'), volume=0, 
                      homogenization_volume = 8000, homogenization_cycles = 4, 
                      speed_of_homogenization = 4000)
    await lh.aspirate_plate(lh.get_resource('plate4'), volume=0, 
                      homogenization_volume = 8000, homogenization_cycles = 4, 
                      speed_of_homogenization = 4000)
    await lh.drop_tips96(lh.get_resource('tips_01'))

Error trace

TimeoutError                              Traceback (most recent call last)
Cell In[45], line 2
      1 ## Run it
----> 2 await cycles(num_cycles)

Cell In[42], line 18, in cycles(cycles)
     17     vol = 0
---> 18     await mix_plates(vol)

Cell In[40], line 46, in mix_plates(vol)
     40 await lh.aspirate_plate(lh.get_resource('plate1'), volume=0, 
     41                   homogenization_volume = 8000, homogenization_cycles = 4, 
     42                   speed_of_homogenization = 4000)
     43 await lh.aspirate_plate(lh.get_resource('plate2'), volume=0, 
     44                   homogenization_volume = 8000, homogenization_cycles = 4, 
     45                   speed_of_homogenization = 4000)
---> 46 await lh.aspirate_plate(lh.get_resource('plate3'), volume=0, 
     47                   homogenization_volume = 8000, homogenization_cycles = 4, 
     48                   speed_of_homogenization = 4000)
     49 await lh.aspirate_plate(lh.get_resource('plate4'), volume=0, 
     50                   homogenization_volume = 8000, homogenization_cycles = 4, 
     51                   speed_of_homogenization = 4000)
     52 await lh.drop_tips96(lh.get_resource('tips_01'))

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/liquid_handler.py:1154, in LiquidHandler.aspirate_plate(self, plate, volume, flow_rate, end_delay, **backend_kwargs)
   1143 if plate.num_items_x == 12 and plate.num_items_y == 8:
   1144   aspiration_plate = AspirationPlate(
   1145     resource=plate,
   1146     volume=volume,
   1152     liquids=liquids,
   1153   )
-> 1154   await self.backend.aspirate96(aspiration=aspiration_plate, **backend_kwargs)
   1155   self._trigger_callback(
   1156     "aspirate_plate",
   1157     liquid_handler=self,
   1160     **backend_kwargs,
   1161   )
   1162 else:

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/STAR.py:61, in need_iswap_parked.<locals>.wrapper(self, *args, **kwargs)
     58 if self.iswap_installed and not self.iswap_parked:
     59   await self.park_iswap()
---> 61 result = await method(self, *args, **kwargs) # pylint: disable=not-callable
     63 return result

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/STAR.py:2058, in STAR.aspirate96(self, aspiration, blow_out_air_volume, use_lld, liquid_height, air_transport_retract_dist, aspiration_type, minimum_traverse_height_at_beginning_of_a_command, minimal_end_height, lld_search_height, maximum_immersion_depth, tube_2nd_section_height_measured_from_zm, tube_2nd_section_ratio, immersion_depth, immersion_depth_direction, liquid_surface_sink_distance_at_the_end_of_aspiration, transport_air_volume, pre_wetting_volume, gamma_lld_sensitivity, swap_speed, settling_time, homogenization_volume, homogenization_cycles, homogenization_position_from_liquid_surface, surface_following_distance_during_homogenization, speed_of_homogenization, limit_curve_index)
   2049 if blow_out_air_volume is not None and blow_out_air_volume > 0:
   2050   await self.aspirate_core_96(
   2051     x_position=int(position.x * 10),
   2052     y_positions=int(position.y * 10),
   2055     aspiration_volumes=int(blow_out_air_volume * 10)
   2056   )
-> 2058 return await self.aspirate_core_96(
   2059   x_position=int(position.x * 10),
   2060   x_direction=0,
   2061   y_positions=int(position.y * 10),
   2062   aspiration_type=aspiration_type,
   2064   minimum_traverse_height_at_beginning_of_a_command=
   2065    minimum_traverse_height_at_beginning_of_a_command,
   2066   minimal_end_height=minimal_end_height,
   2067   lld_search_height=lld_search_height,
   2068   liquid_surface_at_function_without_lld=liquid_surface_at_function_without_lld,
   2069   pull_out_distance_to_take_transport_air_in_function_without_lld=
   2070    pull_out_distance_to_take_transport_air_in_function_without_lld,
   2071   maximum_immersion_depth=maximum_immersion_depth,
   2072   tube_2nd_section_height_measured_from_zm=tube_2nd_section_height_measured_from_zm,
   2073   tube_2nd_section_ratio=tube_2nd_section_ratio,
   2074   immersion_depth=immersion_depth,
   2075   immersion_depth_direction=immersion_depth_direction,
   2076   liquid_surface_sink_distance_at_the_end_of_aspiration=
   2077    liquid_surface_sink_distance_at_the_end_of_aspiration,
   2078   aspiration_volumes=aspiration_volumes,
   2079   aspiration_speed=flow_rate,
   2080   transport_air_volume=transport_air_volume,
   2081   blow_out_air_volume=0,
   2082   pre_wetting_volume=pre_wetting_volume,
   2083   lld_mode=int(use_lld),
   2084   gamma_lld_sensitivity=gamma_lld_sensitivity,
   2085   swap_speed=swap_speed,
   2086   settling_time=settling_time,
   2087   homogenization_volume=homogenization_volume,
   2088   homogenization_cycles=homogenization_cycles,
   2089   homogenization_position_from_liquid_surface=
   2090    homogenization_position_from_liquid_surface,
   2091   surface_following_distance_during_homogenization=
   2092    surface_following_distance_during_homogenization,
   2093   speed_of_homogenization=speed_of_homogenization,
   2094   channel_pattern=channel_pattern,
   2095   limit_curve_index=limit_curve_index,
   2096   tadm_algorithm=False,
   2097   recording_mode=0,
   2098 )

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/STAR.py:4895, in STAR.aspirate_core_96(self, aspiration_type, x_position, x_direction, y_positions, minimum_traverse_height_at_beginning_of_a_command, minimal_end_height, lld_search_height, liquid_surface_at_function_without_lld, pull_out_distance_to_take_transport_air_in_function_without_lld, maximum_immersion_depth, tube_2nd_section_height_measured_from_zm, tube_2nd_section_ratio, immersion_depth, immersion_depth_direction, liquid_surface_sink_distance_at_the_end_of_aspiration, aspiration_volumes, aspiration_speed, transport_air_volume, blow_out_air_volume, pre_wetting_volume, lld_mode, gamma_lld_sensitivity, swap_speed, settling_time, homogenization_volume, homogenization_cycles, homogenization_position_from_liquid_surface, surface_following_distance_during_homogenization, speed_of_homogenization, channel_pattern, limit_curve_index, tadm_algorithm, recording_mode)
   4892 channel_pattern_bin_str = reversed(["1" if x else "0" for x in channel_pattern])
   4893 channel_pattern_hex = hex(int("".join(channel_pattern_bin_str), 2)).upper()[2:]
-> 4895 return await self.send_command(
   4896   module="C0",
   4897   command="EA",
   4898   aa=aspiration_type,
   4899   xs=f"{x_position:05}",
   4900   xd=x_direction,
   4901   yh=f"{y_positions:04}",
   4902   zh=f"{minimum_traverse_height_at_beginning_of_a_command:04}",
   4903   ze=f"{minimal_end_height:04}",
   4904   lz=f"{lld_search_height:04}",
   4905   zt=f"{liquid_surface_at_function_without_lld:04}",
   4906   pp=f"{pull_out_distance_to_take_transport_air_in_function_without_lld:04}",
   4907   zm=f"{maximum_immersion_depth:04}",
   4908   zv=f"{tube_2nd_section_height_measured_from_zm:04}",
   4909   zq=f"{tube_2nd_section_ratio:05}",
   4910   iw=f"{immersion_depth:03}",
   4911   ix=immersion_depth_direction,
   4912   fh=f"{liquid_surface_sink_distance_at_the_end_of_aspiration:03}",
   4913   af=f"{aspiration_volumes:05}",
   4914   ag=f"{aspiration_speed:04}",
   4915   vt=f"{transport_air_volume:03}",
   4916   bv=f"{blow_out_air_volume:05}",
   4917   wv=f"{pre_wetting_volume:05}",
   4918   cm=lld_mode,
   4919   cs=gamma_lld_sensitivity,
   4920   bs=f"{swap_speed:04}",
   4921   wh=f"{settling_time:02}",
   4922   hv=f"{homogenization_volume:05}",
   4923   hc=f"{homogenization_cycles:02}",
   4924   hp=f"{homogenization_position_from_liquid_surface:03}",
   4925   mj=f"{surface_following_distance_during_homogenization:03}",
   4926   hs=f"{speed_of_homogenization:04}",
   4927   cw=channel_pattern_hex,
   4928   cr=f"{limit_curve_index:03}",
   4929   cj=tadm_algorithm,
   4930   cx=recording_mode,
   4931 )

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/STAR.py:1172, in STAR.send_command(self, module, command, tip_pattern, write_timeout, read_timeout, wait, fmt, **kwargs)
   1158 async def send_command(
   1159   self,
   1160   module: str,
   1167   **kwargs
   1168 ):
   1169   """ Send a command to the machine. Parse the response if `fmt != ""`, else return the raw
   1170   response. """
-> 1172   resp = await super().send_command(
   1173     module=module,
   1174     command=command,
   1175     tip_pattern=tip_pattern,
   1176     write_timeout=write_timeout,
   1177     read_timeout=read_timeout,
   1178     wait=wait,
   1179     **kwargs
   1180   )
   1181   if fmt != "":
   1182     parsed = parse_star_fw_string(resp, fmt)

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/base.py:191, in HamiltonLiquidHandler.send_command(self, module, command, tip_pattern, write_timeout, read_timeout, wait, **kwargs)
    170 """ Send a firmware command to the Hamilton machine.
    172 Args:
    186   A dictionary containing the parsed response, or None if no response was read within `timeout`.
    187 """
    189 cmd, id_ = self._assemble_command(module=module, command=command, tip_pattern=tip_pattern,
    190   **kwargs)
--> 191 return await self._write_and_read_command(id_=id_, cmd=cmd, write_timeout=write_timeout,
    192                 read_timeout=read_timeout, wait=wait)

File ~/Documents/Lab/PyLabRobot/pylabrobot/pylabrobot/liquid_handling/backends/hamilton/base.py:215, in HamiltonLiquidHandler._write_and_read_command(self, id_, cmd, write_timeout, read_timeout, wait)
    213 fut = loop.create_future()
    214 self._start_reading(id_, loop, fut, cmd, read_timeout)
--> 215 result = await fut
    216 return cast(dict, result)

TimeoutError: Timeout while waiting for response to command C0EAid0048aa0xs02530xd0yh3380zh2450ze2450lz1999zt1881pp0100zm1269zv0032zq06180iw000ix0fh000af00000ag2500vt050bv00000wv00050cm0cs1bs0020wh10hv08000hc04hp000mj000hs4000cwFFFFFFFFFFFFFFFFFFFFFFFFcr000cj0cx0.

Further testing:

If I lower homogenization cycles from 4 to 2, it completes without error.

It seems like there is some maximum time period in which the mix_plates function is allowed to complete, and if either the cycles or speed of mixing is too high, it times out. Ideally this parameter is editable so I can allow this function to run longer than whatever the default is?

You can set a custom read_timeout value in STAR.py, particularly the aspirate_pip command. Check out line 3725 in STAR.py, see how it is hardcoded for a read timeout of 60 seconds? If your aspirate function with mixing takes longer than 60 seconds to execute, increasing this number will solve your problem. I have this set at 300 seconds for multi-column mix commands


Awesome, thank you @ben!

1 Like