opentrons 8.6.0a1__py3-none-any.whl

opentrons/protocol_runner/task_queue.py

@@ -0,0 +1,95 @@
+"""Asynchronous task queue to accomplish a protocol run."""
+import asyncio
+import logging
+from typing import Any, Awaitable, Callable, Optional, ParamSpec, Concatenate
+
+log = logging.getLogger(__name__)
+
+CleanupFuncInput = ParamSpec("CleanupFuncInput")
+RunFuncInput = ParamSpec("RunFuncInput")
+
+
+class TaskQueue:
+    """A queue of async tasks to run.
+
+    Once started, a TaskQueue may not be re-used.
+    """
+
+    def __init__(
+        self,
+        # cleanup_func: CleanupFunc,
+    ) -> None:
+        """Initialize the TaskQueue."""
+        self._cleanup_func: Optional[
+            Callable[[Optional[Exception]], Awaitable[Any]]
+        ] = None
+
+        self._run_func: Optional[Callable[[], Any]] = None
+        self._run_task: Optional["asyncio.Task[None]"] = None
+        self._ok_to_join_event: asyncio.Event = asyncio.Event()
+
+    def set_cleanup_func(
+        self,
+        func: Callable[
+            Concatenate[Optional[Exception], CleanupFuncInput], Awaitable[Any]
+        ],
+        *args: CleanupFuncInput.args,
+        **kwargs: CleanupFuncInput.kwargs,
+    ) -> None:
+        """Add the protocol cleanup task to the queue.
+
+        The "cleanup" task will be run after the "run" task.
+        """
+
+        async def _do_cleanup(error: Optional[Exception]) -> None:
+            await func(error, *args, **kwargs)
+
+        self._cleanup_func = _do_cleanup
+
+    def set_run_func(
+        self,
+        func: Callable[RunFuncInput, Awaitable[Any]],
+        *args: RunFuncInput.args,
+        **kwargs: RunFuncInput.kwargs,
+    ) -> None:
+        """Add the protocol run task to the queue.
+
+        The "run" task will be run first, before the "cleanup" task.
+        """
+
+        async def _do_run() -> None:
+            await func(*args, **kwargs)
+
+        self._run_func = _do_run
+
+    def start(self) -> None:
+        """Start running tasks in the queue."""
+        self._ok_to_join_event.set()
+
+        if self._run_task is None:
+            self._run_task = asyncio.create_task(self._run())
+
+    async def join(self) -> None:
+        """Wait for the background run task to complete, propagating errors."""
+        await self._ok_to_join_event.wait()
+
+        if self._run_task:
+            await self._run_task
+
+    async def _run(self) -> None:
+        error = None
+
+        try:
+            if self._run_func is not None:
+                await self._run_func()
+        except Exception as e:
+            log.exception("Exception raised by protocol")
+            error = e
+        finally:
+            self._run_func = None
+
+        try:
+            if self._cleanup_func is not None:
+                await self._cleanup_func(error)
+        finally:
+            self._cleanup_func = None

opentrons/protocols/__init__.py

@@ -0,0 +1,6 @@
+""" opentrons.protocols: functions and state for handling, executing, and
+simulating protocols.
+
+This genericizes over v1 and v2 protocols and allows for version inference
+and version-independent apis for simulating and executing protocols.
+"""

opentrons/protocols/advanced_control/common.py

@@ -0,0 +1,38 @@
+"""Common resources for all advanced control functions."""
+import enum
+from typing import NamedTuple, Optional
+
+
+class MixStrategy(enum.Enum):
+    BOTH = enum.auto()
+    BEFORE = enum.auto()
+    AFTER = enum.auto()
+    NEVER = enum.auto()
+
+
+class MixOpts(NamedTuple):
+    """
+    Options to customize behavior of mix.
+
+    These options will be passed to
+    :py:meth:`InstrumentContext.mix` when it is called during the
+    transfer.
+    """
+
+    repetitions: Optional[int] = None
+    volume: Optional[float] = None
+    rate: Optional[float] = None
+
+
+MixOpts.repetitions.__doc__ = ":py:class:`int`"
+MixOpts.volume.__doc__ = ":py:class:`float`"
+MixOpts.rate.__doc__ = ":py:class:`float`"
+
+
+class Mix(NamedTuple):
+    """
+    Options to control mix behavior before aspirate and after dispense.
+    """
+
+    mix_before: MixOpts = MixOpts()
+    mix_after: MixOpts = MixOpts()

opentrons/protocols/advanced_control/mix.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict, Tuple
+
+from .common import MixStrategy, Mix
+
+
+def mix_from_kwargs(top_kwargs: Dict[str, Any]) -> Tuple[MixStrategy, Mix]:
+    """A utility function to determine mix strategy from key word arguments
+    to InstrumentContext.mix"""
+
+    def _mix_requested(kwargs: Dict[str, Any], opt: str) -> bool:
+        """
+        Helper for determining mix options from :py:meth:`transfer` kwargs
+        Mixes can be ignored in kwargs by either
+        - Not specifying the kwarg
+        - Specifying it as None
+        - Specifying it as (0, 0)
+
+        This handles all these cases.
+        """
+        val = kwargs.get(opt)
+        if None is val:
+            return False
+        if val == (0, 0):
+            return False
+        return True
+
+    mix_opts = Mix()
+    if _mix_requested(top_kwargs, "mix_before") and _mix_requested(
+        top_kwargs, "mix_after"
+    ):
+        mix_strategy = MixStrategy.BOTH
+        before_opts = top_kwargs["mix_before"]
+        after_opts = top_kwargs["mix_after"]
+        mix_opts = mix_opts._replace(
+            mix_after=mix_opts.mix_after._replace(
+                repetitions=after_opts[0], volume=after_opts[1]
+            ),
+            mix_before=mix_opts.mix_before._replace(
+                repetitions=before_opts[0], volume=before_opts[1]
+            ),
+        )
+    elif _mix_requested(top_kwargs, "mix_before"):
+        mix_strategy = MixStrategy.BEFORE
+        before_opts = top_kwargs["mix_before"]
+        mix_opts = mix_opts._replace(
+            mix_before=mix_opts.mix_before._replace(
+                repetitions=before_opts[0], volume=before_opts[1]
+            )
+        )
+    elif _mix_requested(top_kwargs, "mix_after"):
+        mix_strategy = MixStrategy.AFTER
+        after_opts = top_kwargs["mix_after"]
+        mix_opts = mix_opts._replace(
+            mix_after=mix_opts.mix_after._replace(
+                repetitions=after_opts[0], volume=after_opts[1]
+            )
+        )
+    else:
+        mix_strategy = MixStrategy.NEVER
+    return mix_strategy, mix_opts

opentrons/protocols/advanced_control/transfers/common.py

@@ -0,0 +1,180 @@
+"""Common functions between v1 transfer and liquid-class-based transfer."""
+import enum
+import math
+from typing import Iterable, Generator, Tuple, TypeVar, Literal, List, Union
+
+from opentrons.protocol_api._liquid_properties import (
+    LiquidHandlingPropertyByVolume,
+    TransferProperties,
+)
+
+
+class NoLiquidClassPropertyError(ValueError):
+    """An error raised when a liquid class property cannot be found for a pipette/tip combination"""
+
+
+class TransferTipPolicyV2(enum.Enum):
+    ONCE = "once"
+    NEVER = "never"
+    ALWAYS = "always"
+    PER_SOURCE = "per source"
+    PER_DESTINATION = "per destination"
+
+
+TransferTipPolicyV2Type = Literal[
+    "once", "always", "per source", "never", "per destination"
+]
+
+Target = TypeVar("Target")
+
+
+def check_valid_volume_parameters(
+    disposal_volume: float, air_gap: float, max_volume: float
+) -> None:
+    if air_gap >= max_volume:
+        raise ValueError(
+            "The air gap must be less than the maximum volume of the pipette"
+        )
+    elif disposal_volume >= max_volume:
+        raise ValueError(
+            "The disposal volume must be less than the maximum volume of the pipette"
+        )
+    elif disposal_volume + air_gap >= max_volume:
+        raise ValueError(
+            "The sum of the air gap and disposal volume must be less than"
+            " the maximum volume of the pipette"
+        )
+
+
+def check_valid_liquid_class_volume_parameters(
+    aspirate_volume: float,
+    air_gap: float,
+    max_volume: float,
+    current_volume: float,
+) -> None:
+    if (
+        current_volume != 0.0
+        and air_gap + aspirate_volume + current_volume > max_volume
+    ):
+        raise ValueError(
+            f"Cannot have an air gap of {air_gap} µL for an aspiration of {aspirate_volume} µL with"
+            f" a max volume of {max_volume} µL when {current_volume} µL has already been aspirated."
+            f" Please adjust the retract air gap to fit within the bounds of the tip."
+        )
+    elif air_gap + aspirate_volume > max_volume:
+        raise ValueError(
+            f"Cannot have an air gap of {air_gap} µL for an aspiration of {aspirate_volume} µL"
+            f" with a max volume of {max_volume} µL. Please adjust the retract air gap to fit within"
+            f" the bounds of the tip."
+        )
+
+
+def expand_for_volume_constraints(
+    volumes: Iterable[float],
+    targets: Iterable[Target],
+    max_volume: float,
+) -> Generator[Tuple[float, "Target"], None, None]:
+    """Split a sequence of proposed transfers if necessary to keep each
+    transfer under the given max volume.
+    """
+    # A final defense against an infinite loop.
+    # Raising a proper exception with a helpful message is left to calling code,
+    # because it has more context about what the user is trying to do.
+    assert max_volume > 0
+    for volume, target in zip(volumes, targets):
+        while volume > max_volume * 2:
+            yield max_volume, target
+            volume -= max_volume
+
+        if volume > max_volume:
+            volume /= 2
+            yield volume, target
+        yield volume, target
+
+
+def _split_volume_equally(volume: float, max_volume: float) -> List[float]:
+    """
+    Splits a given volume into a list of volumes that are all less than or equal to max volume.
+
+    If volume provided is more than the max volume, the volumes will be split evenly.
+    """
+    if volume <= max_volume:
+        return [volume]
+    else:
+        iterations = math.ceil(volume / max_volume)
+        return [volume / iterations for _ in range(iterations)]
+
+
+def get_sources_and_destinations_for_liquid_classes(
+    volumes: List[float],
+    max_volume: float,
+    targets: Iterable[Target],
+    transfer_properties: TransferProperties,
+    is_multi_dispense: bool = False,
+) -> Generator[Tuple[float, "Target"], None, None]:
+    """Return a list of targets (wells or tuples of wells) and volumes for a liquid class transfer."""
+    aspirate_air_gap_by_volume = transfer_properties.aspirate.retract.air_gap_by_volume
+    if is_multi_dispense:
+        assert transfer_properties.multi_dispense is not None
+        disposal_vol_by_volume = transfer_properties.multi_dispense.disposal_by_volume
+        conditioning_vol_by_volume = (
+            transfer_properties.multi_dispense.conditioning_by_volume
+        )
+        return expand_for_volume_constraints_for_liquid_classes(
+            volumes=volumes,
+            targets=targets,
+            max_volume=max_volume,
+            air_gap=aspirate_air_gap_by_volume,
+            disposal_vol=disposal_vol_by_volume,
+            conditioning_vol=conditioning_vol_by_volume,
+        )
+    return expand_for_volume_constraints_for_liquid_classes(
+        volumes=volumes,
+        targets=targets,
+        max_volume=max_volume,
+        air_gap=aspirate_air_gap_by_volume,
+    )
+
+
+def expand_for_volume_constraints_for_liquid_classes(
+    volumes: Iterable[float],
+    targets: Iterable[Target],
+    max_volume: float,
+    air_gap: Union[LiquidHandlingPropertyByVolume, float],
+    disposal_vol: Union[LiquidHandlingPropertyByVolume, float] = 0.0,
+    conditioning_vol: Union[LiquidHandlingPropertyByVolume, float] = 0.0,
+) -> Generator[Tuple[float, "Target"], None, None]:
+    """Split a sequence of proposed transfers to keep each under the max volume, splitting larger ones equally."""
+    assert max_volume > 0
+    for volume, target in zip(volumes, targets):
+        disposal_volume = (
+            disposal_vol
+            if isinstance(disposal_vol, float)
+            else disposal_vol.get_for_volume(volume)
+        )
+        air_gap_volume = (
+            air_gap
+            if isinstance(air_gap, float)
+            else air_gap.get_for_volume(volume + disposal_volume)
+        )
+        conditioning_volume = (
+            conditioning_vol
+            if isinstance(conditioning_vol, float)
+            else conditioning_vol.get_for_volume(volume)
+        )
+        # If there is conditioning volume in a multi-aspirate, it will negate the air gap
+        if conditioning_volume > 0:
+            air_gap_volume = 0
+        adjusted_max_volume = (
+            max_volume - air_gap_volume - disposal_volume - conditioning_volume
+        )
+        if adjusted_max_volume <= 0:
+            error_text = f"Pipette cannot aspirate {volume} µL when pipette will need {air_gap_volume} µL for air gap"
+            if disposal_volume:
+                error_text += f", {disposal_volume} for disposal volume"
+            if conditioning_volume:
+                error_text += f", {conditioning_volume} for conditioning volume"
+            error_text += f" with a max volume of {max_volume} µL."
+            raise ValueError(error_text)
+        for split_volume in _split_volume_equally(volume, adjusted_max_volume):
+            yield split_volume, target