lab-compiler 0.1.0__py3-none-any.whl

lab/__init__.py

@@ -0,0 +1,23 @@
+"""Build and compile laboratory protocols using ordinary Python."""
+
+from lab._version import __version__
+from lab.compiler import Compilation, compile
+from lab.protocol import Plate, Protocol, Well
+from lab.units import Quantity, celsius, minutes, mL, seconds, uL
+from lab.validation import CompileError
+
+__all__ = [
+    "Compilation",
+    "CompileError",
+    "Plate",
+    "Protocol",
+    "Quantity",
+    "Well",
+    "__version__",
+    "celsius",
+    "compile",
+    "mL",
+    "minutes",
+    "seconds",
+    "uL",
+]

lab/_version.py

@@ -0,0 +1,3 @@
+"""Package version shared by the public API and compiler."""
+
+__version__ = "0.1.0"

lab/compiler.py

@@ -0,0 +1,133 @@
+"""Snapshot, validate, prepare a target, and emit a self-contained bundle."""
+
+import hashlib
+import json
+from dataclasses import dataclass, replace
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+from typing import Protocol as Interface
+
+import lab.documents as documents
+from lab._version import __version__
+from lab.deck import Deck
+from lab.model import Distribute, Location, Mix, RecordedProtocol, TargetPlan, Transfer, encode
+from lab.protocol import Protocol
+from lab.targets.liquid_handler import LiquidHandler
+from lab.targets.lower import lower_deck
+from lab.validation import CompileError, logical_bindings, validate
+
+
+class Target(Interface):
+    def prepare(self, protocol: RecordedProtocol) -> TargetPlan: ...
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2, allow_nan=False) + "\n"
+
+
+@dataclass(frozen=True)
+class Compilation:
+    protocol: RecordedProtocol
+    target: TargetPlan
+    final_volumes: tuple[tuple[Location, Decimal], ...]
+
+    @property
+    def plan_json(self) -> str:
+        return canonical_json(
+            {
+                "format": "lab.plan.v1",
+                "compiler_version": __version__,
+                "units": {"volume": "microliter", "duration": "second", "temperature": "celsius"},
+                "protocol": encode(self.protocol),
+                "target": {
+                    "name": self.target.name,
+                    "configuration": json.loads(self.target.configuration_json),
+                    "bindings": encode(self.target.bindings),
+                    "setup": list(self.target.setup),
+                },
+                "final_volumes": [
+                    {"location": encode(location), "volume": encode(volume)}
+                    for location, volume in self.final_volumes
+                ],
+                "source_sha256": (
+                    hashlib.sha256(self.target.source.encode()).hexdigest()
+                    if self.target.source is not None
+                    else None
+                ),
+            }
+        )
+
+    @property
+    def digest(self) -> str:
+        return hashlib.sha256(self.plan_json.encode()).hexdigest()
+
+    @property
+    def files(self) -> dict[str, str]:
+        result = {"plan.json": self.plan_json, "protocol.html": documents.render(self)}
+        if self.target.source is not None:
+            result["protocol.py"] = self.target.source
+        return result
+
+    def write(self, directory: str | Path) -> Path:
+        """Write a bundle. Refuse to replace any different existing artifact."""
+        directory = Path(directory)
+        files = self.files
+        for name, text in files.items():
+            path = directory / name
+            if path.exists() and path.read_text() != text:
+                raise FileExistsError(f"{path} already contains a different artifact")
+        directory.mkdir(parents=True, exist_ok=True)
+        for name, text in files.items():
+            (directory / name).write_text(text, encoding="utf-8")
+        return directory
+
+
+def compile(
+    protocol: Protocol, hardware: Target | Deck, *, liquid_handler: LiquidHandler | None = None
+) -> Compilation:
+    """Compile offline for one piece of hardware.
+
+    A ``Deck`` contains shared requirements and optional Lab-owned layouts. The
+    selected backend validates and translates its layout or supported preset.
+    Concrete backend targets are also accepted for low-level integrations.
+    A document target such as ``Manual()`` has no robot, so ``liquid_handler`` is omitted.
+    """
+    authored_deck = hardware if isinstance(hardware, Deck) else None
+    if isinstance(hardware, Deck):
+        if not isinstance(liquid_handler, LiquidHandler):
+            raise TypeError(
+                "Pass liquid_handler=LiquidHandler.OT2, LiquidHandler.FLEX, or LiquidHandler.STAR."
+            )
+        liquid = tuple(
+            step.volume for step in protocol.steps if isinstance(step, (Transfer, Mix, Distribute))
+        )
+        requirements = {container.id: container.labware for container in hardware.containers}
+        for resource in protocol.snapshot().resources:
+            spec = requirements.get(resource.name)
+            if spec is None or (spec.rows, spec.columns) != (resource.rows, resource.columns):
+                raise CompileError(
+                    f"Deck requirements must match the protocol geometry for {resource.name}."
+                )
+            if resource.capacity > spec.capacity_ul:
+                raise CompileError(f"Protocol capacity exceeds the deck limit for {resource.name}.")
+        hardware = lower_deck(hardware, liquid_handler, liquid)
+    declared = getattr(hardware, "liquid_handler", None)
+    if isinstance(declared, LiquidHandler) and liquid_handler != declared:
+        raise TypeError(
+            f"This hardware is LiquidHandler.{declared.name}. "
+            f"Pass liquid_handler=LiquidHandler.{declared.name}."
+        )
+    if liquid_handler is not None and not isinstance(declared, LiquidHandler):
+        raise TypeError("This hardware does not name a LiquidHandler.")
+    if liquid_handler is not None and not isinstance(liquid_handler, LiquidHandler):
+        raise TypeError("Pass LiquidHandler.OT2, LiquidHandler.FLEX, or LiquidHandler.STAR.")
+    recorded = protocol.snapshot()
+    validate(recorded, logical_bindings(recorded))
+    prepared = hardware.prepare(recorded)
+    if authored_deck is not None:
+        configuration = json.loads(prepared.configuration_json)
+        configuration["lab_deck"] = encode(authored_deck)
+        prepared = replace(prepared, configuration_json=json.dumps(configuration, sort_keys=True))
+    volumes = validate(recorded, prepared.bindings)
+    return Compilation(recorded, prepared, tuple(volumes.items()))

lab/deck.py

@@ -0,0 +1,311 @@
+"""Logical containers and Lab-owned physical layouts for liquid handlers."""
+
+from dataclasses import dataclass
+from decimal import Decimal
+from enum import Enum
+from typing import Any
+
+from lab.equipment import (
+    CARRIER_SITE_COUNTS,
+    MODULE_SITE_COUNTS,
+    CarrierModel,
+    LabwareModel,
+    LiquidHandler,
+    ModuleModel,
+    Mount,
+    PipetteModel,
+    TipRackModel,
+)
+from lab.labware import ContainerSpec, LabwareKind
+
+
+class DeckSite(Enum):
+    """Logical placement groups used by built-in layout presets."""
+
+    TEMPERATURE_MODULE = "temperature_module"
+    THERMOCYCLER = "thermocycler"
+    PLATES = "plates"
+    MORE_PLATES = "more_plates"
+    TUBE_RACK = "tube_rack"
+    RESERVOIR = "reservoir"
+
+
+_COMPATIBLE_KINDS = {
+    DeckSite.TEMPERATURE_MODULE: frozenset({LabwareKind.COLD_BLOCK}),
+    DeckSite.THERMOCYCLER: frozenset({LabwareKind.PCR_PLATE, LabwareKind.CULTURE_PLATE}),
+    DeckSite.PLATES: frozenset({LabwareKind.PLATE, LabwareKind.PCR_PLATE}),
+    DeckSite.MORE_PLATES: frozenset({LabwareKind.PLATE, LabwareKind.PCR_PLATE}),
+    DeckSite.TUBE_RACK: frozenset({LabwareKind.TUBE_RACK}),
+    DeckSite.RESERVOIR: frozenset({LabwareKind.CONICAL_RACK}),
+}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Container(ContainerSpec):
+    """A named container assigned to a logical placement group.
+
+    ``DeckSite.PLATES`` and ``DeckSite.MORE_PLATES`` are the two open-deck plate
+    runs. ``DeckSite.TUBE_RACK`` and ``DeckSite.RESERVOIR`` are the holder and the
+    large-volume rack. Explicit layouts specify the actual holders and devices.
+    """
+
+    site: DeckSite
+
+    def __post_init__(self) -> None:
+        ContainerSpec.__post_init__(self)
+        if not isinstance(self.site, DeckSite):
+            raise TypeError("Container site must be a DeckSite member.")
+        if self.labware.kind not in _COMPATIBLE_KINDS[self.site]:
+            raise ValueError(f"A {self.labware.kind.value} cannot sit on {self.site.value}.")
+
+
+def _name(value: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError("Equipment and container identifiers must be nonempty text.")
+
+
+def _tuple(values: tuple[Any, ...], member: type, label: str) -> None:
+    if not isinstance(values, tuple) or any(not isinstance(value, member) for value in values):
+        raise TypeError(f"{label} must be a tuple of {member.__name__} objects.")
+
+
+@dataclass(frozen=True, slots=True)
+class Slot:
+    name: str
+
+    def __post_init__(self) -> None:
+        _name(self.name)
+
+
+@dataclass(frozen=True, slots=True)
+class Rail:
+    index: int
+
+    def __post_init__(self) -> None:
+        if type(self.index) is not int or self.index < 1:
+            raise ValueError("Rail index must be a positive integer.")
+
+
+@dataclass(frozen=True, slots=True)
+class HolderSite:
+    holder: str
+    index: int = 0
+
+    def __post_init__(self) -> None:
+        _name(self.holder)
+        if type(self.index) is not int or self.index < 0:
+            raise ValueError("Holder site index must be a nonnegative integer.")
+
+
+Position = Slot | Rail | HolderSite
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Carrier:
+    id: str
+    model: CarrierModel
+    location: Position
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Module:
+    id: str
+    model: ModuleModel
+    location: Position
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TipRack:
+    id: str
+    model: TipRackModel
+    location: Position
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Placement:
+    """Bind a logical container to a physical model and location in a layout.
+
+    ``wells`` optionally lists physical well names in logical row-major order.
+    """
+
+    container: str
+    model: LabwareModel
+    location: Position
+    wells: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Pipette:
+    model: PipetteModel
+    mount: Mount
+    tip_racks: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Channel:
+    """An independently addressable channel; limits are in microliters."""
+
+    index: int
+    min_volume_ul: Decimal
+    max_volume_ul: Decimal
+    tip_racks: tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeckLayout:
+    """A physical configuration expressed entirely in Lab types.
+
+    Targets validate supported equipment, positions, footprints, and capabilities.
+    External thermal resources explicitly require a runtime device handoff.
+    """
+
+    liquid_handler: LiquidHandler
+    placements: tuple[Placement, ...]
+    carriers: tuple[Carrier, ...] = ()
+    modules: tuple[Module, ...] = ()
+    tip_racks: tuple[TipRack, ...] = ()
+    pipettes: tuple[Pipette, ...] = ()
+    channels: tuple[Channel, ...] = ()
+    external_thermal_resources: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.liquid_handler, LiquidHandler):
+            raise TypeError("A layout requires a LiquidHandler member.")
+        for values, member in (
+            (self.placements, Placement),
+            (self.carriers, Carrier),
+            (self.modules, Module),
+            (self.tip_racks, TipRack),
+            (self.pipettes, Pipette),
+            (self.channels, Channel),
+        ):
+            _tuple(values, member, member.__name__)
+        equipment: tuple[Carrier | Module | TipRack, ...] = (
+            *self.carriers,
+            *self.modules,
+            *self.tip_racks,
+        )
+        ids = [item.id for item in equipment]
+        for identifier in ids:
+            _name(identifier)
+        if len(set(ids)) != len(ids):
+            raise ValueError("Layout equipment ids must be unique.")
+        containers = [item.container for item in self.placements]
+        for identifier in containers:
+            _name(identifier)
+        if len(set(containers)) != len(containers):
+            raise ValueError("Each container needs exactly one placement in a layout.")
+        if set(ids) & set(containers):
+            raise ValueError("Equipment and container ids must be distinct.")
+        for values, model_type in (
+            (self.carriers, CarrierModel),
+            (self.modules, ModuleModel),
+            (self.tip_racks, TipRackModel),
+            (self.placements, LabwareModel),
+        ):
+            for model_item in values:
+                if not isinstance(model_item.model, model_type):
+                    raise TypeError(f"Use a {model_type.__name__} member.")
+        holder_items: tuple[Carrier | Module, ...] = (*self.carriers, *self.modules)
+        holders = {item.id: item for item in holder_items}
+        occupied: set[Position] = set()
+        positioned: tuple[Carrier | Module | TipRack | Placement, ...] = (
+            *equipment,
+            *self.placements,
+        )
+        for item in positioned:
+            position = item.location
+            if not isinstance(position, (Slot, Rail, HolderSite)):
+                raise TypeError("A location must be a Slot, Rail, or HolderSite.")
+            if position in occupied:
+                raise ValueError(f"Layout location {position!r} is occupied more than once.")
+            occupied.add(position)
+            if isinstance(position, HolderSite):
+                if position.holder not in holders:
+                    raise ValueError(f"Unknown holder {position.holder!r}.")
+                holder = holders[position.holder]
+                limit = (
+                    CARRIER_SITE_COUNTS[holder.model]
+                    if isinstance(holder, Carrier)
+                    else MODULE_SITE_COUNTS[holder.model]
+                )
+                if position.index >= limit:
+                    raise ValueError(f"Holder {position.holder!r} has {limit} sites.")
+        # Reject cycles even when holders were declared in a different order.
+        for holder in holders.values():
+            seen = {holder.id}
+            position = holder.location
+            while isinstance(position, HolderSite):
+                if position.holder in seen:
+                    raise ValueError("Layout holder relationships must not contain a cycle.")
+                seen.add(position.holder)
+                position = holders[position.holder].location
+        for placement in self.placements:
+            _tuple(placement.wells, str, "Physical wells")
+            if len(set(placement.wells)) != len(placement.wells):
+                raise ValueError("Physical well mappings must be unique.")
+            for well in placement.wells:
+                _name(well)
+        tips = {rack.id for rack in self.tip_racks}
+        assigned: set[str] = set()
+        heads: tuple[Pipette | Channel, ...] = (*self.pipettes, *self.channels)
+        for head in heads:
+            _tuple(head.tip_racks, str, "Head tip racks")
+            if not head.tip_racks or any(rack not in tips for rack in head.tip_racks):
+                raise ValueError("Every pipette or channel needs declared tip racks.")
+            if len(set(head.tip_racks)) != len(head.tip_racks):
+                raise ValueError("A head's tip rack list must not contain duplicates.")
+            assigned.update(head.tip_racks)
+        if assigned != tips:
+            raise ValueError("Every tip rack must be assigned to a pipette or channel.")
+        for pipette in self.pipettes:
+            if not isinstance(pipette.model, PipetteModel) or not isinstance(pipette.mount, Mount):
+                raise TypeError("Use PipetteModel and Mount members.")
+        if len({pipette.mount for pipette in self.pipettes}) != len(self.pipettes):
+            raise ValueError("Pipette mounts must be unique.")
+        for channel in self.channels:
+            if type(channel.index) is not int or channel.index < 0:
+                raise ValueError("Channel index must be a nonnegative integer.")
+            limits = (channel.min_volume_ul, channel.max_volume_ul)
+            if any(not isinstance(v, Decimal) or not v.is_finite() or v <= 0 for v in limits):
+                raise ValueError("Channel volume limits must be positive finite Decimals.")
+            if channel.min_volume_ul > channel.max_volume_ul:
+                raise ValueError("Channel minimum volume exceeds maximum volume.")
+        if len({channel.index for channel in self.channels}) != len(self.channels):
+            raise ValueError("Channel indices must be unique.")
+        _tuple(self.external_thermal_resources, str, "External thermal resources")
+        if not set(self.external_thermal_resources) <= set(containers):
+            raise ValueError("External thermal resources must name placed containers.")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Deck:
+    """Shared container requirements with optional physical layouts for each handler."""
+
+    containers: tuple[ContainerSpec, ...]
+    layouts: tuple[DeckLayout, ...] = ()
+
+    def __post_init__(self) -> None:
+        _tuple(self.containers, ContainerSpec, "Deck containers")
+        _tuple(self.layouts, DeckLayout, "Deck layouts")
+        if not self.containers:
+            raise ValueError("A deck needs at least one container.")
+        ids = [container.id for container in self.containers]
+        if len(ids) != len(set(ids)):
+            raise ValueError("Deck container ids must be unique.")
+        handlers = [layout.liquid_handler for layout in self.layouts]
+        if len(set(handlers)) != len(handlers):
+            raise ValueError("A deck can have only one layout per liquid handler.")
+        specs = {container.id: container.labware for container in self.containers}
+        for layout in self.layouts:
+            if {placement.container for placement in layout.placements} != set(ids):
+                raise ValueError("Each layout must place exactly the deck's containers.")
+            for placement in layout.placements:
+                spec = specs[placement.container]
+                if placement.wells and len(placement.wells) != spec.rows * spec.columns:
+                    raise ValueError("A physical well mapping must cover every logical well.")
+
+    def layout_for(self, liquid_handler: LiquidHandler) -> DeckLayout | None:
+        return next(
+            (layout for layout in self.layouts if layout.liquid_handler == liquid_handler), None
+        )

lab/documents.py

@@ -0,0 +1,129 @@
+"""A printable document rendered from the same frozen data as robot code."""
+
+from html import escape
+from typing import Any
+
+from lab.model import (
+    Distribute,
+    ManualInstruction,
+    Mix,
+    SetTemperature,
+    Step,
+    Thermocycle,
+    Transfer,
+    Wait,
+)
+from lab.units import number
+
+
+def describe(step: Step) -> str:
+    match step:
+        case Transfer(source, destination, volume, _):
+            return f"Transfer {number(volume)} µL from {source} to {destination}."
+        case Distribute(source, destinations, volume, air_gap, _):
+            wells = ", ".join(str(destination) for destination in destinations)
+            gap = f" Air gap {number(air_gap)} µL." if air_gap is not None else ""
+            return f"Distribute {number(volume)} µL from {source} to {wells}.{gap}"
+        case Mix(location, volume, cycles, _):
+            return f"Mix {location}: {cycles} cycles of {number(volume)} µL."
+        case Wait(seconds, _):
+            unit = "second" if seconds == 1 else "seconds"
+            return f"Wait {number(seconds)} {unit}."
+        case Thermocycle(resource, profile, cycles, lid, _, block_volume):
+            holds = "; ".join(
+                f"{number(hold.celsius)} °C for {number(hold.seconds)} s" for hold in profile
+            )
+            lid_text = "unheated lid" if lid is None else f"lid at {number(lid)} °C"
+            block = (
+                f" Reported block volume {number(block_volume)} µL."
+                if block_volume is not None
+                else ""
+            )
+            return (
+                f"Thermocycle all of {resource}: {holds}; {cycles} cycle(s); {lid_text}. "
+                "Wait for completion, turn off temperature control, and release the plate."
+                f"{block}"
+            )
+        case SetTemperature(resource, celsius, _):
+            return f"Hold {resource} at {number(celsius)} °C."
+        case ManualInstruction(text, _):
+            return f"Operator: {text}"
+        case _:
+            raise TypeError(f"Unsupported step: {type(step).__name__}")
+
+
+def render(compilation: Any) -> str:
+    p, target = compilation.protocol, compilation.target
+    bindings = {binding.location: binding for binding in target.bindings}
+    resources = []
+    for resource in p.resources:
+        fills = (
+            "; ".join(
+                f"{fill.well}: {fill.material}, {number(fill.volume)} µL" for fill in resource.fills
+            )
+            or "Initially empty"
+        )
+        locations = [
+            binding.physical
+            for location, binding in bindings.items()
+            if location.resource == resource.name
+        ]
+        physical = (
+            ", ".join(locations)
+            if len(locations) <= 4
+            else f"{locations[0]} … {locations[-1]} ({len(locations)} wells; see plan.json)"
+        )
+        resources.append(
+            f"<tr><th>{escape(resource.name)}</th><td>{escape(fills)}</td>"
+            f"<td class='locations'>{escape(physical)}</td></tr>"
+        )
+    steps = "".join(f"<li><p>{escape(describe(step))}</p></li>" for step in p.steps)
+    setup = (
+        "<h2>Equipment setup</h2><ul>"
+        + "".join(f"<li>{escape(line)}</li>" for line in target.setup)
+        + "</ul>"
+        if target.setup
+        else ""
+    )
+    totals = "".join(
+        f"<tr><th>{escape(str(location))}</th><td>{number(volume)} µL</td></tr>"
+        for location, volume in compilation.final_volumes
+        if volume
+    )
+    return f"""<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{escape(p.name)}</title>
+<style>
+:root {{ color-scheme: light; font-family: system-ui, sans-serif; color: #18312f; }}
+body {{ max-width: 920px; padding: 56px 28px; margin: auto; line-height: 1.6; }}
+header {{ border-top: 5px solid #25756a; padding-top: 24px; margin-bottom: 36px; }}
+h1 {{ font-size: clamp(2rem, 5vw, 3rem); letter-spacing: -.035em; margin: 6px 0; }}
+h2 {{ margin-top: 36px; font-size: 1.2rem; }}
+.eyebrow, small {{ color: #60736e; }}
+.eyebrow {{ text-transform: uppercase; letter-spacing: .1em; }}
+table {{ width: 100%; border-collapse: collapse; font-size: .9rem; }}
+th, td {{ text-align: left; vertical-align: top; border-bottom: 1px solid #dbe5e1; padding: 12px; }}
+.locations {{ overflow-wrap: anywhere; }} ol {{ padding-left: 28px; }}
+li {{ padding: 8px 0 16px 12px; border-bottom: 1px solid #e3ebe7; break-inside: avoid; }}
+li p {{ margin: 0; }} small, code {{ overflow-wrap: anywhere; }}
+.note {{ padding: 16px; background: #f0f5f2; border-radius: 8px; }}
+footer {{ margin-top: 40px; font-size: .8rem; color: #60736e; }}
+@media (max-width: 600px) {{ body {{ padding: 24px 16px; }} th, td {{ padding: 8px 4px; }} }}
+@media print {{ body {{ padding: 0; font-size: 10pt; }} header {{ margin-bottom: 16px; }}
+small {{ display: none; }} h2 {{ break-after: avoid; }} tr {{ break-inside: avoid; }} }}
+</style></head><body>
+<header><div class="eyebrow">Lab / Compiled protocol</div>
+<h1>{escape(p.name)}</h1><p>{escape(p.description)}</p>
+<p>Target: <strong>{escape(target.name)}</strong></p></header>
+<p class="note">Planned quantities. Use a fresh tip for each transfer or mix.</p>
+{setup}
+<h2>Materials and placement</h2><table><thead><tr>
+<th>Resource</th><th>Declared initial contents</th>
+<th>Physical locations</th></tr></thead><tbody>{"".join(resources)}</tbody></table>
+<h2>Procedure</h2><ol>{steps}</ol>
+<h2>Calculated final contents</h2><table>{totals}</table>
+<footer>Plan {compilation.digest}<br>Quantities are in microlitres unless stated otherwise.
+Inspect plan.json for complete bindings and target configuration.</footer>
+</body></html>
+"""

lab/equipment.py

@@ -0,0 +1,64 @@
+"""Lab-owned equipment identifiers. Backends resolve these to SDK definitions."""
+
+from enum import Enum
+
+
+class LiquidHandler(Enum):
+    OT2 = "ot2"
+    FLEX = "flex"
+    STAR = "star"
+
+
+class LabwareModel(Enum):
+    CORNING_96_360_UL = "corning_96_360_ul"
+    NEST_12_RESERVOIR_15_ML = "nest_12_reservoir_15_ml"
+    NEST_96_PCR_100_UL = "nest_96_pcr_100_ul"
+    OPENTRONS_96_PCR_200_UL = "opentrons_96_pcr_200_ul"
+    BIORAD_96_PCR_200_UL = "biorad_96_pcr_200_ul"
+    AZENTA_96_PCR_200_UL = "azenta_96_pcr_200_ul"
+    OPENTRONS_24_COLD_BLOCK = "opentrons_24_cold_block"
+    OPENTRONS_24_TUBE_RACK = "opentrons_24_tube_rack"
+    OPENTRONS_15_CONICAL_RACK = "opentrons_15_conical_rack"
+
+
+class CarrierModel(Enum):
+    HAMILTON_PLATE_5 = "hamilton_plate_5"
+    HAMILTON_TIP_5 = "hamilton_tip_5"
+
+
+class ModuleModel(Enum):
+    TEMPERATURE_GEN1 = "temperature_gen1"
+    TEMPERATURE_GEN2 = "temperature_gen2"
+    THERMOCYCLER_GEN1 = "thermocycler_gen1"
+    THERMOCYCLER_GEN2 = "thermocycler_gen2"
+
+
+class TipRackModel(Enum):
+    OPENTRONS_20_UL = "opentrons_20_ul"
+    OPENTRONS_300_UL = "opentrons_300_ul"
+    FLEX_200_UL = "flex_200_ul"
+    HAMILTON_50_UL = "hamilton_50_ul"
+    HAMILTON_300_UL = "hamilton_300_ul"
+
+
+class PipetteModel(Enum):
+    P20_SINGLE_GEN2 = "p20_single_gen2"
+    P300_SINGLE_GEN2 = "p300_single_gen2"
+    FLEX_1CHANNEL_1000 = "flex_1channel_1000"
+
+
+class Mount(Enum):
+    LEFT = "left"
+    RIGHT = "right"
+
+
+CARRIER_SITE_COUNTS = {
+    CarrierModel.HAMILTON_PLATE_5: 5,
+    CarrierModel.HAMILTON_TIP_5: 5,
+}
+MODULE_SITE_COUNTS = {
+    ModuleModel.TEMPERATURE_GEN1: 1,
+    ModuleModel.TEMPERATURE_GEN2: 1,
+    ModuleModel.THERMOCYCLER_GEN1: 1,
+    ModuleModel.THERMOCYCLER_GEN2: 1,
+}

lab/experiments/__init__.py

@@ -0,0 +1,7 @@
+"""Experiment families built on the protocol operations.
+
+A family is a package of ordinary functions. Each stage lays out wells, then
+appends steps to a caller-owned protocol. Cloning is :mod:`lab.experiments.cloning`.
+Add another kind of experiment as a sibling package, and add another stage of
+cloning as a module in :mod:`lab.experiments.cloning.stages`. Stages are not registered.
+"""