Liquid Classes

Liquid classes are global definitions that store all relevant background parameters, such as flow rates and volume corrections, for one pipetting cycle, i.e. for one aspiration and the subsequent dispense(s).

Use predefined liquid classes

Vendors usually provide predefined liquid classes for common liquid types. Liquid classes are only compatible their vendor. To get an overview, which liquid classes are available out of the box for your vendor, use:

from unitelabs.labware.hamilton import LiquidClass

print(LiquidClass)
# StandardVolume_Water_DispenseJet_Empty
# StandardVolume_Water_DispenseJet_Part
# StandardVolume_Water_DispenseSurface_Empty
# StandardVolume_Water_DispenseSurface_Part
# ...

liquid_class = LiquidClass.StandardVolume_Water_DispenseJet_Empty()
print(liquid_class)
# StandardVolume_Water_DispenseJet_Empty [Water (100%)]
#   aspirate_flow_rate: 100
#   dispense_flow_rate: 180
#   ...

Understand liquid class parameters

Flow Rate

Liquid flow rate in μL/s that correspond to plunger speed for aspirate and dispense steps. The optimum setting for flow rate allows the liquid to enter or leave the tip as fast as possible while still allowing for consistent volumes to be transferred. The flow rate is heavily dependent on liquid properties.

Aspirate Dispense

Mix Flow Rate

Liquid flow rates in μL/s, corresponding to plunger speed for mixing.

Aspirate Dispense

Air Transport Volume

Volume of air in μL that is aspirated at the end of the aspiration and dispense step and is automatically dispensed again as an extra volume at the beginning of the dispense step. This extra air volume helps prevent droplet formation and dripping.
Keep in mind that using surface dispense mode plus air transport volume could cause bubbles to form. Do not use an excessive amount of volume for the air transport.

Aspirate Dispense

Blowout Volume

Volume of air in μL that is aspirated first during the aspiration step. If dispensing in empty tip mode, part or all of the blowout volume of air is dispensed.

Aspirate Dispense

Swap Speed

Speed in mm/s at which the pipette head is moved out of the liquid after aspiration and dispense.
After aspiration and dispense, the tip speed must be carefully controlled to prevent droplet formation for various liquid types.

Aspirate Dispense

Settling Time

Time in seconds that the pipette head remains in the liquid after the aspiration and dispense step before moving out of the liquid. Some liquids take longer to settle into the tip than others.
If a liquid that requires a long settling time is programmed to use a short settling time, then an insufficient amount might be aspirated or dispensed.

Aspirate Dispense

Over-Aspirate Volume

After aspirating the required volume, an additional volume is aspirated and dispensed again immediately.
The over-aspirate volume works as a pre-conditioning or pre-wetting of the tip and can help minimize any capillary effect.

Aspirate Dispense

Clot Retract Height

A parameter for clot detection that determines how high the pipette head is allowed to move out of the liquid while there is still a liquid detection signal after aspiration. It is measured from the liquid surface upwards. If this distance is exceeded, an error message is generated. Only used to help detect clots after aspiration, and doesn’t affect liquid transfers.

Aspirate Dispense

Stop Flow Rate

Dispense flow rate in μL/s in at which the dispense step terminates abruptly.

Aspirate Dispense

Stop Back Volume

Volume in μL which is aspirated again immediately after the dispense. This volume is aspirated as quickly as possible. The stop back volume helps prevent droplets after dispense in jet part volume mode by acting as an air transport volume in between transfers.

Aspirate Dispense

Correction Curve

While the parameters help determine the precision of the liquid transfer, the liquid class correction curve affects the trueness. The correction curve makes sure that the liquid is pipetted correctly across a range of volumes. The correction curve is defined by mapping target to corrected values. The target value is the amount of liquid that actually needs to be transferred. The corrected value is an adjusted volume to control the plunger, ensuring that the target amount is hit.

Aspirate Dispense

Create a liquid class

The dataclass of a liquid class looks like this:

import dataclasses

from unitelabs.labware import Ingredient, Liquid, Mixture
from unitelabs.labware.hamilton import DispenseMode, HamiltonLiquidClass, StandardTip
from unitelabs.labware.math import Decimal


@dataclasses.dataclass
class StandardVolume_Water_DispenseJet_Empty(HamiltonLiquidClass):
    uid: int = 366
    version: str = "1.1"
    liquid: Mixture = dataclasses.field(
        default_factory=lambda: Mixture([Ingredient(Liquid.WATER, 1)])
    )
    tip: type[HamiltonTip] = StandardTip

    aspirate_flow_rate: Decimal = Decimal(default="100")
    aspirate_mix_flow_rate: Decimal = Decimal(default="100")
    aspirate_transport_air_volume: Decimal = Decimal(default="5")
    aspirate_blowout_air_volume: Decimal = Decimal(default="30")
    aspirate_swap_speed: Decimal = Decimal(default="2")
    aspirate_settling_time: Decimal = Decimal(default="1")
    aspirate_over_aspirate_volume: Decimal = Decimal(default="0")
    aspirate_clot_retract_height: Decimal = Decimal(default="0")
    aspirate_lld_sensitivity: int = 4
    aspirate_lld_max_height_diff: Decimal = Decimal(default="0")

    dispense_mode: int = DispenseMode.JET_EMPTY
    dispense_flow_rate: Decimal = Decimal(default="180")
    dispense_mix_flow_rate: Decimal = Decimal(default="1")
    dispense_transport_air_volume: Decimal = Decimal(default="5")
    dispense_blowout_air_volume: Decimal = Decimal(default="30")
    dispense_swap_speed: Decimal = Decimal(default="1")
    dispense_settling_time: Decimal = Decimal(default="0")
    dispense_stop_flow_rate: Decimal = Decimal(default="100")
    dispense_stop_back_volume: Decimal = Decimal(default="0")
    dispense_lld_sensitivity: int = 4

    curve: dict[float, float] = dataclasses.field(
        default_factory=lambda: {
            0.0: 0.0,
            20.0: 23.2,
            50.0: 55.1,
            100.0: 107.2,
            200.0: 211.0,
            300.0: 313.5,
        }
    )
    is_validated: bool = True
    devices: list[str] = dataclasses.field(default_factory=lambda: ["1"])