opentrons 8.6.0__py3-none-any.whl

opentrons/protocols/geometry/planning.py

@@ -0,0 +1,297 @@
+import functools
+import logging
+from dataclasses import dataclass
+from typing import Any, List, Optional, Tuple, Type
+
+from opentrons import types
+from opentrons.hardware_control.types import CriticalPoint
+from opentrons.hardware_control.util import plan_arc
+
+from opentrons.motion_planning import (
+    DEFAULT_GENERAL_ARC_Z_MARGIN,
+    DEFAULT_IN_LABWARE_ARC_Z_MARGIN,
+    MINIMUM_Z_MARGIN,
+    MoveType,
+    get_waypoints,
+)
+
+from opentrons.protocols.api_support.labware_like import LabwareLike
+from opentrons.protocol_api.core.legacy.deck import Deck
+from opentrons.protocol_api.core.legacy.module_geometry import ModuleGeometry
+
+
+MODULE_LOG = logging.getLogger(__name__)
+
+
+class LabwareHeightError(Exception):
+    pass
+
+
+def max_many(*args: float) -> float:
+    return functools.reduce(max, args[1:], args[0])
+
+
+BAD_PAIRS = {
+    ("1", "12"),
+    ("12", "1"),
+    ("4", "12"),
+    ("12", "4"),
+    ("4", "9"),
+    ("9", "4"),
+    ("4", "8"),
+    ("8", "4"),
+    ("1", "8"),
+    ("8", "1"),
+    ("4", "11"),
+    ("11", "4"),
+    ("1", "11"),
+    ("11", "1"),
+}
+
+
+def should_dodge_thermocycler(
+    deck: Deck, from_loc: types.Location, to_loc: types.Location
+) -> bool:
+    """
+    Decide if the requested path would cross the thermocycler, if
+    installed.
+
+    Returns True if we need to dodge, False otherwise
+    """
+    if deck.thermocycler_present:
+        transit = (from_loc.labware.first_parent(), to_loc.labware.first_parent())
+        # mypy doesn't like this because transit could be none, but it's
+        # checked by value in BAD_PAIRS which has only strings
+        return transit in BAD_PAIRS
+
+    return False
+
+
+@dataclass
+class MoveConstraints:
+    instr_max_height: float
+    well_z_margin: float = DEFAULT_IN_LABWARE_ARC_Z_MARGIN
+    lw_z_margin: float = DEFAULT_GENERAL_ARC_Z_MARGIN
+    minimum_lw_z_margin: float = MINIMUM_Z_MARGIN
+    minimum_z_height: float = 0.0
+
+    @classmethod
+    def build(cls: Type["MoveConstraints"], **kwargs: Any) -> "MoveConstraints":
+        return cls(**{k: v for k, v in kwargs.items() if v is not None})
+
+
+def get_move_type(
+    from_loc: types.Location,
+    to_loc: types.Location,
+    force_direct: bool = False,
+) -> MoveType:
+    """Given two Locations, return the type of move."""
+    move_type = MoveType.GENERAL_ARC
+    from_labware, from_well = from_loc.labware.get_parent_labware_and_well()
+    to_labware, to_well = to_loc.labware.get_parent_labware_and_well()
+    same_labware = to_labware is not None and to_labware == from_labware
+    same_well = to_well is not None and to_well == from_well
+
+    if same_labware:
+        move_type = MoveType.DIRECT if same_well else MoveType.IN_LABWARE_ARC
+
+    return move_type if not force_direct else MoveType.DIRECT
+
+
+def safe_height(
+    from_loc: types.Location,
+    to_loc: types.Location,
+    deck: Deck,
+    instr_max_height: float,
+    well_z_margin: Optional[float] = None,
+    lw_z_margin: Optional[float] = None,
+    minimum_lw_z_margin: Optional[float] = None,
+    minimum_z_height: Optional[float] = None,
+) -> float:
+    """
+    Derive the height required to clear the current deck setup along
+    with other constraints
+    :param from_loc: The last location.
+    :param to_loc: The location to move to.
+    :param deck: The :py:class:`Deck` instance describing the robot.
+    :param float instr_max_height: The highest z location this pipette can
+                                   achieve
+    :param float well_z_margin: How much extra Z margin to raise the cp by over
+                                the bare minimum to clear wells within the same
+                                labware. Default: 5mm
+    :param float lw_z_margin: How much extra Z margin to raise the cp by over
+                              the bare minimum to clear different pieces of
+                              labware.
+    :param minimum_z_height: When specified, this Z margin is able to raise
+                             (but never lower) the mid-arc height.
+    """
+    constraints = MoveConstraints.build(
+        instr_max_height=instr_max_height,
+        well_z_margin=well_z_margin,
+        lw_z_margin=lw_z_margin,
+        minimum_lw_z_margin=minimum_lw_z_margin,
+        minimum_z_height=minimum_z_height,
+    )
+    assert constraints.minimum_z_height >= 0.0
+    return _build_safe_height(from_loc, to_loc, deck, constraints)
+
+
+def _build_safe_height(
+    from_loc: types.Location,
+    to_loc: types.Location,
+    deck: Deck,
+    constraints: MoveConstraints,
+) -> float:
+    to_point = to_loc.point
+    to_lw, to_well = to_loc.labware.get_parent_labware_and_well()
+    from_point = from_loc.point
+    from_lw, from_well = from_loc.labware.get_parent_labware_and_well()
+
+    if to_lw and from_lw and to_lw == from_lw:
+        # If we know the labwares we’re moving from and to, we can calculate
+        # a safe z based on their heights
+        if to_well:
+            to_safety = to_well.top().point.z + constraints.well_z_margin
+        else:
+            to_safety = to_lw.highest_z + constraints.well_z_margin
+        if from_well:
+            from_safety = from_well.top().point.z + constraints.well_z_margin
+        else:
+            from_safety = from_lw.highest_z + constraints.well_z_margin
+        # if we are already at the labware, we know the instr max height would
+        # be tall enough
+        if max(from_safety, to_safety) > constraints.instr_max_height:
+            to_safety = constraints.instr_max_height
+            from_safety = 0.0  # (ignore since it's in a max())
+    else:
+        # One of our labwares is invalid so we have to just go above
+        # deck.highest_z since we don’t know where we are
+        to_safety = deck.highest_z + constraints.lw_z_margin
+
+        if to_safety > constraints.instr_max_height:
+            if constraints.instr_max_height >= (
+                deck.highest_z + constraints.minimum_lw_z_margin
+            ):
+                to_safety = constraints.instr_max_height
+            else:
+                tallest_lw = list(
+                    filter(
+                        lambda lw: lw.highest_z == deck.highest_z,
+                        [lw for lw in deck.data.values() if lw],
+                    )
+                )[0]
+                if isinstance(tallest_lw, ModuleGeometry) and tallest_lw.labware:
+                    tallest_lw = tallest_lw.labware
+                raise LabwareHeightError(
+                    f"The {tallest_lw} has a total height of {deck.highest_z}"
+                    " mm, which is too tall for your current pipette "
+                    "configurations. The longest pipette on your robot can "
+                    f"only be raised to {constraints.instr_max_height} mm "
+                    "above the deck. "
+                    "This may be because the labware is incorrectly defined, "
+                    "incorrectly calibrated, or physically too tall. This "
+                    "could also be caused by the pipette and its tipracks "
+                    "being mismatched. Please check your protocol, labware "
+                    "definitions and calibrations."
+                )
+        from_safety = 0.0  # (ignore since it’s in a max())
+
+    return max_many(
+        to_point.z, from_point.z, to_safety, from_safety, constraints.minimum_z_height
+    )
+
+
+def plan_moves(
+    from_loc: types.Location,
+    to_loc: types.Location,
+    deck: Deck,
+    instr_max_height: float,
+    well_z_margin: Optional[float] = None,
+    lw_z_margin: Optional[float] = None,
+    force_direct: bool = False,
+    minimum_lw_z_margin: Optional[float] = None,
+    minimum_z_height: Optional[float] = None,
+    use_experimental_waypoint_planning: bool = False,
+) -> List[Tuple[types.Point, Optional[CriticalPoint]]]:
+    """Plan moves between one :py:class:`.Location` and another.
+
+    Each :py:class:`.Location` instance might or might not have a specific
+    kind of geometry attached. This function is intended to return series
+    of moves that contain the minimum safe retractions to avoid (known)
+    labware on the specified :py:class:`Deck`.
+    :param from_loc: The last location.
+    :param to_loc: The location to move to.
+    :param deck: The :py:class:`Deck` instance describing the robot.
+    :param force_direct: If True, ignore any Z margins force a direct move
+    :param use_experimental_waypoint_planning: If True, use waypoint logic
+                                               from opentrons.motion_planning
+
+    The other parameters are as :py:meth:`safe_height`.
+
+    :returns: A list of tuples of :py:class:`.Point` and critical point
+              overrides to move through.
+    """
+    constraints = MoveConstraints.build(
+        instr_max_height=instr_max_height,
+        well_z_margin=well_z_margin,
+        lw_z_margin=lw_z_margin,
+        minimum_lw_z_margin=minimum_lw_z_margin,
+        minimum_z_height=minimum_z_height,
+    )
+    assert constraints.minimum_z_height >= 0.0
+
+    to_point = to_loc.point
+    to_lw, to_well = to_loc.labware.get_parent_labware_and_well()
+    from_point = from_loc.point
+    from_lw, from_well = from_loc.labware.get_parent_labware_and_well()
+    from_center = LabwareLike(from_lw).center_multichannel_on_wells()
+    to_center = LabwareLike(to_lw).center_multichannel_on_wells()
+    dest_cp_override = CriticalPoint.XY_CENTER if to_center else None
+    origin_cp_override = CriticalPoint.XY_CENTER if from_center else None
+    extra_waypoints = []
+
+    if should_dodge_thermocycler(deck, from_loc, to_loc):
+        sc = deck.get_slot_center("5")
+        extra_waypoints = [(sc.x, sc.y)]
+
+    if use_experimental_waypoint_planning:
+        move_type = get_move_type(from_loc, to_loc, force_direct)
+        min_travel_z = deck.highest_z
+
+        if to_lw is not None and move_type == MoveType.IN_LABWARE_ARC:
+            min_travel_z = to_lw.highest_z
+
+        # TODO(mc, 2020-11-05): if this ever needs to be used, we need a
+        # story to re-create error messaging from LabwareHeightError above if
+        # this raises a MotionPlanningError
+        waypoints = get_waypoints(
+            origin=from_point,
+            dest=to_point,
+            min_travel_z=min_travel_z,
+            max_travel_z=instr_max_height,
+            move_type=move_type,
+            xy_waypoints=extra_waypoints,
+            origin_cp=origin_cp_override,
+            dest_cp=dest_cp_override,
+        )
+        return [(wp.position, wp.critical_point) for wp in waypoints]
+
+    is_same_location = (to_lw and to_lw == from_lw) and (
+        to_well and to_well == from_well
+    )
+    if force_direct or (is_same_location and not (minimum_z_height or 0) > 0):
+        # If we’re going direct, we can assume we’re already in the correct
+        # cp so we can use the override without prep
+        return [(to_point, dest_cp_override)]
+
+    # Find the safe z heights based on the destination and origin labware/well
+    safe = _build_safe_height(from_loc, to_loc, deck, constraints)
+
+    return plan_arc(
+        from_point,
+        to_point,
+        safe,
+        origin_cp_override,
+        dest_cp_override,
+        extra_waypoints,
+    )

opentrons/protocols/labware.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+import logging
+import json
+import os
+from pathlib import Path
+from typing import Mapping, Optional, Union, List, Sequence, Literal
+
+import jsonschema  # type: ignore
+
+from opentrons_shared_data import load_shared_data, get_shared_data_root
+from opentrons.protocols.api_support.util import ModifiedList
+from opentrons.protocols.api_support.constants import (
+    OPENTRONS_NAMESPACE,
+    CUSTOM_NAMESPACE,
+    STANDARD_DEFS_PATH,
+    USER_DEFS_PATH,
+)
+from opentrons_shared_data.labware.types import LabwareDefinition
+from opentrons_shared_data.errors.exceptions import InvalidProtocolData
+
+
+MODULE_LOG = logging.getLogger(__name__)
+
+LabwareProblem = Literal[
+    "no-schema-id", "bad-schema-id", "schema-mismatch", "invalid-json"
+]
+
+
+class NotALabwareError(InvalidProtocolData):
+    def __init__(
+        self, problem: LabwareProblem, wrapping: Sequence[BaseException]
+    ) -> None:
+        messages: dict[LabwareProblem, str] = {
+            "no-schema-id": "No schema ID present in file",
+            "bad-schema-id": "Bad schema ID in file",
+            "invalid-json": "File does not contain valid JSON",
+            "schema-mismatch": "File does not match labware schema",
+        }
+        super().__init__(
+            message=messages[problem], detail={"kind": problem}, wrapping=wrapping
+        )
+
+
+def get_labware_definition(
+    load_name: str,
+    namespace: Optional[str] = None,
+    version: Optional[int] = None,
+    bundled_defs: Optional[Mapping[str, LabwareDefinition]] = None,
+    extra_defs: Optional[Mapping[str, LabwareDefinition]] = None,
+) -> LabwareDefinition:
+    """
+    Look up and return a definition by load_name + namespace + version and
+        return it or raise an exception
+
+    :param str load_name: corresponds to 'loadName' key in definition
+    :param str namespace: The namespace the labware definition belongs to.
+        If unspecified, will search 'opentrons' then 'custom_beta'
+    :param int version: The version of the labware definition. If unspecified,
+        will use version 1.
+    :param bundled_defs: A bundle of labware definitions to exclusively use for
+        finding labware definitions, if specified
+    :param extra_defs: An extra set of definitions (in addition to the system
+        definitions) in which to search
+    """
+    load_name = load_name.lower()
+
+    if bundled_defs is not None:
+        return _get_labware_definition_from_bundle(
+            bundled_defs, load_name, namespace, version
+        )
+
+    checked_extras = extra_defs or {}
+
+    try:
+        return _get_labware_definition_from_bundle(
+            checked_extras, load_name, namespace, version
+        )
+    except (FileNotFoundError, RuntimeError):
+        pass
+
+    return _get_standard_labware_definition(load_name, namespace, version)
+
+
+def get_all_labware_definitions(schema_version: str = "2") -> List[str]:
+    """
+    Return a list of standard and custom labware definitions with load_name +
+        name_space + version existing on the robot
+    """
+    labware_list = ModifiedList()
+
+    def _check_for_subdirectories(path: Union[str, Path, os.DirEntry[str]]) -> None:
+        with os.scandir(path) as top_path:
+            for sub_dir in top_path:
+                if sub_dir.is_dir():
+                    labware_list.append(sub_dir.name)
+
+    # check for standard labware
+    _check_for_subdirectories(
+        get_shared_data_root() / STANDARD_DEFS_PATH / schema_version
+    )
+    # check for custom labware
+    for namespace in os.scandir(USER_DEFS_PATH):
+        _check_for_subdirectories(namespace)
+    return labware_list
+
+
+def save_definition(
+    labware_def: LabwareDefinition, force: bool = False, location: Optional[Path] = None
+) -> None:
+    """
+    Save a labware definition
+
+    :param labware_def: A deserialized JSON labware definition
+    :param bool force: If true, overwrite an existing definition if found.
+        Cannot overwrite Opentrons definitions.
+    :param location: File path
+    """
+    namespace = labware_def["namespace"]
+    load_name = labware_def["parameters"]["loadName"]
+    version = labware_def["version"]
+
+    verify_definition(labware_def)
+
+    if not namespace or not load_name or not version:
+        raise RuntimeError(
+            "Could not save definition, labware def is missing a field: "
+            + f"{namespace}, {load_name}, {version}"
+        )
+
+    if namespace == OPENTRONS_NAMESPACE:
+        raise RuntimeError(
+            f'Saving definitions to the "{OPENTRONS_NAMESPACE}" namespace '
+            + "is not permitted"
+        )
+    def_path = _get_path_to_labware(load_name, namespace, version, location)
+
+    if not force and def_path.is_file():
+        raise RuntimeError(
+            f"The given definition ({namespace}/{load_name} v{version}) "
+            + "already exists. Cannot save definition without force=True"
+        )
+
+    Path(def_path).parent.mkdir(parents=True, exist_ok=True)
+    with open(def_path, "w") as f:
+        json.dump(labware_def, f)
+
+
+def verify_definition(  # noqa: C901
+    contents: str | bytes | LabwareDefinition | object,
+) -> LabwareDefinition:
+    """Verify that an input string is a labware definition and return it.
+
+    :param contents: The untrusted input to parse and validate. If str or bytes, it's
+        parsed as JSON. Otherwise, it should be the output of json.load().
+
+    :raises NotALabwareError:
+
+    :returns: The parsed and validated definition
+    """
+    schemata_by_version = {
+        2: json.loads(load_shared_data("labware/schemas/2.json").decode("utf-8")),
+        3: json.loads(load_shared_data("labware/schemas/3.json").decode("utf-8")),
+    }
+
+    try:
+        parsed_json: object = (
+            json.loads(contents) if isinstance(contents, (str, bytes)) else contents
+        )
+    except json.JSONDecodeError as e:
+        raise NotALabwareError("invalid-json", [e]) from e
+
+    if isinstance(parsed_json, dict):
+        try:
+            schema_version: object = parsed_json["schemaVersion"]
+        except KeyError as e:
+            raise NotALabwareError("no-schema-id", [e]) from e
+    else:
+        raise NotALabwareError("no-schema-id", [])
+
+    try:
+        # we can type ignore this because we handle the KeyError below
+        schema = schemata_by_version[schema_version]  # type: ignore[index]
+    except KeyError as e:
+        raise NotALabwareError("bad-schema-id", [e]) from e
+
+    try:
+        jsonschema.validate(parsed_json, schema)
+    except jsonschema.ValidationError as e:
+        raise NotALabwareError("schema-mismatch", [e]) from e
+
+    # we can type ignore this because if it passes the jsonschema it has
+    # the correct structure
+    return parsed_json  # type: ignore[return-value]
+
+
+def _get_labware_definition_from_bundle(
+    bundled_labware: Mapping[str, LabwareDefinition],
+    load_name: str,
+    namespace: Optional[str] = None,
+    version: Optional[int] = None,
+) -> LabwareDefinition:
+    """
+    Look up and return a bundled definition by ``load_name`` + ``namespace``
+    + ``version`` and return it or raise an exception. The``namespace`` and
+    ``version`` args are optional, they only have to be specified if there is
+    ambiguity (eg when multiple labware in the bundle share the same
+    ``load_name``)
+
+    :param str load_name: corresponds to 'loadName' key in definition
+    :param str namespace: The namespace the labware definition belongs to
+    :param int version: The version of the labware definition
+    :param Dict bundled_labware: A dictionary of labware definitions to search
+    """
+    load_name = load_name.lower()
+
+    bundled_candidates = [
+        b for b in bundled_labware.values() if b["parameters"]["loadName"] == load_name
+    ]
+    if namespace:
+        namespace = namespace.lower()
+        bundled_candidates = [
+            b for b in bundled_candidates if b["namespace"] == namespace
+        ]
+    if version:
+        bundled_candidates = [b for b in bundled_candidates if b["version"] == version]
+
+    if len(bundled_candidates) == 1:
+        return bundled_candidates[0]
+    elif len(bundled_candidates) > 1:
+        raise RuntimeError(
+            f"Ambiguous labware access. Bundle contains multiple "
+            f"labware with load name {load_name}, "
+            f"namespace {namespace}, and version {version}."
+        )
+    else:
+        raise RuntimeError(
+            f"No labware found in bundle with load name {load_name}, "
+            f"namespace {namespace}, and version {version}."
+        )
+
+
+def _get_standard_labware_definition(
+    load_name: str, namespace: Optional[str] = None, version: Optional[int] = None
+) -> LabwareDefinition:
+    if version is None:
+        checked_version = 1
+    else:
+        checked_version = version
+    error_msg_string = """Unable to find a labware
+        definition for "{0}",
+        version {1}, in the {2} namespace.
+        Please confirm your protocol includes the correct
+        labware spelling and (optionally) the correct version
+        number and namespace.
+
+        If you are referencing a custom labware in your
+        protocol, you must add it to your Custom Labware
+        Definitions Folder from the Opentrons App before
+        uploading your protocol.
+        """
+    if namespace is None:
+        for fallback_namespace in [OPENTRONS_NAMESPACE, CUSTOM_NAMESPACE]:
+            try:
+                return _get_standard_labware_definition(
+                    load_name, fallback_namespace, checked_version
+                )
+            except FileNotFoundError:
+                pass
+
+        raise FileNotFoundError(
+            error_msg_string.format(load_name, checked_version, OPENTRONS_NAMESPACE)
+        )
+
+    namespace = namespace.lower()
+    def_path = _get_path_to_labware(load_name, namespace, checked_version)
+
+    try:
+        with open(def_path, "rb") as f:
+            labware_def = json.loads(f.read().decode("utf-8"))
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f'Labware "{load_name}" not found with version {checked_version} '
+            f'in namespace "{namespace}".'
+        )
+    return labware_def  # type: ignore[no-any-return]
+
+
+def _get_path_to_labware(
+    load_name: str, namespace: str, version: int, base_path: Optional[Path] = None
+) -> Path:
+    if namespace == OPENTRONS_NAMESPACE:
+        # all labware in OPENTRONS_NAMESPACE is stored in shared data
+        schema_3_path = (
+            get_shared_data_root()
+            / STANDARD_DEFS_PATH
+            / "3"
+            / load_name
+            / f"{version}.json"
+        )
+        schema_2_path = (
+            get_shared_data_root()
+            / STANDARD_DEFS_PATH
+            / "2"
+            / load_name
+            / f"{version}.json"
+        )
+        return schema_3_path if schema_3_path.exists() else schema_2_path
+    if not base_path:
+        base_path = USER_DEFS_PATH
+    def_path = base_path / namespace / load_name / f"{version}.json"
+    return def_path