@opentrons/shared-data 0.0.0-alpha.14

package/python/opentrons_shared_data/gripper/__init__.py

@@ -0,0 +1,63 @@
+"""opentrons_shared_data.gripper: functions and types for gripper config."""
+from typing import cast, Any
+from typing_extensions import Literal
+import json
+from pathlib import Path
+
+from .. import load_shared_data
+from .gripper_definition import (
+    GripperDefinition,
+    GripperSchema,
+    GripperSchemaVersion,
+    GripForceProfile,
+    GripperModel,
+    Geometry,
+)
+
+
+class InvalidGripperDefinition(Exception):
+    """Incorrect gripper definition."""
+
+    pass
+
+
+def generate_schema() -> str:
+    """Create schema."""
+    raw_json_schema = GripperDefinition.schema_json()
+    schema_as_dict = json.loads(raw_json_schema)
+    return json.dumps(schema_as_dict, indent=2)
+
+
+def load_schema(version: Literal[1]) -> GripperSchema:
+    """Load gripper schema."""
+    path = Path("gripper") / "schemas" / f"{version}.json"
+    return cast(GripperSchema, json.loads(load_shared_data(path)))
+
+
+def _load_definition_data(path: Path) -> Any:
+    return
+
+
+def load_definition(
+    model: GripperModel,
+    version: GripperSchemaVersion = 1,
+) -> GripperDefinition:
+    """Load gripper definition based on schema version and gripper model."""
+    try:
+        path = Path("gripper") / "definitions" / f"{version}" / f"{model.value}.json"
+        return GripperDefinition.parse_obj(json.loads(load_shared_data(path)))
+    except FileNotFoundError:
+        raise InvalidGripperDefinition(
+            f"Gripper model {model} definition in schema version {version} does not exist."
+        )
+
+
+__all__ = [
+    "GripperDefinition",
+    "GripperSchema",
+    "GripperSchemaVersion",
+    "GripForceProfile",
+    "GripperModel",
+    "Geometry",
+    "generate_schema",
+]

package/python/opentrons_shared_data/gripper/constants.py

@@ -0,0 +1,5 @@
+"""Gripper constants and default values."""
+
+LABWARE_GRIP_FORCE = 15.0  # Newtons
+GRIPPER_DECK_DROP_OFFSET = [-0.5, -0.5, -1.5]
+GRIPPER_MODULE_DROP_OFFSET = [0.0, 0.0, 1.5]

package/python/opentrons_shared_data/gripper/gripper_definition.py

@@ -0,0 +1,101 @@
+"""Gripper configurations."""
+
+from typing_extensions import Literal
+from typing import TYPE_CHECKING, List, Dict, Tuple, Any, NewType
+from pydantic import BaseModel, Field, conint, confloat
+from enum import Enum
+
+
+def _snake_to_camel_case(snake: str) -> str:
+    """Turns snake_case to camelCase."""
+    return "".join(
+        [s.capitalize() if i > 0 else s.lower() for i, s in enumerate(snake.split("_"))]
+    )
+
+
+GripperModelStr = NewType("GripperModelStr", str)
+
+
+# TODO (spp, 2023-01-31): figure out if we want to keep this a string enum or revert to
+#  a regular enum with custom stringification
+class GripperModel(str, Enum):
+    """Gripper models."""
+
+    v1 = "gripperV1"
+    v1_1 = "gripperV1.1"
+    v1_2 = "gripperV1.2"
+
+    def __str__(self) -> str:
+        """Model name."""
+        enum_to_str = {
+            self.__class__.v1: "gripperV1",
+            self.__class__.v1_1: "gripperV1.1",
+            self.__class__.v1_2: "gripperV1.2",
+        }
+        return enum_to_str[self]
+
+
+GripperSchemaVersion = Literal[1]
+
+GripperSchema = Dict[str, Any]
+
+
+if TYPE_CHECKING:
+    _StrictNonNegativeInt = int
+    _StrictNonNegativeFloat = float
+else:
+    _StrictNonNegativeInt = conint(strict=True, ge=0)
+    _StrictNonNegativeFloat = confloat(strict=True, ge=0.0)
+
+
+class GripperBaseModel(BaseModel):
+    """Gripper base model."""
+
+    class Config:
+        """Config."""
+
+        alias_generator = _snake_to_camel_case
+        allow_population_by_field_name = True
+
+
+Offset = Tuple[float, float, float]
+
+
+class Geometry(GripperBaseModel):
+    """Gripper geometry definition."""
+
+    base_offset_from_mount: Offset
+    jaw_center_offset_from_base: Offset
+    pin_one_offset_from_base: Offset
+    pin_two_offset_from_base: Offset
+    jaw_width: Dict[str, float]
+
+
+PolynomialTerm = Tuple[_StrictNonNegativeInt, float]
+
+
+class GripForceProfile(GripperBaseModel):
+    """Gripper force profile."""
+
+    polynomial: List[PolynomialTerm] = Field(
+        ...,
+        description="Polynomial function to convert a grip force in Newton to the jaw motor duty cycle value, which will be read by the gripper firmware.",
+        min_items=1,
+    )
+    default_grip_force: _StrictNonNegativeFloat
+    default_idle_force: _StrictNonNegativeFloat
+    default_home_force: _StrictNonNegativeFloat
+    min: _StrictNonNegativeFloat
+    max: _StrictNonNegativeFloat
+
+
+class GripperDefinition(GripperBaseModel):
+    """Gripper definition."""
+
+    schema_version: GripperSchemaVersion = Field(
+        ..., description="Which schema version a gripper is using"
+    )
+    display_name: str = Field(..., description="Gripper display name.")
+    model: GripperModel
+    geometry: Geometry
+    grip_force_profile: GripForceProfile

package/python/opentrons_shared_data/labware/__init__.py

@@ -0,0 +1,22 @@
+"""
+opentrons_shared_data.labware: types and functions for accessing labware defs
+"""
+import json
+from typing import Any, Dict, NewType, TYPE_CHECKING
+
+from .. import load_shared_data
+
+if TYPE_CHECKING:
+    from .dev_types import LabwareDefinition
+
+Schema = NewType("Schema", Dict[str, Any])
+
+
+def load_definition(loadname: str, version: int) -> "LabwareDefinition":
+    return json.loads(
+        load_shared_data(f"labware/definitions/2/{loadname}/{version}.json")
+    )
+
+
+def load_schema() -> Schema:
+    return json.loads(load_shared_data("labware/schemas/2.json"))

package/python/opentrons_shared_data/labware/constants.py

@@ -0,0 +1,7 @@
+import re
+from typing_extensions import Final
+
+
+# Regular expression to validate and extract row, column from well name
+# (ie A3, C1)
+WELL_NAME_PATTERN: Final["re.Pattern[str]"] = re.compile(r"^([A-Z]+)([0-9]+)$", re.X)

package/python/opentrons_shared_data/labware/dev_types.py

@@ -0,0 +1,140 @@
+""" opentrons_shared_data.labware.dev_types: types for labware defs
+
+types in this file by and large require the use of typing_extensions.
+this module shouldn't be imported unless typing.TYPE_CHECKING is true.
+"""
+from typing import Dict, List, NewType, Union
+from typing_extensions import Literal, TypedDict
+
+
+LabwareUri = NewType("LabwareUri", str)
+
+LabwareDisplayCategory = Union[
+    Literal["tipRack"],
+    Literal["tubeRack"],
+    Literal["reservoir"],
+    Literal["trash"],
+    Literal["wellPlate"],
+    Literal["aluminumBlock"],
+    Literal["adapter"],
+    Literal["other"],
+]
+
+LabwareFormat = Union[
+    Literal["96Standard"],
+    Literal["384Standard"],
+    Literal["trough"],
+    Literal["irregular"],
+    Literal["trash"],
+]
+
+LabwareRoles = Union[
+    Literal["labware"],
+    Literal["fixture"],
+    Literal["adapter"],
+    Literal["maintenance"],
+]
+
+Circular = Literal["circular"]
+Rectangular = Literal["rectangular"]
+WellShape = Union[Circular, Rectangular]
+
+
+class NamedOffset(TypedDict):
+    x: float
+    y: float
+    z: float
+
+
+class GripperOffsets(TypedDict):
+    pickUpOffset: NamedOffset
+    dropOffset: NamedOffset
+
+
+class LabwareParameters(TypedDict, total=False):
+    format: LabwareFormat
+    isTiprack: bool
+    loadName: str
+    isMagneticModuleCompatible: bool
+    quirks: List[str]
+    tipLength: float
+    tipOverlap: float
+    magneticModuleEngageHeight: float
+
+
+class LabwareBrandData(TypedDict, total=False):
+    brand: str
+    brandId: List[str]
+    links: List[str]
+
+
+class LabwareMetadata(TypedDict, total=False):
+    displayName: str
+    displayCategory: LabwareDisplayCategory
+    displayVolumeUnits: Union[Literal["µL"], Literal["mL"], Literal["L"]]
+    tags: List[str]
+
+
+class LabwareDimensions(TypedDict):
+    yDimension: float
+    zDimension: float
+    xDimension: float
+
+
+class CircularWellDefinition(TypedDict):
+    shape: Circular
+    depth: float
+    totalLiquidVolume: float
+    x: float
+    y: float
+    z: float
+    diameter: float
+
+
+class RectangularWellDefinition(TypedDict):
+    shape: Rectangular
+    depth: float
+    totalLiquidVolume: float
+    x: float
+    y: float
+    z: float
+    xDimension: float
+    yDimension: float
+
+
+WellDefinition = Union[CircularWellDefinition, RectangularWellDefinition]
+
+
+class WellGroupMetadata(TypedDict, total=False):
+    displayName: str
+    displayCategory: LabwareDisplayCategory
+    wellBottomShape: Union[Literal["flat"], Literal["u"], Literal["v"]]
+
+
+class WellGroup(TypedDict, total=False):
+    wells: List[str]
+    metadata: WellGroupMetadata
+    brand: LabwareBrandData
+
+
+class _RequiredLabwareDefinition(TypedDict):
+    schemaVersion: Literal[2]
+    version: int
+    namespace: str
+    metadata: LabwareMetadata
+    brand: LabwareBrandData
+    parameters: LabwareParameters
+    cornerOffsetFromSlot: NamedOffset
+    ordering: List[List[str]]
+    dimensions: LabwareDimensions
+    wells: Dict[str, WellDefinition]
+    groups: List[WellGroup]
+
+
+class LabwareDefinition(_RequiredLabwareDefinition, total=False):
+    stackingOffsetWithLabware: Dict[str, NamedOffset]
+    stackingOffsetWithModule: Dict[str, NamedOffset]
+    allowedRoles: List[LabwareRoles]
+    gripperOffsets: Dict[str, GripperOffsets]
+    gripForce: float
+    gripHeightFromLabwareBottom: float

package/python/opentrons_shared_data/labware/labware_definition.py

@@ -0,0 +1,328 @@
+"""
+This was initially generated by datamodel-codegen from the labware schema in
+shared-data. It's been modified by hand to be more friendly.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Dict, List, Optional, Union
+
+from pydantic import (
+    BaseModel,
+    Extra,
+    Field,
+    conint,
+    confloat,
+    StrictInt,
+    StrictFloat,
+)
+from typing_extensions import Literal
+
+SAFE_STRING_REGEX = "^[a-z0-9._]+$"
+
+
+if TYPE_CHECKING:
+    _StrictNonNegativeInt = int
+    _StrictNonNegativeFloat = float
+else:
+    _StrictNonNegativeInt = conint(strict=True, ge=0)
+    _StrictNonNegativeFloat = confloat(strict=True, ge=0.0)
+
+
+_Number = Union[StrictInt, StrictFloat]
+"""JSON number type, written to preserve lack of decimal point.
+
+For labware definition hashing, which is an older part of the codebase,
+this ensures that Pydantic won't change `"someFloatField: 0` to
+`"someFloatField": 0.0`, which would hash differently.
+"""
+
+_NonNegativeNumber = Union[_StrictNonNegativeInt, _StrictNonNegativeFloat]
+"""Non-negative JSON number type, written to preserve lack of decimal point."""
+
+
+class CornerOffsetFromSlot(BaseModel):
+    """
+    Distance from left-front-bottom corner of slot to left-front-bottom corner
+     of labware bounding box. Used for labware that spans multiple slots. For
+      labware that does not span multiple slots, x/y/z should all be zero.
+    """
+
+    x: _Number
+    y: _Number
+    z: _Number
+
+
+class OverlapOffset(BaseModel):
+    """
+    Overlap dimensions of labware with another labware/module that it can be stacked on top of.
+    """
+
+    x: _Number
+    y: _Number
+    z: _Number
+
+
+class OffsetVector(BaseModel):
+    """
+    A generic 3-D offset vector.
+    """
+
+    x: _Number
+    y: _Number
+    z: _Number
+
+
+class GripperOffsets(BaseModel):
+    """
+    Offsets used when calculating coordinates for gripping labware during labware movement.
+    """
+
+    pickUpOffset: OffsetVector
+    dropOffset: OffsetVector
+
+
+class BrandData(BaseModel):
+    brand: str = Field(..., description="Brand/manufacturer name")
+    brandId: Optional[List[str]] = Field(
+        None,
+        description="An array of manufacture numbers pertaining to a given labware",
+    )
+    links: Optional[List[str]] = Field(
+        None, description="URLs for manufacturer page(s)"
+    )
+
+
+class DisplayCategory(str, Enum):
+    tipRack = "tipRack"
+    tubeRack = "tubeRack"
+    reservoir = "reservoir"
+    trash = "trash"
+    wellPlate = "wellPlate"
+    aluminumBlock = "aluminumBlock"
+    adapter = "adapter"
+    other = "other"
+
+
+class LabwareRole(str, Enum):
+    labware = "labware"
+    fixture = "fixture"
+    adapter = "adapter"
+    maintenance = "maintenance"
+
+
+class Metadata(BaseModel):
+    """
+    Properties used for search and display
+    """
+
+    displayName: str = Field(..., description="Easy to remember name of labware")
+    displayCategory: DisplayCategory = Field(
+        ..., description="Label(s) used in UI to categorize labware"
+    )
+    displayVolumeUnits: Literal["µL", "mL", "L"] = Field(
+        ..., description="Volume units for display"
+    )
+    tags: Optional[List[str]] = Field(
+        None, description="List of descriptions for a given labware"
+    )
+
+
+class Parameters(BaseModel):
+    """
+    Internal describers used to determine pipette movement to labware
+    """
+
+    format: Literal[
+        "96Standard", "384Standard", "trough", "irregular", "trash"
+    ] = Field(
+        ..., description="Property to determine compatibility with multichannel pipette"
+    )
+    quirks: Optional[List[str]] = Field(
+        None,
+        description="Property to classify a specific behavior this labware "
+        "should have",
+    )
+    isTiprack: bool = Field(
+        ..., description="Flag marking whether a labware is a tiprack or not"
+    )
+    tipLength: Optional[_NonNegativeNumber] = Field(
+        None,
+        description="Required if labware is tiprack, specifies length of tip"
+        " from drawing or as measured with calipers",
+    )
+    tipOverlap: Optional[_NonNegativeNumber] = Field(
+        None,
+        description="Required if labware is tiprack, specifies the length of "
+        "the area of the tip that overlaps the nozzle of the pipette",
+    )
+    loadName: str = Field(
+        ...,
+        description="Name used to reference a labware definition",
+        regex=SAFE_STRING_REGEX,
+    )
+    isMagneticModuleCompatible: bool = Field(
+        ...,
+        description="Flag marking whether a labware is compatible by default "
+        "with the Magnetic Module",
+    )
+    magneticModuleEngageHeight: Optional[_NonNegativeNumber] = Field(
+        None, description="Distance to move magnetic module magnets to engage"
+    )
+
+
+class Dimensions(BaseModel):
+    """
+    Outer dimensions of a labware
+    """
+
+    yDimension: _NonNegativeNumber = Field(...)
+    zDimension: _NonNegativeNumber = Field(...)
+    xDimension: _NonNegativeNumber = Field(...)
+
+
+class WellDefinition(BaseModel):
+    class Config:
+        extra = Extra.allow
+
+    depth: _NonNegativeNumber = Field(...)
+    x: _NonNegativeNumber = Field(
+        ...,
+        description="x location of center-bottom of well in reference to "
+        "left-front-bottom of labware",
+    )
+    y: _NonNegativeNumber = Field(
+        ...,
+        description="y location of center-bottom of well in reference to "
+        "left-front-bottom of labware",
+    )
+    z: _NonNegativeNumber = Field(
+        ...,
+        description="z location of center-bottom of well in reference to "
+        "left-front-bottom of labware",
+    )
+    totalLiquidVolume: _NonNegativeNumber = Field(
+        ..., description="Total well, tube, or tip volume in microliters"
+    )
+    xDimension: Optional[_NonNegativeNumber] = Field(
+        None,
+        description="x dimension of rectangular wells",
+    )
+    yDimension: Optional[_NonNegativeNumber] = Field(
+        None,
+        description="y dimension of rectangular wells",
+    )
+    diameter: Optional[_NonNegativeNumber] = Field(
+        None,
+        description="diameter of circular wells",
+    )
+    shape: Literal["rectangular", "circular"] = Field(
+        ...,
+        description="If 'rectangular', use xDimension and "
+        "yDimension; if 'circular' use diameter",
+    )
+
+
+class Metadata1(BaseModel):
+    """
+    Metadata specific to a grid of wells in a labware
+    """
+
+    displayName: Optional[str] = Field(
+        None, description="User-readable name for the well group"
+    )
+    displayCategory: Optional[DisplayCategory] = Field(
+        None, description="Label(s) used in UI to categorize well groups"
+    )
+    wellBottomShape: Optional[Literal["flat", "u", "v"]] = Field(
+        None, description="Bottom shape of the well for UI purposes"
+    )
+
+
+class Group(BaseModel):
+    wells: List[str] = Field(
+        ..., description="An array of wells that contain the same metadata"
+    )
+    metadata: Metadata1 = Field(
+        ..., description="Metadata specific to a grid of wells in a labware"
+    )
+    brand: Optional[BrandData] = Field(
+        None, description="Brand data for the well group (e.g. for tubes)"
+    )
+
+
+class LabwareDefinition(BaseModel):
+    schemaVersion: Literal[1, 2] = Field(
+        ..., description="Which schema version a labware is using"
+    )
+    version: int = Field(
+        ...,
+        description="Version of the labware definition itself "
+        "(eg myPlate v1/v2/v3). An incrementing integer",
+        ge=1.0,
+    )
+    namespace: str = Field(..., regex=SAFE_STRING_REGEX)
+    metadata: Metadata = Field(
+        ..., description="Properties used for search and display"
+    )
+    brand: BrandData = Field(
+        ...,
+        description="Real-world labware that the definition is modeled "
+        "from and/or compatible with",
+    )
+    parameters: Parameters = Field(
+        ...,
+        description="Internal describers used to determine pipette movement "
+        "to labware",
+    )
+    ordering: List[List[str]] = Field(
+        ...,
+        description="Generated array that keeps track of how wells should be "
+        "ordered in a labware",
+    )
+    cornerOffsetFromSlot: CornerOffsetFromSlot = Field(
+        ...,
+        description="Distance from left-front-bottom corner of slot to "
+        "left-front-bottom corner of labware bounding box. Used for "
+        "labware that spans multiple slots. For labware that does "
+        "not span multiple slots, x/y/z should all be zero.",
+    )
+    dimensions: Dimensions = Field(..., description="Outer dimensions of a labware")
+    wells: Dict[str, WellDefinition] = Field(
+        ...,
+        description="Unordered object of well objects with position and "
+        "dimensional information",
+    )
+    groups: List[Group] = Field(
+        ...,
+        description="Logical well groupings for metadata/display purposes; "
+        "changes in groups do not affect protocol execution",
+    )
+    allowedRoles: List[LabwareRole] = Field(
+        default_factory=list,
+        description="Allowed behaviors and usage of a labware in a protocol.",
+    )
+    stackingOffsetWithLabware: Dict[str, OverlapOffset] = Field(
+        default_factory=dict,
+        description="Supported labware that can be stacked upon,"
+        " with overlap vector offset between both labware.",
+    )
+    stackingOffsetWithModule: Dict[str, OverlapOffset] = Field(
+        default_factory=dict,
+        description="Supported module that can be stacked upon,"
+        " with overlap vector offset between labware and module.",
+    )
+    gripperOffsets: Dict[str, GripperOffsets] = Field(
+        default_factory=dict,
+        description="Offsets use when calculating coordinates for gripping labware "
+        "during labware movement.",
+    )
+    gripHeightFromLabwareBottom: Optional[float] = Field(
+        default_factory=None,
+        description="The Z-height, from labware bottom, where the gripper should grip the labware.",
+    )
+    gripForce: Optional[float] = Field(
+        default_factory=None,
+        description="Force, in Newtons, with which the gripper should grip the labware.",
+    )