@opentrons/shared-data 0.0.0-alpha.2 → 0.0.1-alpha.1

package/python/build/lib/opentrons_shared_data/pipette/pipette_definition.py

@@ -0,0 +1,389 @@
+import re
+from typing import List, Dict, Tuple
+from pydantic import BaseModel, Field, validator
+from typing_extensions import Literal
+from dataclasses import dataclass
+
+from . import types as pip_types, dev_types
+
+PLUNGER_CURRENT_MINIMUM = 0.1
+PLUNGER_CURRENT_MAXIMUM = 1.5
+
+NOZZLE_MAP_NAMES = re.compile(r"[A-Z]{1}[0-9]{1,2}")
+
+
+# TODO (lc 12-5-2022) Ideally we can deprecate this
+# at somepoint once we load pipettes by channels and type
+@dataclass
+class PipetteNameType:
+    pipette_type: pip_types.PipetteModelType
+    pipette_channels: pip_types.PipetteChannelType
+    pipette_generation: pip_types.PipetteGenerationType
+
+    def __repr__(self) -> str:
+        base_name = f"{self.pipette_type.name}_{str(self.pipette_channels)}"
+        if self.pipette_generation == pip_types.PipetteGenerationType.GEN1:
+            return base_name
+        elif self.pipette_channels == pip_types.PipetteChannelType.NINETY_SIX_CHANNEL:
+            return base_name
+        else:
+            return f"{base_name}_{self.pipette_generation.name.lower()}"
+
+    def get_version(self) -> pip_types.PipetteVersionType:
+        if self.pipette_generation == pip_types.PipetteGenerationType.FLEX:
+            return pip_types.PipetteVersionType(3, 0)
+        elif self.pipette_generation == pip_types.PipetteGenerationType.GEN2:
+            return pip_types.PipetteVersionType(2, 0)
+        else:
+            return pip_types.PipetteVersionType(1, 0)
+
+
+@dataclass
+class PipetteModelVersionType:
+    pipette_type: pip_types.PipetteModelType
+    pipette_channels: pip_types.PipetteChannelType
+    pipette_version: pip_types.PipetteVersionType
+
+    def __repr__(self) -> str:
+        base_name = f"{self.pipette_type.name}_{str(self.pipette_channels)}"
+
+        return f"{base_name}_v{self.pipette_version}"
+
+
+class FlowRateDefinition(BaseModel):
+    default: float = Field(..., description="Highest API level default fallback.")
+    values_by_api_level: Dict[str, float] = Field(
+        ..., description="flow rates keyed by API level.", alias="valuesByApiLevel"
+    )
+
+
+PipetteFunctionKeyType = Literal["1", "2", "3"]
+ulPerMMType = Dict[PipetteFunctionKeyType, List[Tuple[float, float, float]]]
+
+
+class ulPerMMDefinition(BaseModel):
+    default: ulPerMMType
+
+
+class SupportedTipsDefinition(BaseModel):
+    """Tip parameters available for every tip size."""
+
+    default_aspirate_flowrate: FlowRateDefinition = Field(
+        ...,
+        description="The flowrate used in aspirations by default.",
+        alias="defaultAspirateFlowRate",
+    )
+    default_dispense_flowrate: FlowRateDefinition = Field(
+        ...,
+        description="The flowrate used in dispenses by default.",
+        alias="defaultDispenseFlowRate",
+    )
+    default_blowout_flowrate: FlowRateDefinition = Field(
+        ...,
+        description="The flowrate used in blowouts by default.",
+        alias="defaultBlowOutFlowRate",
+    )
+    default_flow_acceleration: float = Field(
+        float("inf"),  # no default works for all pipettes
+        description="The acceleration used during aspirate/dispense/blowout in ul/s^2.",
+        alias="defaultFlowAcceleration",
+    )
+    default_tip_length: float = Field(
+        ...,
+        description="The default tip length associated with this tip type.",
+        alias="defaultTipLength",
+    )
+    default_return_tip_height: float = Field(
+        default=0.5,
+        description="The height to return a tip to its tiprack.",
+        alias="defaultReturnTipHeight",
+    )
+    aspirate: ulPerMMDefinition = Field(
+        ..., description="The default pipetting functions list for aspirate."
+    )
+    dispense: ulPerMMDefinition = Field(
+        ..., description="The default pipetting functions list for dispensing."
+    )
+    default_push_out_volume: float = Field(
+        ...,
+        description="The default volume for a push-out during dispense.",
+        alias="defaultPushOutVolume",
+    )
+
+
+class MotorConfigurations(BaseModel):
+    idle: float = Field(
+        ..., description="The plunger motor current to use during idle states."
+    )
+    run: float = Field(
+        ..., description="The plunger motor current to use during active states."
+    )
+
+
+class PlungerPositions(BaseModel):
+    top: float = Field(
+        ...,
+        description="The plunger position that describes max available volume of a pipette in mm.",
+    )
+    bottom: float = Field(
+        ...,
+        description="The plunger position that describes min available volume of a pipette in mm.",
+    )
+    blow_out: float = Field(
+        ...,
+        description="The plunger position past 0 volume to blow out liquid.",
+        alias="blowout",
+    )
+    drop_tip: float = Field(
+        ..., description="The plunger position used to drop tips.", alias="drop"
+    )
+
+
+class TipHandlingConfigurations(BaseModel):
+    current: float = Field(
+        ...,
+        description="Either the z motor current needed for picking up tip or the plunger motor current for dropping tip off the nozzle.",
+    )
+    speed: float = Field(
+        ...,
+        description="The speed to move the z or plunger axis for tip pickup or drop off.",
+    )
+    presses: int = Field(
+        default=0.0, description="The number of tries required to force pick up a tip."
+    )
+    increment: float = Field(
+        default=0.0,
+        description="The increment to move the pipette down for force tip pickup retries.",
+    )
+    distance: float = Field(
+        default=0.0, description="The distance to begin a pick up tip from."
+    )
+
+
+class AvailableSensorDefinition(BaseModel):
+    """The number and type of sensors available in the pipette."""
+
+    sensors: List[str] = Field(..., description="")
+
+
+class PartialTipDefinition(BaseModel):
+    partial_tip_supported: bool = Field(
+        ...,
+        description="Whether partial tip pick up is supported.",
+        alias="partialTipSupported",
+    )
+    available_configurations: List[int] = Field(
+        default=None,
+        description="A list of the types of partial tip configurations supported, listed by channel ints",
+        alias="availableConfigurations",
+    )
+    per_tip_pickup_current: float = Field(
+        default=0.5,
+        description="A current scale for pick up tip in a partial tip configuration",
+        alias="perTipPickupCurrent",
+    )
+
+
+class PipettePhysicalPropertiesDefinition(BaseModel):
+    """The physical properties definition of a pipette."""
+
+    display_name: str = Field(
+        ...,
+        description="The display or full product name of the pipette.",
+        alias="displayName",
+    )
+    pipette_backcompat_names: List[dev_types.PipetteName] = Field(
+        ...,
+        description="A list of pipette names that are compatible with this pipette.",
+        alias="backCompatNames",
+    )
+    pipette_type: pip_types.PipetteModelType = Field(
+        ...,
+        description="The pipette model type (related to number of channels).",
+        alias="model",
+    )
+    display_category: pip_types.PipetteGenerationType = Field(
+        ..., description="The product model of the pipette.", alias="displayCategory"
+    )
+    pick_up_tip_configurations: TipHandlingConfigurations = Field(
+        ..., alias="pickUpTipConfigurations"
+    )
+    drop_tip_configurations: TipHandlingConfigurations = Field(
+        ..., alias="dropTipConfigurations"
+    )
+    plunger_motor_configurations: MotorConfigurations = Field(
+        ..., alias="plungerMotorConfigurations"
+    )
+    plunger_positions_configurations: Dict[
+        pip_types.LiquidClasses, PlungerPositions
+    ] = Field(..., alias="plungerPositionsConfigurations")
+    available_sensors: AvailableSensorDefinition = Field(..., alias="availableSensors")
+    partial_tip_configurations: PartialTipDefinition = Field(
+        ..., alias="partialTipConfigurations"
+    )
+    channels: pip_types.PipetteChannelType = Field(
+        ..., description="The maximum number of channels on the pipette."
+    )
+    shaft_diameter: float = Field(
+        ..., description="The diameter of the pipette shaft.", alias="shaftDiameter"
+    )
+    shaft_ul_per_mm: float = Field(
+        ...,
+        description="The conversion rate between uL dispensed and mm of motor movement.",
+        alias="shaftULperMM",
+    )
+    backlash_distance: float = Field(
+        ...,
+        description="The distance of backlash on the plunger motor.",
+        alias="backlashDistance",
+    )
+    quirks: List[pip_types.Quirks] = Field(
+        ..., description="The list of quirks available for the loaded configuration"
+    )
+
+    @validator("pipette_type", pre=True)
+    def convert_pipette_model_string(cls, v: str) -> pip_types.PipetteModelType:
+        return pip_types.PipetteModelType(v)
+
+    @validator("channels", pre=True)
+    def convert_channels(cls, v: int) -> pip_types.PipetteChannelType:
+        return pip_types.PipetteChannelType(v)
+
+    @validator("display_category", pre=True)
+    def convert_display_category(cls, v: str) -> pip_types.PipetteGenerationType:
+        if not v:
+            return pip_types.PipetteGenerationType.GEN1
+        return pip_types.PipetteGenerationType(v)
+
+    @validator("quirks", pre=True)
+    def convert_quirks(cls, v: List[str]) -> List[pip_types.Quirks]:
+        return [pip_types.Quirks(q) for q in v]
+
+    @validator("plunger_positions_configurations", pre=True)
+    def convert_plunger_positions(
+        cls, v: Dict[str, PlungerPositions]
+    ) -> Dict[pip_types.LiquidClasses, PlungerPositions]:
+        return {pip_types.LiquidClasses[key]: value for key, value in v.items()}
+
+    class Config:
+        json_encoders = {
+            pip_types.PipetteChannelType: lambda v: v.value,
+            pip_types.PipetteModelType: lambda v: v.value,
+            pip_types.PipetteGenerationType: lambda v: v.value,
+            pip_types.Quirks: lambda v: v.value,
+        }
+
+
+class PipetteGeometryDefinition(BaseModel):
+    """The geometry properties definition of a pipette."""
+
+    nozzle_offset: List[float] = Field(..., alias="nozzleOffset")
+    path_to_3D: str = Field(
+        ...,
+        description="The shared data relative path to the 3D representation of the pipette model.",
+        alias="pathTo3D",
+    )
+    nozzle_map: Dict[str, List[float]] = Field(..., alias="nozzleMap")
+
+    @validator("nozzle_map", pre=True)
+    def check_nonempty_strings(
+        cls, v: Dict[str, List[float]]
+    ) -> Dict[str, List[float]]:
+        # Note, the key should be able to be a regex but I think
+        # we're not on a pydantic version that supports that.
+        for k in v.keys():
+            if not NOZZLE_MAP_NAMES.match(k):
+                raise ValueError("{k} is not a valid key entry for nozzle map.")
+        return v
+
+
+class PipetteLiquidPropertiesDefinition(BaseModel):
+    """The liquid properties definition of a pipette."""
+
+    supported_tips: Dict[pip_types.PipetteTipType, SupportedTipsDefinition] = Field(
+        ..., alias="supportedTips"
+    )
+    tip_overlap_dictionary: Dict[str, float] = Field(
+        ...,
+        description="The default tip overlap associated with this tip type.",
+        alias="defaultTipOverlapDictionary",
+    )
+    max_volume: int = Field(
+        ...,
+        description="The maximum supported volume of the pipette.",
+        alias="maxVolume",
+    )
+    min_volume: float = Field(
+        ...,
+        description="The minimum supported volume of the pipette.",
+        alias="minVolume",
+    )
+    default_tipracks: List[str] = Field(
+        ...,
+        description="A list of default tiprack paths.",
+        regex="opentrons/[a-z0-9._]+/[0-9]",
+        alias="defaultTipracks",
+    )
+
+    @validator("supported_tips", pre=True)
+    def convert_aspirate_key_to_channel_type(
+        cls, v: Dict[str, SupportedTipsDefinition]
+    ) -> Dict[pip_types.PipetteTipType, SupportedTipsDefinition]:
+        return {pip_types.PipetteTipType[key]: value for key, value in v.items()}
+
+
+class PipetteConfigurations(
+    PipetteGeometryDefinition,
+    PipettePhysicalPropertiesDefinition,
+):
+    """The full pipette configurations of a given model and version."""
+
+    version: pip_types.PipetteVersionType = Field(
+        ..., description="The version of the configuration loaded."
+    )
+    mount_configurations: pip_types.RobotMountConfigs = Field(
+        ...,
+    )
+    liquid_properties: Dict[
+        pip_types.LiquidClasses, PipetteLiquidPropertiesDefinition
+    ] = Field(
+        ..., description="A dictionary of liquid properties keyed by liquid classes."
+    )
+
+    @validator("liquid_properties", pre=True)
+    def convert_liquid_properties_key(
+        cls, v: Dict[str, PipetteLiquidPropertiesDefinition]
+    ) -> Dict[pip_types.LiquidClasses, PipetteLiquidPropertiesDefinition]:
+        return {pip_types.LiquidClasses[key]: value for key, value in v.items()}
+
+
+def liquid_class_for_volume_between_default_and_defaultlowvolume(
+    volume: float,
+    current_liquid_class_name: pip_types.LiquidClasses,
+    available_liquid_classes: Dict[
+        pip_types.LiquidClasses, PipetteLiquidPropertiesDefinition
+    ],
+) -> pip_types.LiquidClasses:
+    """Determine the appropriate liquid class to use for a volume.
+
+    This function has such a weird name because it is hardcoded to only use the liquid
+    classes default and defaultLowVolume. It should no longer be used when those liquid
+    classes change.
+    """
+    # For now, until we add more liquid classes, we're going to hardcode the default
+    # and lowVolumeDefault liquid classes as the ones to switch between.
+    has_lvd = pip_types.LiquidClasses.lowVolumeDefault in available_liquid_classes
+
+    if not has_lvd:
+        return pip_types.LiquidClasses.default
+    if volume >= available_liquid_classes[pip_types.LiquidClasses.default].min_volume:
+        return pip_types.LiquidClasses.default
+    return pip_types.LiquidClasses.lowVolumeDefault
+
+
+def default_tip_for_liquid_class(
+    liquid_class_config: PipetteLiquidPropertiesDefinition,
+) -> pip_types.PipetteTipType:
+    """Provide a "default tip", the one with the largest volume."""
+    tip_names = liquid_class_config.supported_tips.keys()
+    return sorted(tip_names, key=lambda tip: tip.value)[-1]

package/python/build/lib/opentrons_shared_data/pipette/pipette_load_name_conversions.py

@@ -0,0 +1,236 @@
+import re
+from typing import List, Optional, Union, cast
+from .dev_types import PipetteModel, PipetteName
+from .types import (
+    PipetteChannelType,
+    PipetteModelType,
+    PipetteVersionType,
+    PipetteGenerationType,
+    PipetteModelMajorVersionType,
+    PipetteModelMinorVersionType,
+)
+from .pipette_definition import (
+    PipetteNameType,
+    PipetteModelVersionType,
+)
+
+DEFAULT_CALIBRATION_OFFSET = [0.0, 0.0, 0.0]
+DEFAULT_MODEL = PipetteModelType.p1000
+DEFAULT_CHANNELS = PipetteChannelType.SINGLE_CHANNEL
+DEFAULT_MODEL_VERSION = PipetteVersionType(major=1, minor=0)
+
+PIPETTE_AVAILABLE_TYPES = [m.name for m in PipetteModelType]
+PIPETTE_CHANNELS_INTS = [c.value for c in PipetteChannelType]
+
+
+def is_model(model_or_name: Union[PipetteName, PipetteModel, None]) -> bool:
+    """Determine if we have a real model or just a PipetteName.
+
+    Args:
+        model_or_name (Union[PipetteName, PipetteModel, None]): The pipette we want to check.
+
+    Returns:
+        bool: Whether or not the given string is a PipetteModel
+    """
+    if not model_or_name:
+        return False
+    return "v" in model_or_name
+
+
+def supported_pipette(model_or_name: Union[PipetteName, PipetteModel, None]) -> bool:
+    """Determine if a pipette type is supported.
+
+    Args:
+        model_or_name (Union[PipetteName, PipetteModel, None]): The pipette we want to check.
+
+    Returns:
+        bool: Whether or not the given pipette name or model is supported.
+    """
+    if not model_or_name:
+        return False
+    split_model_or_name = model_or_name.split("_")
+    try:
+        channels_as_int = int(channels_from_string(split_model_or_name[1]))
+    except ValueError:
+        channels_as_int = 0
+    if (
+        split_model_or_name[0] in PIPETTE_AVAILABLE_TYPES
+        and channels_as_int in PIPETTE_CHANNELS_INTS
+    ):
+        return True
+    return False
+
+
+def channels_from_string(channels: str) -> PipetteChannelType:
+    """Convert channels from a string.
+
+    With both `py:data:PipetteName` and `py:data:PipetteObject`, we refer to channel types
+    as `single`, `multi` or `96`.
+
+    Args:
+        channels (str): The channel string we wish to convert.
+
+    Returns:
+        PipetteChannelType: A `py:obj:PipetteChannelType`
+        representing the number of channels on a pipette.
+
+    """
+    if channels == "96":
+        return PipetteChannelType.NINETY_SIX_CHANNEL
+    elif channels == "multi":
+        return PipetteChannelType.EIGHT_CHANNEL
+    elif channels == "single":
+        return PipetteChannelType.SINGLE_CHANNEL
+    else:
+        raise ValueError("Invalid number of channels")
+
+
+def version_from_string(version: str) -> PipetteVersionType:
+    """Convert a version string to a py:obj:PipetteVersionType.
+
+    The version string will either be in the format of `int.int` or `vint.int`.
+
+    Args:
+        version (str): The string version we wish to convert.
+
+    Returns:
+        PipetteVersionType: A pipette version object.
+
+    """
+    version_list = [v for v in re.split("\\.|[v]", version) if v]
+    major = cast(PipetteModelMajorVersionType, int(version_list[0]))
+    if len(version_list) > 1:
+        minor = cast(PipetteModelMinorVersionType, int(version_list[1]))
+    else:
+        minor = 0
+    return PipetteVersionType(major, minor)
+
+
+def version_from_generation(pipette_name_list: List[str]) -> PipetteVersionType:
+    """Convert a string generation name to a py:obj:PipetteVersionType.
+
+    Pipette generations are strings in the format of "gen1" or "gen2", and
+    usually associated withe :py:data:PipetteName.
+
+    Args:
+        pipette_name_list (List[str]): A list of strings from the separated by `_`
+        py:data:PipetteName.
+
+    Returns:
+        PipetteVersionType: A pipette version object.
+
+    """
+    if "flex" in pipette_name_list or "gen3" in pipette_name_list:
+        return PipetteVersionType(3, 0)
+    elif "gen2" in pipette_name_list:
+        return PipetteVersionType(2, 0)
+    else:
+        return PipetteVersionType(1, 0)
+
+
+def generation_from_string(pipette_name_list: List[str]) -> PipetteGenerationType:
+    """Convert a string generation name to a py:obj:PipetteGenerationType.
+
+    Args:
+        pipette_name_list (List[str]): A list of strings from the separated by `_`
+        py:data:PipetteName or py:data:PipetteModel.
+
+    Returns:
+        PipetteGenerationType: A pipette version object.
+
+    """
+    if "flex" in pipette_name_list or "3." in pipette_name_list[-1]:
+        return PipetteGenerationType.FLEX
+    elif "gen2" in pipette_name_list or "2." in pipette_name_list[-1]:
+        return PipetteGenerationType.GEN2
+    else:
+        return PipetteGenerationType.GEN1
+
+
+def convert_to_pipette_name_type(
+    model_or_name: Union[PipetteName, PipetteModel]
+) -> PipetteNameType:
+    """Convert the py:data:PipetteName to a py:obj:PipetteModelVersionType.
+
+    `PipetteNames` are in the format of "p300_single" or "p300_single_gen1".
+
+    Args:
+        name (PipetteName): The pipette name we want to convert.
+
+    Returns:
+        PipetteNameType: An object representing a broken out PipetteName
+        string.
+
+    """
+    split_pipette_model_or_name = model_or_name.split("_")
+    channels = channels_from_string(split_pipette_model_or_name[1])
+    generation = generation_from_string(split_pipette_model_or_name)
+    pipette_type = PipetteModelType[split_pipette_model_or_name[0]]
+
+    return PipetteNameType(pipette_type, channels, generation)
+
+
+def convert_pipette_name(
+    name: PipetteName, provided_version: Optional[str] = None
+) -> PipetteModelVersionType:
+    """Convert the py:data:PipetteName to a py:obj:PipetteModelVersionType.
+
+    `PipetteNames` are in the format of "p300_single" or "p300_single_gen1".
+
+    Args:
+        name (PipetteName): The pipette name we want to convert.
+
+    Returns:
+        PipetteModelVersionType: An object representing a broken out PipetteName
+        string.
+
+    """
+    split_pipette_name = name.split("_")
+    channels = channels_from_string(split_pipette_name[1])
+    if provided_version:
+        version = version_from_string(provided_version)
+    else:
+        version = version_from_generation(split_pipette_name)
+
+    pipette_type = PipetteModelType[split_pipette_name[0]]
+
+    return PipetteModelVersionType(pipette_type, channels, version)
+
+
+def convert_pipette_model(
+    model: Optional[PipetteModel], provided_version: Optional[str] = ""
+) -> PipetteModelVersionType:
+    """Convert the py:data:PipetteModel to a py:obj:PipetteModelVersionType.
+
+    `PipetteModel` are in the format of "p300_single_v1.0" or "p300_single_v3.3".
+
+    Sometimes, models may not have a version, in which case the `provided_version` arg
+    allows you to specify a version to search for.
+
+    Args:
+        model (PipetteModel): The pipette model we want to convert.
+        provided_version (str, Optional): The provided version we'd like to look for.
+
+    Returns:
+        PipetteModelVersionType: An object representing a broken out PipetteName
+        string.
+
+    """
+    # TODO (lc 12-5-2022) This helper function is needed
+    # until we stop using "name" and "model" to refer
+    # to attached pipettes.
+    # We need to figure out how to default the pipette model as well
+    # rather than returning a p1000
+    if model and not provided_version:
+        pipette_type, parsed_channels, parsed_version = model.split("_")
+        channels = channels_from_string(parsed_channels)
+        version = version_from_string(parsed_version)
+    elif model and provided_version:
+        pipette_type, parsed_channels = model.split("_")
+        channels = channels_from_string(parsed_channels)
+        version = version_from_string(provided_version)
+    else:
+        pipette_type = DEFAULT_MODEL.value
+        channels = DEFAULT_CHANNELS
+        version = DEFAULT_MODEL_VERSION
+    return PipetteModelVersionType(PipetteModelType[pipette_type], channels, version)