Skip to content
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,21 @@
# Changelog

## Unreleased

### Added

- `lab.plates` describes a plate by its intended end state. `PlateDesign` and `WellTarget` hold per-well `Material` records (a name, or a strain and construct that name it, with an optional SBOL design) and solute concentrations; `find_serial_dilutions()` and `parallelize()` detect geometric gradients, `find_replicate_groups()` identical chemistry; `plan_serial_dilution()` and `record_serial_dilution()` build a gradient at a chosen concentrate factor with the arithmetic documented in `docs/plates.md`; `plan_premix()` and `record_premix()` prepare replicate portions once; `arrange()` lays out a plate from `Requirements`; `assemble()` prepares a design from declared stocks, medium, vehicle, and inocula under a `Strategy` of direct, serial, or automatic dosing and reports its decisions.
- `lab.config.PlateDesignConfig` and `PreparationConfig` are the typed JSON and TOML forms of a design and of the preparation settings. `lab.plugins.lmsf` reads and writes the LMSF destination CSV as a view of a design; the core package does not depend on that format.
- `Protocol.capacity()` returns the declared capacity of a plate or well. `lab.uM` and `lab.mM` are exported molar units.
- `compile(..., warn_below=, resolution=)` records advisory `Diagnostic`s on `Compilation.diagnostics`, in `plan.json`, and in a worksheet Advisories section: liquid steps below a head's trusted floor or the lab's own `warn_below`, and volumes that cannot be dialed at the given resolution. `lab.limits.PipettingLimits` describes each head's range and trusted floor; every `TargetPlan` lists its heads, and `Manual(pipettes=...)` takes a bench set. `lab.plates.advise_design()` gives the same advice for a design before any protocol exists. Hard limits remain `CompileError`s.

- `Protocol.transfer()` and `mix()` accept sequences of wells and record `MultiTransfer` and `MultiMix` lane sets; `Plate.column()` returns a column in row order. Opentrons 8-channel heads (`PipetteModel.P20_MULTI_GEN2`, `P300_MULTI_GEN2`, `FLEX_8CHANNEL_50`, `FLEX_8CHANNEL_1000`, with `TipRackModel.FLEX_50_UL` and `FLEX_1000_UL`) run a full-column lane set in one stroke; STAR layouts configure up to eight `Channel`s and run lanes across them; single-channel heads and the manual target run lanes in turn. The worksheet lists lanes and animates them together.
- `TipPolicy` is recorded with a protocol (`Protocol(name, tip_policy=...)`) or overridden with `compile(..., tip_policy=...)`: fresh per step, reuse per source, or reuse while every destination's contents are contained in the source's. `Protocol.load(..., components=...)` declares what a source is made of; `lab.tips` numbers and counts tips, and `prewet()` records a pre-wetting stroke. Generated robot programs and `plan.json` carry the policy; the worksheet shows the resulting tip count.

### Changed behavior

- The concentration-series example prepares the layout's Van gradients as serial dilutions by default (`preparation.strategy = "auto"`), draws gradient diluent from a second medium reservoir well, and discards one transfer volume per lane into a declared waste container. `--strategy direct` reproduces per-well dosing. Its configuration gains a `[preparation]` table, `medium.diluent_volume`, a `waste` container, one more tip rack per robot layout, and eight STAR channels so gradient columns move in one stroke. Serial dilution levels are recorded as lane sets, so the example compiles to 342 steps under `auto`.

## 0.3.0

### Changed behavior
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,7 +198,7 @@ Liquid-class cards plot flow rate against time for the selected operation. Aspir

Preparation proceeds across the plate: medium first, then vehicle and each stock, followed by inoculation and mixing. Equal doses from the same source share a `distribute()` operation and one tip. Unique doses remain individual transfers. Preparing the full supplied layout requires 327 tips, including source resuspension and destination mixing. The worksheet reports the tip count alongside the operation count.

The standalone [concentration-series example](examples/concentration_series/) reads a [plate layout](examples/concentration_series/layout.csv) and [protocol configuration](examples/concentration_series/config.toml), then records ordinary transfers and mixes. The supplied layout preserves the well coordinates and target concentrations of an LMSF fitness export, with generic strain and plasmid names. Every CSV row is prepared by default: 96 wells covering 24 conditions for each of four plasmid samples. An optional `wells` list in the configuration selects a subset explicitly. `lab.units.dilution_volume()` calculates stock volumes; the recipe balances vehicle and medium, inoculates, and mixes. Source identities and volumes, working-stock selection, and liquid classes are explicit. The TOML also declares development OT-2 and STAR deck layouts, parsed directly into Lab's existing `Deck` types, with reservoir sources and enough tips for the full plate.
The standalone [concentration-series example](examples/concentration_series/) reads a [plate layout](examples/concentration_series/layout.csv) and [protocol configuration](examples/concentration_series/config.toml), then records ordinary transfers and mixes. The supplied layout preserves the well coordinates and target concentrations of an LMSF fitness export, with generic strain and plasmid names. Every CSV row is prepared by default: 96 wells covering 24 conditions for each of four plasmid samples. An optional `wells` list in the configuration selects a subset explicitly. `lab.plugins.lmsf` reads the CSV into a `lab.plates.PlateDesign`, and `lab.plates.assemble()` plans every well: the two Van gradients are detected and prepared as serial dilutions (`--strategy auto`, the default) or dosed directly (`--strategy direct`), the recipe balances vehicle and medium, inoculates, and mixes. Source identities and volumes, working-stock selection, and liquid classes are explicit. [Plate designs](docs/plates.md) documents the design model, pattern detection, and the dilution arithmetic. The TOML also declares development OT-2 and STAR deck layouts, parsed directly into Lab's existing `Deck` types, with reservoir sources and enough tips for the full plate.

`main()` parses the TOML into `ProtocolConfig` and the CSV into `PlateLayout` using Pydantic. The reusable quantity fields and liquid-class schemas come from [`lab.config`](docs/configuration.md), available through `lab-compiler[config]` and included in development dependencies (`uv sync --locked`). `prepare_wells()` checks the inputs together and calculates doses; `protocol()` consumes those prepared wells and the validated configuration to record operations. The configuration mirrors the TOML: `medium.name` is `config.medium.name`, and liquid-class names remain names until protocol construction resolves them. Saved configuration comes from that same model.

Expand Down
4 changes: 4 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,3 +45,7 @@ Quantity fields accept unit-bearing strings or Pint `Quantity` objects. They rej
Existing Lab dataclasses can also be fields. For example, `deck: lab.deck.Deck` parses nested containers and layouts into typed Lab objects, including enums, locations, and Decimal limits. Pydantic applies their existing dataclass validation. The [concentration-series configuration](../examples/concentration_series/config.toml) demonstrates this without a separate deck parser or schema.

For applications that do not use Pydantic, `lab.units.parse_quantity(value, unit="microliter")` provides the same normalization. `unit` may also be a tuple of alternatives for different dimensions, such as `("mole/liter", "gram/liter")`. The first compatible unit is used. `positive=False` permits zero; negative or nonfinite values always fail. This input parser does not change the `Protocol` API: operations take quantity objects.

## Plate designs and preparation settings

`PlateDesignConfig` is the typed form of a [`lab.plates.PlateDesign`](plates.md): a name, an optional shape, the final volume, and `wells`, each with an optional `material` (a name, or a table with `name` and optional `strain`, `construct`, and `design`) and a `concentrations` table of unit-bearing strings. `to_design()` builds the Lab object. `PreparationConfig` carries the `strategy` (`direct`, `serial`, or `auto`), `concentrate`, `serial_min_steps`, the optional premix settings that `lab.plates.Settings` consumes, the `warn_below` and `resolution` volumes passed to `compile()` for advisories, and the `tip_policy` the protocol is recorded with. The concentration-series configuration uses `PreparationConfig` as its `[preparation]` table.
Loading
Loading