pylabrobot.liquid_handling.backends.hamilton.STAR_backend.STAR.probe_liquid_heights#

async STAR.probe_liquid_heights(containers: List[Container], use_channels: List[int] | None = None, resource_offsets: List[Coordinate] | None = None, lld_mode: LLDMode | List[LLDMode] | None = None, search_speed: float = 10.0, n_replicates: int = 1, min_traverse_height_at_beginning_of_command: float | None = None, min_traverse_height_during_command: float | None = None, z_position_at_end_of_command: float | None = None, x_grouping_tolerance: float | None = None, move_to_z_safety_after: bool | None = None) → List[float]#

Probe liquid surface heights in containers using liquid level detection.

Performs capacitive or pressure-based liquid level detection (LLD) by moving channels to container positions and sensing the liquid surface. Heights are measured from the bottom of each container’s cavity.

Uses plan_batches for X/Y partitioning with per-batch container spread (respecting no-go zones), then execute_batched to iterate batches with Z safety.

Parameters:

  • containers (List[Container]) – List of Container objects to probe, one per channel.

  • use_channels (List[int] | None) – Channel indices to use for probing (0-indexed).

  • resource_offsets (List[Coordinate] | None) – Optional XYZ offsets from container centers. When not provided, plan_batches auto-spreads channels targeting the same container.

  • lld_mode (LLDMode | List[LLDMode] | None) – Detection mode. Either a single LLDMode applied to all containers (deprecated, removed in v1b1) or a list of LLDMode``s (one per container) allowing mixed GAMMA/PRESSURE within one call. ``None (default) applies GAMMA to all containers.

  • search_speed (float) – Z-axis search speed in mm/s. Default 10.0 mm/s.

  • n_replicates (int) – Number of measurements per channel. Default 1.

  • min_traverse_height_at_beginning_of_command (float | None) – Absolute Z height (mm) to move involved channels to before the first batch. Must clear all deck obstacles since channels travel laterally at this height. None (default) uses full Z safety.

  • min_traverse_height_during_command (float | None) – Absolute Z height (mm) to move involved channels to between batches. None (default) uses full Z safety.

  • z_position_at_end_of_command (float | None) – Absolute Z height (mm) to move involved channels to after probing. None (default) uses full Z safety.

  • x_grouping_tolerance (float | None) – Containers within this X distance (mm) are grouped and probed together. Defaults to _x_grouping_tolerance_mm (0.1 mm).

  • move_to_z_safety_after (bool | None) – Deprecated. Use z_position_at_end_of_command instead.

Returns:

Mean of measured liquid heights for each container (mm from cavity bottom).

Raises:

  • ValueError – If use_channels is empty, contains out-of-range indices, or if input list lengths don’t match.

  • RuntimeError – If any specified channel lacks a tip.

Return type:

List[float]