pyhte 0.1.0__py3-none-any.whl

hte/__init__.py

@@ -0,0 +1,46 @@
+"""High-throughput experiments and laboratory automation.
+
+The most used classes and functions can be imported directly from ``hte``, e.g. ``from hte import Plate``.
+"""
+__version__ = "0.1.0"
+
+from hte.chemistry.composition import Composition
+from hte.chemistry.substances import Substance
+from hte.designs.titrations import TitrationDesign, TitrationSeries
+from hte.devices.jasco import V750
+from hte.devices.ukrobotics import D2
+from hte.exceptions import HTEError, ValidationError
+from hte.execution.records import Run, actual_state
+from hte.execution.states import TransferStatus
+from hte.labware.containers import Container
+from hte.labware.layouts import PlateLayout
+from hte.labware.plates import Plate, PlateType, Well
+from hte.measurements.models import Measurement
+from hte.operations.plans import Plan
+from hte.operations.state import LabState
+from hte.operations.transfers import Transfer
+from hte.storage.database import Database
+
+__all__ = [
+    "Composition",
+    "Container",
+    "D2",
+    "Database",
+    "HTEError",
+    "LabState",
+    "Measurement",
+    "Plan",
+    "Plate",
+    "PlateLayout",
+    "PlateType",
+    "Run",
+    "Substance",
+    "TitrationDesign",
+    "TitrationSeries",
+    "Transfer",
+    "TransferStatus",
+    "V750",
+    "ValidationError",
+    "Well",
+    "actual_state",
+]

hte/chemistry/composition.py

@@ -0,0 +1,192 @@
+"""Contents of containers as solvent volumes and solute amounts."""
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+import math
+from types import MappingProxyType
+from typing import Self
+
+from hte.chemistry.substances import Substance
+from hte.exceptions import InsufficientVolumeError, ValidationError
+from hte.tolerances import exceeds
+
+
+def _add(first: Mapping[Substance, float], second: Mapping[Substance, float]) -> dict[Substance, float]:
+    total = dict(first)
+    for substance, quantity in second.items():
+        total[substance] = total.get(substance, 0.0) + quantity
+    return total
+
+
+@dataclass(frozen=True, repr=False)
+class Composition:
+    """Contents of a container: the volume of each solvent (L) and the amount of each solute (mol).
+
+    Solvent volumes add up on mixing. Solutes, including solids, are regarded as fully dissolved in the total solvent
+    volume. Compositions are immutable: mixing and splitting return new compositions.
+
+    Attributes
+    ----------
+    solvents
+        Volume of each solvent in L. Read-only; zero volumes are dropped.
+    solutes
+        Amount of each solute in mol. Read-only; zero amounts are dropped.
+
+    Raises
+    ------
+    ValidationError
+        If a volume or amount is negative or not finite.
+    """
+    solvents: Mapping[Substance, float] = field(default_factory=dict)
+    solutes: Mapping[Substance, float] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        for name, quantities in (("Solvent volumes", self.solvents), ("Solute amounts", self.solutes)):
+            if any(not math.isfinite(quantity) or quantity < 0 for quantity in quantities.values()):
+                raise ValidationError(f"{name} must be finite and non-negative")
+        # zero quantities are dropped, so an empty composition has no entries
+        object.__setattr__(self, "solvents", MappingProxyType({s: v for s, v in self.solvents.items() if v}))
+        object.__setattr__(self, "solutes", MappingProxyType({s: a for s, a in self.solutes.items() if a}))
+
+    @classmethod
+    def solution(
+        cls,
+        solvent: Substance,
+        volume: float,
+        concentrations: Mapping[Substance, float]|None = None,
+    ) -> Self:
+        """Create a solution in a single solvent from the concentrations of its solutes.
+
+        Parameters
+        ----------
+        solvent
+            The solvent.
+        volume
+            Volume of the solvent in L.
+        concentrations
+            Concentration of each solute in mol/L, relative to ``volume``. Without concentrations, the composition
+            contains the pure solvent.
+
+        Returns
+        -------
+        Composition
+            The solution.
+
+        Raises
+        ------
+        ValidationError
+            If the volume or a concentration is negative or not finite.
+        """
+        concentrations = concentrations or {}
+        if any(not math.isfinite(concentration) or concentration < 0 for concentration in concentrations.values()):
+            raise ValidationError("Concentrations must be finite and non-negative")
+        return cls(
+            solvents={solvent: volume},
+            solutes={substance: concentration*volume for substance, concentration in concentrations.items()},
+        )
+
+    @property
+    def volume(self) -> float:
+        """Total volume of all solvents in L."""
+        return sum(self.solvents.values())
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the composition contains neither solvent nor solute."""
+        return not self.solvents and not self.solutes
+
+    def concentration(self, substance: Substance) -> float:
+        """Return the concentration of a solute in the total solvent volume.
+
+        Parameters
+        ----------
+        substance
+            The solute.
+
+        Returns
+        -------
+        float
+            Concentration in mol/L; 0 if the substance is not a solute of the composition.
+
+        Raises
+        ------
+        ValidationError
+            If the substance is a solute but there is no solvent.
+        """
+        amount = self.solutes.get(substance, 0.0)
+        if not amount:
+            return 0.0
+        if not self.volume:
+            raise ValidationError(f"The concentration of {substance.name} is undefined without solvent")
+        return amount / self.volume
+
+    @property
+    def concentrations(self) -> dict[Substance, float]:
+        """Concentration of each solute in mol/L (see `concentration`)."""
+        return {substance: self.concentration(substance) for substance in self.solutes}
+
+    @property
+    def solvent_fractions(self) -> dict[Substance, float]:
+        """Volume fraction of each solvent (between 0 and 1)."""
+        volume = self.volume
+        return {solvent: solvent_volume/volume for solvent, solvent_volume in self.solvents.items()}
+
+    def mix(self, other: Self) -> Self:
+        """Combine both compositions, conserving the volume of each solvent and the amount of each solute.
+
+        Parameters
+        ----------
+        other
+            The composition to add.
+
+        Returns
+        -------
+        Composition
+            The mixture.
+        """
+        return type(self)(solvents=_add(self.solvents, other.solvents), solutes=_add(self.solutes, other.solutes))
+
+    def split(self, volume: float) -> tuple[Self, Self]:
+        """Divide off a volume of the homogeneous liquid.
+
+        Solvents and solutes are divided in proportion to the volume. If the volume is within floating point error of
+        the whole volume (see `.exceeds`), everything is taken, so that no residue is left behind.
+
+        Parameters
+        ----------
+        volume
+            Volume to divide off in L.
+
+        Returns
+        -------
+        tuple[Composition, Composition]
+            The portion and the remainder.
+
+        Raises
+        ------
+        ValidationError
+            If the volume is negative or not finite.
+        InsufficientVolumeError
+            If the volume exceeds the volume of the composition.
+        """
+        if not math.isfinite(volume) or volume < 0:
+            raise ValidationError("Volume must be finite and non-negative")
+        if exceeds(volume, self.volume):
+            raise InsufficientVolumeError(f"Cannot take {volume} L from {self.volume} L")
+        if not volume:
+            return type(self)(), self
+        if not exceeds(self.volume, volume):
+            # within floating point error of the whole volume: take everything rather than leave a residue
+            return self, type(self)()
+        fraction = volume/self.volume
+        return self._scale(fraction), self._scale(1.0 - fraction)
+
+    def _scale(self, factor: float) -> Self:
+        return type(self)(
+            solvents={solvent: volume*factor for solvent, volume in self.solvents.items()},
+            solutes={solute: amount*factor for solute, amount in self.solutes.items()},
+        )
+
+    def __repr__(self) -> str:
+        solvents = ", ".join(f"{solvent.name}: {volume:g} L" for solvent, volume in self.solvents.items())
+        solutes = ", ".join(f"{solute.name}: {amount:g} mol" for solute, amount in self.solutes.items())
+        return f"Composition(volume={self.volume:g} L, solvents={{{solvents}}}, solutes={{{solutes}}})"

hte/chemistry/substances.py

@@ -0,0 +1,142 @@
+"""Chemical substances and their identity."""
+from dataclasses import dataclass, field
+from functools import cached_property
+import math
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
+
+from hte.exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from rdkit.Chem import Mol
+
+
+@dataclass(frozen=True, eq=False, repr=False)
+class Substance:
+    """A chemical substance.
+
+    Substances with a structure (``mol``, requires RDKit) are compared by their InChIKey.
+    Substances without a structure are compared by their name (case-insensitive).
+    The two kinds never compare equal to each other.
+
+    The molar mass (g/mol) is inferred from the structure. Substances without a structure need an explicit molar mass
+    to convert between mass and amount.
+
+    Attributes
+    ----------
+    name
+        Name of the substance.
+    id
+        Unique id.
+    mol
+        Structure as RDKit molecule, or None.
+    molar_mass
+        Molar mass in g/mol for substances without a structure, or None.
+
+    Raises
+    ------
+    ValidationError
+        If no InChIKey can be generated for the structure, or if a molar mass is given together with a structure or is
+        not finite and positive.
+    """
+    name: str
+    id: UUID = field(default_factory=uuid4)
+    mol: "Mol|None" = None
+    molar_mass: float|None = None
+
+    def __post_init__(self) -> None:
+        if self.mol is not None and not self.key[1]:
+            raise ValidationError(f"No InChIKey can be generated for the structure of {self.name}")
+        if self.molar_mass is not None:
+            if self.mol is not None:
+                raise ValidationError(f"The molar mass of {self.name} is inferred from its structure and cannot be given")
+            if not math.isfinite(self.molar_mass) or self.molar_mass <= 0:
+                raise ValidationError(f"The molar mass of {self.name} must be finite and positive")
+
+    def get_molar_mass(self) -> float:
+        """Return the molar mass, either given or inferred from the structure.
+
+        Returns
+        -------
+        float
+            Molar mass in g/mol. For a structure, the average molar mass including implicit hydrogens.
+
+        Raises
+        ------
+        ValidationError
+            If the substance has neither a structure nor a molar mass.
+        """
+        if self.molar_mass is not None:
+            return self.molar_mass
+        if self.mol is not None:
+            # average molar mass including implicit hydrogens; defined dynamically, so missing from RDKit's stubs
+            from rdkit.Chem.Descriptors import MolWt  # pyright: ignore[reportAttributeAccessIssue]
+            return MolWt(self.mol)
+        raise ValidationError(f"The molar mass of {self.name} is unknown: give a structure or a molar mass")
+
+    def amount(self, mass: float) -> float:
+        """Convert a mass into an amount.
+
+        Parameters
+        ----------
+        mass
+            Mass in g.
+
+        Returns
+        -------
+        float
+            Amount in mol.
+
+        Raises
+        ------
+        ValidationError
+            If the molar mass is unknown (see `get_molar_mass`).
+        """
+        return mass / self.get_molar_mass()
+
+    def mass(self, amount: float) -> float:
+        """Convert an amount into a mass.
+
+        Parameters
+        ----------
+        amount
+            Amount in mol.
+
+        Returns
+        -------
+        float
+            Mass in g.
+
+        Raises
+        ------
+        ValidationError
+            If the molar mass is unknown (see `get_molar_mass`).
+        """
+        return amount * self.get_molar_mass()
+
+    @cached_property
+    def key(self) -> tuple[str, str]:
+        """Chemical identity used for comparison.
+
+        ``("inchikey", <InChIKey>)`` for substances with a structure, ``("name", <normalised name>)`` otherwise.
+        """
+        if self.mol is not None:
+            from rdkit.Chem import MolToInchiKey
+            return ("inchikey", MolToInchiKey(self.mol))
+        return ("name", self.name.strip().casefold())
+
+    def __repr__(self) -> str:
+        details = [repr(self.name)]
+        if self.mol is not None:
+            details.append(f"inchikey={self.key[1]!r}")
+        if self.molar_mass is not None:
+            details.append(f"molar_mass={self.molar_mass!r}")
+        return f"Substance({', '.join(details)})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Substance):
+            return NotImplemented
+        return self.key == other.key
+
+    def __hash__(self) -> int:
+        return hash(self.key)

hte/designs/base.py

@@ -0,0 +1,184 @@
+"""Building blocks shared by experiment designs."""
+from collections.abc import Sequence
+import math
+from typing import Protocol
+
+from hte.chemistry.composition import Composition
+from hte.exceptions import ValidationError
+from hte.labware.containers import Container
+from hte.labware.plates import Plate
+from hte.operations.plans import Plan
+from hte.operations.state import LabState
+from hte.tolerances import exceeds
+
+
+class Design(Protocol):
+    """An experiment design: it creates the plan that prepares a plate, starting from an initial state.
+
+    Attributes
+    ----------
+    plate
+        The plate that the design prepares.
+    """
+    plate: Plate
+
+    def create_plan(self, initial: LabState) -> Plan:
+        """Create the plan that prepares the plate.
+
+        Parameters
+        ----------
+        initial
+            State of the stocks and the plate before the plan.
+
+        Returns
+        -------
+        Plan
+            The plan.
+        """
+        ...
+
+
+def stock_volume(final_concentration: float, final_volume: float, stock_concentration: float) -> float:
+    """Return the volume of a stock that gives the final concentration in the final volume.
+
+    Parameters
+    ----------
+    final_concentration
+        Concentration in the final volume in mol/L.
+    final_volume
+        Final volume in L.
+    stock_concentration
+        Concentration of the stock in mol/L.
+
+    Returns
+    -------
+    float
+        Volume of the stock in L.
+    """
+    return final_volume * final_concentration/stock_concentration
+
+
+def stock_concentration(stock: Container, contents: Composition) -> float:
+    """Return the concentration of the single solute of a stock solution.
+
+    Parameters
+    ----------
+    stock
+        The stock container, used in error messages.
+    contents
+        Contents of the stock.
+
+    Returns
+    -------
+    float
+        Concentration in mol/L; always positive.
+
+    Raises
+    ------
+    ValidationError
+        If the stock does not contain a solution with exactly one solute.
+    """
+    # zero amounts are dropped from compositions, so the single solute has a positive concentration
+    if len(contents.solutes) != 1 or not contents.volume:
+        raise ValidationError(f"Stock {stock.describe()} must contain a solution with exactly one solute.")
+    (solute,) = contents.solutes
+    return contents.concentration(solute)
+
+
+def check_empty(initial: LabState, plate: Plate) -> None:
+    """Check that all wells of a plate are empty in a state.
+
+    Parameters
+    ----------
+    initial
+        The state.
+    plate
+        The plate.
+
+    Raises
+    ------
+    ValidationError
+        If a well contains liquid.
+    """
+    filled = [well.describe() for well in plate.wells if not initial[well].is_empty]
+    if filled:
+        raise ValidationError(f"Wells must be empty ({', '.join(filled)} already contain liquid).")
+
+
+def dilution_plan(
+    initial: LabState,
+    plate: Plate,
+    stocks: Sequence[Container],
+    concentrations: Sequence[Sequence[float]],
+    solvent: Container,
+    volume: float,
+) -> Plan:
+    """Plan to bring every well to a final volume with given concentrations of the stocks' solutes.
+
+    Each stock contains a single solute; its concentrations give the target in each well (row-major order). The
+    remaining volume of each well is filled with solvent. Wells must be empty, since existing contents would change
+    the final concentrations. Transfers are source-major: each stock across the plate, the solvent last.
+
+    Parameters
+    ----------
+    initial
+        State of the stocks and the plate before the plan.
+    plate
+        The plate to fill.
+    stocks
+        Stock solutions, each with a single solute.
+    concentrations
+        For each stock, the target concentration of its solute in each well in mol/L.
+    solvent
+        Container that fills each well up to the final volume.
+    volume
+        Final volume of each well in L.
+
+    Returns
+    -------
+    Plan
+        The plan. It is not validated: whether the stocks contain enough liquid is checked by `.Plan.simulate`.
+
+    Raises
+    ------
+    ValidationError
+        If the final volume is not finite and positive, the concentrations do not match the stocks or the wells or
+        are negative or not finite, a stock does not contain exactly one solute, a well is not empty, or the stock
+        volumes of a well exceed the final volume.
+    """
+    if not math.isfinite(volume) or volume <= 0:
+        raise ValidationError("Final volume must be finite and positive.")
+    if len(stocks) != len(concentrations):
+        raise ValidationError(f"{len(concentrations)} concentration sequences given for {len(stocks)} stocks.")
+    check_empty(initial, plate)
+
+    volumes = []
+    for stock, concentration_sequence in zip(stocks, concentrations, strict=True):
+        if len(concentration_sequence) != plate.size:
+            raise ValidationError(f"Concentrations of stock {stock.describe()} must be given for {plate.size} wells.")
+        if any(not math.isfinite(concentration) or concentration < 0 for concentration in concentration_sequence):
+            raise ValidationError(f"Concentrations of stock {stock.describe()} must be finite and non-negative.")
+        concentration_of_stock = stock_concentration(stock, initial[stock])
+        volumes.append([
+            stock_volume(
+                final_concentration=concentration,
+                final_volume=volume,
+                stock_concentration=concentration_of_stock,
+            ) for concentration in concentration_sequence
+        ])
+
+    solvent_volumes = []
+    for index, well in enumerate(plate.wells):
+        total_volume = sum(volume_sequence[index] for volume_sequence in volumes)
+        if exceeds(total_volume, volume):
+            raise ValidationError(
+                f"Stock volumes for well {well.describe()} ({total_volume}) exceed the final volume ({volume})."
+            )
+        solvent_volumes.append(max(volume - total_volume, 0.0))
+
+    return Plan.create_plan(
+        initial=initial,
+        plate=plate,
+        sources=[*stocks, solvent],
+        volumes=[*volumes, solvent_volumes],
+    )

hte/designs/titrations.py

@@ -0,0 +1,106 @@
+"""Titrations: a constant analyte with varying titrant concentrations across a plate."""
+from collections.abc import Sequence
+from dataclasses import dataclass
+import math
+
+from hte.designs.base import dilution_plan
+from hte.exceptions import ValidationError
+from hte.labware.containers import Container
+from hte.labware.plates import Plate
+from hte.operations.plans import Plan
+from hte.operations.state import LabState
+
+
+@dataclass
+class TitrationSeries:
+    """Target concentrations (mol/L) per well, in row-major order.
+
+    Attributes
+    ----------
+    analyte_concentration
+        Concentration of the analyte in each well.
+    titrant_concentration
+        Concentration of the titrant in each well.
+    additive_concentration
+        Concentration of an additive in each well, or None without additive.
+    """
+    analyte_concentration: Sequence[float]
+    titrant_concentration: Sequence[float]
+    additive_concentration: Sequence[float]|None = None
+
+
+@dataclass
+class TitrationDesign:
+    """A titration on a plate.
+
+    Every well receives analyte, titrant and, optionally, additive from stock solutions with a single solute each, and
+    is filled up to the final volume with solvent (see `.dilution_plan`).
+
+    Attributes
+    ----------
+    series
+        Target concentrations per well.
+    analyte
+        Stock solution of the analyte.
+    titrant
+        Stock solution of the titrant.
+    solvent
+        Container that fills each well up to the final volume.
+    volume
+        Final volume of each well in L.
+    plate
+        The plate to fill.
+    additive
+        Stock solution of an additive, or None without additive.
+
+    Raises
+    ------
+    ValidationError
+        If only one of the additive and its concentrations is given, or the final volume is not finite and positive.
+    """
+    series: TitrationSeries
+    analyte: Container
+    titrant: Container
+    solvent: Container
+    volume: float
+    plate: Plate
+    additive: Container|None = None
+
+    def __post_init__(self) -> None:
+        if (self.additive is None) != (self.series.additive_concentration is None):
+            raise ValidationError("Additive and additive concentrations must be given together.")
+        if not math.isfinite(self.volume) or self.volume <= 0:
+            raise ValidationError("Final volume must be finite and positive.")
+
+    def create_plan(self, initial: LabState) -> Plan:
+        """Create the plan for the given initial state of the stocks and the plate.
+
+        Parameters
+        ----------
+        initial
+            State of the stocks and the plate before the plan. The wells must be empty.
+
+        Returns
+        -------
+        Plan
+            The plan: analyte, titrant and additive across the plate, then the solvent. It is not validated; see
+            `.Plan.simulate`.
+
+        Raises
+        ------
+        ValidationError
+            If the plan cannot be created (see `.dilution_plan`).
+        """
+        stocks = [self.analyte, self.titrant]
+        concentrations = [self.series.analyte_concentration, self.series.titrant_concentration]
+        if self.additive is not None and self.series.additive_concentration is not None:
+            stocks.append(self.additive)
+            concentrations.append(self.series.additive_concentration)
+        return dilution_plan(
+            initial=initial,
+            plate=self.plate,
+            stocks=stocks,
+            concentrations=concentrations,
+            solvent=self.solvent,
+            volume=self.volume,
+        )