lab-compiler 0.2.0__tar.gz → 0.3.0__tar.gz

{lab_compiler-0.2.0 → lab_compiler-0.3.0}/.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 .venv/
 __pycache__/
 *.py[cod]
@@ -7,3 +8,5 @@ __pycache__/
 build/
 dist/
 *.egg-info/
+
+docs/lmsf/

lab_compiler-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## 0.3.0
+
+### Changed behavior
+
+- On OT-2 and Flex, `Protocol.thermocycle()` without `lid_temperature` now follows each block hold with the heated lid, disabling lid heating below 37 °C. An explicit lid temperature remains fixed. Thermocycling retains the final temperature settings after opening the lid; failures deactivate the module before propagating the error. `set_temperature()` also matches the thermocycler lid to the block. Generated STAR thermal callbacks document the same contract.
+- Golden Gate assembly uses the automatic lid behavior instead of a fixed 42 °C lid, including during enzyme inactivation.
+- Recorded transfer, distribution, and mixing steps in `plan.json` now include `liquid_class`, set to `null` when no class is supplied. Consumers of serialized operations should accept this additional field.
+
+### Added
+
+- A standalone, printable protocol worksheet with material and well inspection, liquid-class flow profiles, and an interactive preparation preview. The preview follows the compiler's calculated volume snapshots and illustrates transfers, distributions, and mixes; it does not simulate physical delivery or robot trajectories. Templates, styles, and scripts ship in the package, with no network access required to view the worksheet.
+- `LiquidClass` supplies explicit aspiration and dispense rates for `Protocol.transfer()`, `distribute()`, and `mix()` across manual, OT-2, Flex, and STAR targets. `HamiltonLiquidClass` references native STAR definitions, which are captured in the generated plan and program; Opentrons targets reject these references.
+- Optional `lab.config` models and quantity fields, installed with `lab-compiler[config]`, support typed application configuration with Pydantic. The core package remains independent of Pydantic. `lab.units.parse_quantity()` normalizes unit-bearing inputs, and `dilution_volume()` calculates stock volumes for compatible concentrations.
+- A concentration-series example reads a destination CSV and TOML configuration, validates doses and source requirements, and prepares an inoculated plate for manual, OT-2, or STAR compilation. The included layout covers a full 96-well plate and supports selecting a subset through configuration.
+
+### Dependencies and validation
+
+- Jinja2 is now a core dependency for worksheet rendering. The optional robot SDK versions remain Opentrons 8.8.2 and PyLabRobot 0.2.1; supported Python versions remain 3.11 and 3.12.
+- CI compares simulated OT-2 assembly, transformation, and plating behavior with a pinned PUDU revision, including lid settings, thermal profiles, transfers, and handoff wells. These required checks fail if the reference source or Opentrons SDK is missing.
+
+## 0.2.0
+
+### Migration from 0.1.0
+
+- Pass shared decks with `lab.compile(protocol, deck=deck, liquid_handler=...)`. A positional second argument is now reserved for a concrete target.
+- `lab.compile(protocol)` defaults to a manual target and writes a bundle to `~/.lab/<protocol>/<target>/`. Use `to=None` to compile without writing, `to=path` to choose a directory, or `LAB_HOME` to change the default root. Recompilation replaces the files in that protocol/target bundle; `Compilation.write()` still refuses to replace different existing artifacts.
+- Replace the removed `lab.protocols` request and material API with the cloning experiment builders and `lab.samples`. `Assembly` and `Transformation` recipes take native `sbol3.Component` objects; pySBOL3 is now a core dependency.
+
+### Added
+
+- Sample identities, lineage, design references, and optional implementation references are preserved in the protocol snapshot. Declared outputs produce `manifest.json` and are available through `Compilation.manifest`.
+- Assembly, transformation, and plating examples carry native SBOL design identities through their planned outputs, with a separate example for computational design provenance.
+- An optional LabOP integration exports prospective protocol plans using upstream LabOP. It is installed from the checkout in a separate environment and is not imported by the core package.
+
+### Repository
+
+- Move the source repository to `https://github.com/MyersResearchGroup/LabCompiler` and update package URLs, README links, and publishing instructions. The PyPI package remains `lab-compiler`; the Python import remains `lab`.

{lab_compiler-0.2.0 → lab_compiler-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lab-compiler
-Version: 0.2.0
+Version: 0.3.0
 Summary: A small Python compiler for inspectable laboratory protocols
 Project-URL: Homepage, https://github.com/MyersResearchGroup/LabCompiler
 Project-URL: Documentation, https://github.com/MyersResearchGroup/LabCompiler#readme
@@ -17,8 +17,11 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Typing :: Typed
 Requires-Python: <3.13,>=3.11
+Requires-Dist: jinja2<4,>=3.1.6
 Requires-Dist: pint<0.27,>=0.24
 Requires-Dist: sbol3==1.2.0.post0
+Provides-Extra: config
+Requires-Dist: pydantic<3,>=2.13; extra == 'config'
 Provides-Extra: opentrons
 Requires-Dist: opentrons==8.8.2; extra == 'opentrons'
 Provides-Extra: star
@@ -33,7 +36,7 @@ Description-Content-Type: text/markdown
 </p>
 
 <p align="center">
-  <em>A compiler for biological engineering. Describe experiments in Python, check the protocol, and produce a document or a robot program.</em>
+  <em>A compiler for liquid handling. Describe experiments in Python, check the protocol, and produce a document or a robot program.</em>
 </p>
 
 Lab Compiler is the Python compiler for laboratory work. A `Protocol` records materials, wells, steps, and optional sample identities and lineage. Compilation checks volumes, units, bindings, and sample declarations, then writes a printable document and code for the liquid handler you name.
@@ -59,34 +62,47 @@ Use `"lab-compiler[opentrons,star]"` to install both SDKs.
 
 ## Write a protocol
 
-Describe biological designs with native pySBOL3 components. An experiment builder records their laboratory operations in a `Protocol`, and `compile()` validates and compiles that protocol for the selected target.
+A `Protocol` records what a scientist would write at the bench: the plates, what starts in each well, and every transfer and mix. This one prepares a two-fold dilution series of fluorescein in PBS, the standard curve for a plate reader.
 
 ```python
-import sbol3
-from lab import compile
+from lab import Protocol, compile, uL
+from lab.deck import Container, Deck, DeckSite
 from lab.equipment import LiquidHandler
-from lab.experiments.cloning import Transformation, build_transformation, transformation_deck
+from lab.labware import PLATE_96
 
-designs = sbol3.Document()
-strain = sbol3.Component("https://example.org/my_strain", sbol3.SBO_FUNCTIONAL_ENTITY)
-chassis = sbol3.Component("https://example.org/my_cells", sbol3.SBO_FUNCTIONAL_ENTITY)
-plasmid = sbol3.Component("https://example.org/my_plasmid", sbol3.SBO_DNA)
-designs.add([strain, chassis, plasmid])
+protocol = Protocol("fluorescein serial dilution")
+sources = protocol.plate("sources", capacity=360 * uL)
+assay = protocol.plate("assay", capacity=360 * uL)
 
-protocol = build_transformation(
-    [Transformation(strain=strain, chassis=chassis, plasmids=[plasmid])],
-    name="transformation",
-)
-compiled = compile(
-    protocol,
-    deck=transformation_deck(on_module=True),
-    liquid_handler=LiquidHandler.OT2,
+fluorescein, pbs, waste = sources["A1"], sources["A2"], sources["A3"]
+protocol.load(fluorescein, "10 µM fluorescein in PBS", volume=150 * uL)
+protocol.load(pbs, "PBS", volume=300 * uL)
+
+dilutions = [assay[f"A{column}"] for column in range(1, 7)]
+protocol.transfer(fluorescein, dilutions[0], volume=100 * uL)
+protocol.distribute(pbs, dilutions[1:], volume=50 * uL)
+
+# Carry 50 µL down the row, mixing each well before the next transfer.
+for previous, current in zip(dilutions, dilutions[1:]):
+    protocol.transfer(previous, current, volume=50 * uL)
+    protocol.mix(current, volume=40 * uL, cycles=3)
+protocol.transfer(dilutions[-1], waste, volume=50 * uL)
+protocol.manual("Read fluorescence at 485 nm excitation and 525 nm emission.")
+
+deck = Deck(
+    containers=(
+        Container(id="sources", labware=PLATE_96, site=DeckSite.PLATES),
+        Container(id="assay", labware=PLATE_96, site=DeckSite.PLATES),
+    )
 )
+compiled = compile(protocol, deck=deck, liquid_handler=LiquidHandler.FLEX)
 ```
 
+`compile()` checks every volume against the wells and the pipette, then writes a printable protocol and an Opentrons Flex program. The deck only says both plates sit in open plate positions; the Flex preset chooses the slots, tip rack, and pipette. Wells A1–A6 of the assay plate each finish with 50 µL.
+
 ## Describe a deck
 
-This OT-2 deck places two 96-well plates in slots 1 and 2, a 300 µL tip rack in slot 3, and a P300 pipette on the left mount. It uses the same equipment and placement types as the [deck layouts example](https://github.com/MyersResearchGroup/LabCompiler/blob/master/examples/deck_layouts.py).
+A `DeckLayout` states the equipment and positions instead of leaving them to a preset. This OT-2 deck places the dilution protocol's `sources` and `assay` plates in slots 1 and 2, a 300 µL tip rack in slot 3, and a P300 pipette on the left mount. It uses the same equipment and placement types as the [deck layouts example](https://github.com/MyersResearchGroup/LabCompiler/blob/master/examples/deck_layouts.py).
 
 ```python
 from lab.deck import Deck, DeckLayout, Pipette, Placement, Slot, TipRack
@@ -132,6 +148,12 @@ deck = Deck(
 )
 ```
 
+Compile the dilution protocol for that robot:
+
+```python
+compiled = compile(protocol, deck=deck, liquid_handler=LiquidHandler.OT2)
+```
+
 ## Describe physical layouts in Lab
 
 Use `DeckLayout` when equipment or placement needs to be explicit. Each layout names its `LiquidHandler` and places the same shared containers. All objects below belong to Lab:
@@ -160,6 +182,8 @@ The compiler rejects missing layouts, conflicting placements, invalid holder ref
 
 For Opentrons, place thermal labware on a supported `Module`. STAR layouts currently support one independent `Channel` and external thermal integration. Declare thermal containers in `DeckLayout.external_thermal_resources` and supply the async `thermocycle` callback when the generated `run()` executes. The callback is responsible for controlling the device and returning the plate to its original position. Compilation checks the declaration; the software preview only reports the request. On-deck `Module` models are not yet supported by the STAR backend.
 
+By default, thermocycling matches the lid target to each block target within the device's heated lid range and turns lid heating off below that range. On Opentrons, the lid follows block targets at 37 °C and above; colder holds turn off the lid heater. Persistent thermocycler holds use the same rule, including setup and plating. An explicit `lid_temperature` keeps the lid at a fixed target throughout a profile. Successful profiles keep their final temperature settings; a failed Opentrons profile shuts down both controllers. External STAR thermal callbacks follow the same contract when `lid_temperature=None`.
+
 ## Try it
 
 The examples live in the source repository. With [uv](https://docs.astral.sh/uv/) installed, set up Python 3.12 and both optional SDKs:
@@ -192,6 +216,32 @@ The cloning example writes separate `assembly`, `transformation`, and `plating`
 
 The manifest uses logical container and well names; physical bindings remain in `plan.json`. Rewriting an identical bundle succeeds. If any generated file would replace different contents, `write()` rejects the write before changing any bundle files.
 
+The HTML worksheet shows initial loads, numbered operations, liquid-class settings, and calculated final volumes. Hover or focus a material, location, resource, or liquid class to inspect its recorded details; click to keep the card open and press Escape to dismiss it. Location cards distinguish initial loads, planned final volumes, output samples, and incoming transfers. The first paragraph of `Protocol.description` is the overview; subsequent paragraphs appear in expandable protocol notes. Styles and interactions are embedded for offline use, with a plain reference section when JavaScript is disabled and a separate print layout.
+
+The [worksheet UI guide](docs/worksheet-ui.md) describes its typed view data, reusable templates, and interactive components.
+
+The preparation preview shows logical plate layouts and reagent inputs. Step through or play the procedure to see source volumes decrease and destination wells fill; a schematic pipette and directional paths show each transfer. Distributions visit each destination, and mixes animate in place. Click a procedure step number to preview that state. Well details and reagent amounts follow the selected step. The preview uses the compiler's volume accounting, with animation timing chosen for readability. It shows planned liquid movement; physical well bindings are available in the detail cards.
+
+Liquid-class cards plot flow rate against time for the selected operation. Aspiration is positive and dispensing negative; mixing repeats those phases. Durations are ideal calculations from nominal volume divided by the recorded rate, excluding robot movement, pauses, ramps, air gaps, and volume correction. These diagrams are not measured device traces. Native Hamilton profiles require rates captured during STAR compilation.
+
+## Concentration series
+
+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.
+
+`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.
+
+```sh
+uv run --no-sync python -m examples.concentration_series \
+  --csv examples/concentration_series/layout.csv \
+  --config examples/concentration_series/config.toml --target manual
+```
+
+Use `--target ot2` or `--target star` with the corresponding optional SDK installed. Output goes to `build/concentration_series/csv/<target>/`; `--out` selects another directory. Rerunning replaces the generated bundle in that directory. The example ends with an inoculated plate; incubation and measurement need separately specified methods.
+
+`LiquidClass` supplies unit-checked aspiration and dispense rates on either robot family. `HamiltonLiquidClass` references a native STAR built-in, whose definition is captured during compilation. Both can be passed as `liquid_class=` to `transfer()`, `distribute()`, and `mix()`. See [liquid classes](docs/liquid-classes.md) for examples, settings coverage, calibration boundaries, and the data needed to compare with VENUS.
+
 ## Development
 
 From the repository root:
@@ -203,4 +253,12 @@ uv run --no-sync mypy
 uv run --no-sync pytest
 ```
 
+The concentration-series tests use the same `layout.csv` and `config.toml` as the example. They exercise parsing, dose calculations, compilation, robot simulation, and provenance without additional data files or configuration.
+
+CI runs the OT-2 equivalence tests against a pinned PUDU revision. To compare against another checkout, set `PUDU_SOURCE` to its `src` directory. When this variable is set, missing PUDU source or the Opentrons SDK fails the run.
+
+```sh
+PUDU_SOURCE=/path/to/PUDU/src uv run --no-sync pytest -q tests/test_ot2_equivalence.py
+```
+
 See the [release guide](https://github.com/MyersResearchGroup/LabCompiler/blob/master/docs/releasing.md) for package validation and PyPI publishing, and the [release notes](https://github.com/MyersResearchGroup/LabCompiler/blob/master/CHANGELOG.md) for changes and migration guidance.

{lab_compiler-0.2.0 → lab_compiler-0.3.0}/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <em>A compiler for biological engineering. Describe experiments in Python, check the protocol, and produce a document or a robot program.</em>
+  <em>A compiler for liquid handling. Describe experiments in Python, check the protocol, and produce a document or a robot program.</em>
 </p>
 
 Lab Compiler is the Python compiler for laboratory work. A `Protocol` records materials, wells, steps, and optional sample identities and lineage. Compilation checks volumes, units, bindings, and sample declarations, then writes a printable document and code for the liquid handler you name.
@@ -32,34 +32,47 @@ Use `"lab-compiler[opentrons,star]"` to install both SDKs.
 
 ## Write a protocol
 
-Describe biological designs with native pySBOL3 components. An experiment builder records their laboratory operations in a `Protocol`, and `compile()` validates and compiles that protocol for the selected target.
+A `Protocol` records what a scientist would write at the bench: the plates, what starts in each well, and every transfer and mix. This one prepares a two-fold dilution series of fluorescein in PBS, the standard curve for a plate reader.
 
 ```python
-import sbol3
-from lab import compile
+from lab import Protocol, compile, uL
+from lab.deck import Container, Deck, DeckSite
 from lab.equipment import LiquidHandler
-from lab.experiments.cloning import Transformation, build_transformation, transformation_deck
+from lab.labware import PLATE_96
 
-designs = sbol3.Document()
-strain = sbol3.Component("https://example.org/my_strain", sbol3.SBO_FUNCTIONAL_ENTITY)
-chassis = sbol3.Component("https://example.org/my_cells", sbol3.SBO_FUNCTIONAL_ENTITY)
-plasmid = sbol3.Component("https://example.org/my_plasmid", sbol3.SBO_DNA)
-designs.add([strain, chassis, plasmid])
+protocol = Protocol("fluorescein serial dilution")
+sources = protocol.plate("sources", capacity=360 * uL)
+assay = protocol.plate("assay", capacity=360 * uL)
 
-protocol = build_transformation(
-    [Transformation(strain=strain, chassis=chassis, plasmids=[plasmid])],
-    name="transformation",
-)
-compiled = compile(
-    protocol,
-    deck=transformation_deck(on_module=True),
-    liquid_handler=LiquidHandler.OT2,
+fluorescein, pbs, waste = sources["A1"], sources["A2"], sources["A3"]
+protocol.load(fluorescein, "10 µM fluorescein in PBS", volume=150 * uL)
+protocol.load(pbs, "PBS", volume=300 * uL)
+
+dilutions = [assay[f"A{column}"] for column in range(1, 7)]
+protocol.transfer(fluorescein, dilutions[0], volume=100 * uL)
+protocol.distribute(pbs, dilutions[1:], volume=50 * uL)
+
+# Carry 50 µL down the row, mixing each well before the next transfer.
+for previous, current in zip(dilutions, dilutions[1:]):
+    protocol.transfer(previous, current, volume=50 * uL)
+    protocol.mix(current, volume=40 * uL, cycles=3)
+protocol.transfer(dilutions[-1], waste, volume=50 * uL)
+protocol.manual("Read fluorescence at 485 nm excitation and 525 nm emission.")
+
+deck = Deck(
+    containers=(
+        Container(id="sources", labware=PLATE_96, site=DeckSite.PLATES),
+        Container(id="assay", labware=PLATE_96, site=DeckSite.PLATES),
+    )
 )
+compiled = compile(protocol, deck=deck, liquid_handler=LiquidHandler.FLEX)
 ```
 
+`compile()` checks every volume against the wells and the pipette, then writes a printable protocol and an Opentrons Flex program. The deck only says both plates sit in open plate positions; the Flex preset chooses the slots, tip rack, and pipette. Wells A1–A6 of the assay plate each finish with 50 µL.
+
 ## Describe a deck
 
-This OT-2 deck places two 96-well plates in slots 1 and 2, a 300 µL tip rack in slot 3, and a P300 pipette on the left mount. It uses the same equipment and placement types as the [deck layouts example](https://github.com/MyersResearchGroup/LabCompiler/blob/master/examples/deck_layouts.py).
+A `DeckLayout` states the equipment and positions instead of leaving them to a preset. This OT-2 deck places the dilution protocol's `sources` and `assay` plates in slots 1 and 2, a 300 µL tip rack in slot 3, and a P300 pipette on the left mount. It uses the same equipment and placement types as the [deck layouts example](https://github.com/MyersResearchGroup/LabCompiler/blob/master/examples/deck_layouts.py).
 
 ```python
 from lab.deck import Deck, DeckLayout, Pipette, Placement, Slot, TipRack
@@ -105,6 +118,12 @@ deck = Deck(
 )
 ```
 
+Compile the dilution protocol for that robot:
+
+```python
+compiled = compile(protocol, deck=deck, liquid_handler=LiquidHandler.OT2)
+```
+
 ## Describe physical layouts in Lab
 
 Use `DeckLayout` when equipment or placement needs to be explicit. Each layout names its `LiquidHandler` and places the same shared containers. All objects below belong to Lab:
@@ -133,6 +152,8 @@ The compiler rejects missing layouts, conflicting placements, invalid holder ref
 
 For Opentrons, place thermal labware on a supported `Module`. STAR layouts currently support one independent `Channel` and external thermal integration. Declare thermal containers in `DeckLayout.external_thermal_resources` and supply the async `thermocycle` callback when the generated `run()` executes. The callback is responsible for controlling the device and returning the plate to its original position. Compilation checks the declaration; the software preview only reports the request. On-deck `Module` models are not yet supported by the STAR backend.
 
+By default, thermocycling matches the lid target to each block target within the device's heated lid range and turns lid heating off below that range. On Opentrons, the lid follows block targets at 37 °C and above; colder holds turn off the lid heater. Persistent thermocycler holds use the same rule, including setup and plating. An explicit `lid_temperature` keeps the lid at a fixed target throughout a profile. Successful profiles keep their final temperature settings; a failed Opentrons profile shuts down both controllers. External STAR thermal callbacks follow the same contract when `lid_temperature=None`.
+
 ## Try it
 
 The examples live in the source repository. With [uv](https://docs.astral.sh/uv/) installed, set up Python 3.12 and both optional SDKs:
@@ -165,6 +186,32 @@ The cloning example writes separate `assembly`, `transformation`, and `plating`
 
 The manifest uses logical container and well names; physical bindings remain in `plan.json`. Rewriting an identical bundle succeeds. If any generated file would replace different contents, `write()` rejects the write before changing any bundle files.
 
+The HTML worksheet shows initial loads, numbered operations, liquid-class settings, and calculated final volumes. Hover or focus a material, location, resource, or liquid class to inspect its recorded details; click to keep the card open and press Escape to dismiss it. Location cards distinguish initial loads, planned final volumes, output samples, and incoming transfers. The first paragraph of `Protocol.description` is the overview; subsequent paragraphs appear in expandable protocol notes. Styles and interactions are embedded for offline use, with a plain reference section when JavaScript is disabled and a separate print layout.
+
+The [worksheet UI guide](docs/worksheet-ui.md) describes its typed view data, reusable templates, and interactive components.
+
+The preparation preview shows logical plate layouts and reagent inputs. Step through or play the procedure to see source volumes decrease and destination wells fill; a schematic pipette and directional paths show each transfer. Distributions visit each destination, and mixes animate in place. Click a procedure step number to preview that state. Well details and reagent amounts follow the selected step. The preview uses the compiler's volume accounting, with animation timing chosen for readability. It shows planned liquid movement; physical well bindings are available in the detail cards.
+
+Liquid-class cards plot flow rate against time for the selected operation. Aspiration is positive and dispensing negative; mixing repeats those phases. Durations are ideal calculations from nominal volume divided by the recorded rate, excluding robot movement, pauses, ramps, air gaps, and volume correction. These diagrams are not measured device traces. Native Hamilton profiles require rates captured during STAR compilation.
+
+## Concentration series
+
+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.
+
+`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.
+
+```sh
+uv run --no-sync python -m examples.concentration_series \
+  --csv examples/concentration_series/layout.csv \
+  --config examples/concentration_series/config.toml --target manual
+```
+
+Use `--target ot2` or `--target star` with the corresponding optional SDK installed. Output goes to `build/concentration_series/csv/<target>/`; `--out` selects another directory. Rerunning replaces the generated bundle in that directory. The example ends with an inoculated plate; incubation and measurement need separately specified methods.
+
+`LiquidClass` supplies unit-checked aspiration and dispense rates on either robot family. `HamiltonLiquidClass` references a native STAR built-in, whose definition is captured during compilation. Both can be passed as `liquid_class=` to `transfer()`, `distribute()`, and `mix()`. See [liquid classes](docs/liquid-classes.md) for examples, settings coverage, calibration boundaries, and the data needed to compare with VENUS.
+
 ## Development
 
 From the repository root:
@@ -176,4 +223,12 @@ uv run --no-sync mypy
 uv run --no-sync pytest
 ```
 
+The concentration-series tests use the same `layout.csv` and `config.toml` as the example. They exercise parsing, dose calculations, compilation, robot simulation, and provenance without additional data files or configuration.
+
+CI runs the OT-2 equivalence tests against a pinned PUDU revision. To compare against another checkout, set `PUDU_SOURCE` to its `src` directory. When this variable is set, missing PUDU source or the Opentrons SDK fails the run.
+
+```sh
+PUDU_SOURCE=/path/to/PUDU/src uv run --no-sync pytest -q tests/test_ot2_equivalence.py
+```
+
 See the [release guide](https://github.com/MyersResearchGroup/LabCompiler/blob/master/docs/releasing.md) for package validation and PyPI publishing, and the [release notes](https://github.com/MyersResearchGroup/LabCompiler/blob/master/CHANGELOG.md) for changes and migration guidance.

lab_compiler-0.3.0/docs/configuration.md

@@ -0,0 +1,47 @@
+# Typed protocol configuration
+
+`lab.config` supplies Pydantic fields and models for application input files. Install `lab-compiler[config]` to use it; repository development dependencies also include Pydantic. Importing `lab` and using `Protocol` do not require Pydantic.
+
+Define the application's schema using ordinary Pydantic fields and validators. Lab's quantity fields handle parsing, dimensional checks, Decimal normalization, JSON serialization, and JSON Schema:
+
+```python
+from lab.config import ConfigModel, Concentration, NonnegativeVolume, Volume
+
+
+class ProtocolConfig(ConfigModel):
+    final_volume: Volume
+    source_dead_volume: NonnegativeVolume
+    stock_concentration: Concentration
+
+
+config = ProtocolConfig.model_validate(
+    {
+        "final_volume": "0.2 mL",
+        "source_dead_volume": "20 uL",
+        "stock_concentration": "1 mM",
+    }
+)
+print(config.final_volume)  # 2E+2 microliter
+print(config.model_dump_json())
+```
+
+| Field type | Accepted values and Python representation |
+| --- | --- |
+| `Volume` | Positive finite quantity, normalized to microlitres |
+| `NonnegativeVolume` | As above, allowing zero; useful for dead volumes |
+| `FlowRate` | Positive finite quantity, normalized to microlitres/second |
+| `Concentration` | Nonnegative finite quantity, normalized to mole/litre or gram/litre |
+| `ConcentrationUnit` | A separate mass/volume or amount/volume unit; retains its original scale for CSV numeric columns |
+| `VolumeFraction` | Finite Decimal from zero through one |
+| `NonnegativeDecimal` | Finite Decimal greater than or equal to zero |
+| `NonemptyString` | String containing at least one non-whitespace character |
+
+Quantity fields accept unit-bearing strings or Pint `Quantity` objects. They reject bare numbers and incompatible dimensions. Mass concentration cannot be converted to molar concentration without additional information. Quantities serialize as unit-bearing strings and appear as strings in JSON Schema; the validation runs when parsing, not in JSON Schema itself.
+
+`ConfigModel` rejects unknown fields, allows these Pint types, and freezes attribute assignment. Its contained dictionaries are still mutable, following Pydantic's usual behavior. Parse the files once before building a protocol. Apply application-specific checks, such as stock coverage and composition balance, before recording operations; the compiler subsequently checks inventory, capacity, and equipment constraints.
+
+`LiquidClassConfig` is a discriminated union of `PortableLiquidClassConfig` (`kind = "portable"`, aspiration/dispense rates) and `HamiltonLiquidClassConfig` (`kind = "hamilton"`, native symbol). `MixingConfig` supplies a volume, positive integer cycle count, and liquid-class name. Names remain references within the application's configuration; the application checks them against its registry and explicitly constructs Lab liquid classes. See [liquid classes](liquid-classes.md).
+
+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.

lab_compiler-0.3.0/docs/liquid-classes.md

@@ -0,0 +1,87 @@
+# Liquid classes
+
+A liquid class supplies pipetting settings for a particular operation. Attach it to `Protocol.transfer()`, `distribute()`, or `mix()`. It is separate from the material identity and concentration: two transfers of the same material can need different settings because their tips, volumes, or destinations differ.
+
+## Portable custom settings
+
+```python
+from lab import LiquidClass, Protocol, seconds, uL
+
+gentle = LiquidClass(
+    "gentle culture",
+    aspiration_flow_rate=20 * uL / seconds,
+    dispense_flow_rate=30 * uL / seconds,
+)
+p = Protocol("Culture aliquot")
+source = p.container("source", contents="culture", volume=200 * uL, capacity=360 * uL)
+destination = p.container("destination", capacity=360 * uL)
+p.transfer(source, destination, volume=50 * uL, liquid_class=gentle)
+p.mix(destination, volume=40 * uL, cycles=3, liquid_class=gentle)
+```
+
+`LiquidClass` currently expresses **aspiration and dispense flow rates**. Both are required, finite, positive quantities with volume/time dimensions. Construction converts them to immutable Decimal µL/s values. A name describes the settings; it does not identify a calibrated fluid in a robot's catalogue.
+
+| Target | Application |
+| --- | --- |
+| Manual | Print the name and both rates beside the operation |
+| OT-2 and Flex | Set the selected pipette's absolute aspiration/dispense rates for the operation, then restore its previous rates |
+| STAR | Pass absolute `flow_rates` to each PyLabRobot aspiration and dispense |
+
+Mixing uses these same rates for each cycle. Distribution applies them to the target's aspirations and dispenses; distribution batching remains target-specific. With `liquid_class=None`, the operation uses the existing target defaults.
+
+This portable class is deliberately a small settings profile. It does **not** specify a volume-correction curve, air gap, blowout, liquid-level detection, heights, surface following, settling times, or dispensing mode. Those retain the target/SDK defaults. In particular, changing rates or naming a class `dmso` does not select a Hamilton DMSO calibration: the generated STAR program does not populate PyLabRobot liquid-identity trackers, so automatic class selection uses the SDK's default liquid. Use an explicit Hamilton reference when the native calibration is required.
+
+The common meaning of µL/s supports software portability. Equivalent physical delivery still depends on the device, tips, liquid, volume, and method. Add further portable fields when their meaning and lowering can be demonstrated on the relevant targets; keep device-specific calibration separate.
+
+## Hamilton built-ins
+
+PyLabRobot provides a catalogue imported from VENUS, and its STAR backend accepts native classes on both aspiration and dispense. A native definition contains more than rates, including a volume-correction curve. See the [PyLabRobot liquid-class guide](https://docs.pylabrobot.org/stable/user_guide/00_liquid-handling/hamilton-star/hamilton-liquid-classes.html).
+
+Reference an exact symbol through Lab's SDK-independent type:
+
+```python
+from lab import HamiltonLiquidClass
+
+water = HamiltonLiquidClass("HighVolumeFilter_Water_DispenseSurface_Part")
+p.transfer(source, destination, volume=50 * uL, liquid_class=water)
+```
+
+The symbol above is an illustration of lookup, not a recommendation for the concentration example's 300 µL tips. Select a definition validated for the intended liquid, tip/filter, channel/head, volume range, and dispense mode. Lab does not infer this compatibility from the symbol's spelling.
+
+With `lab-compiler[star]` installed, discover the available symbols without connecting to hardware:
+
+```python
+from lab.targets.star import hamilton_liquid_class_names
+
+names = hamilton_liquid_class_names()
+print([name for name in names if "DMSO" in name])
+```
+
+STAR compilation checks that the symbol resolves to a native liquid-class object. It snapshots the definition into `plan.json` and the generated program, alongside the required PyLabRobot version. The program reconstructs that captured definition and passes it to both operations. Unknown symbols fail compilation. OT-2 and Flex reject Hamilton references; manual compilation can document a reference without installing PyLabRobot but cannot resolve it.
+
+The native backend performs volume correction. Lab records requested liquid volumes, so it does not pre-correct them or apply the curve a second time. Its inventory calculation and channel/tip checks concern nominal volumes; they are not a physical calibration or an exhaustive check of corrected piston movements and transport air. A native class on `mix()` applies to repeated ordinary aspirations and dispenses, not a separate Hamilton firmware mixing command.
+
+Capturing the definition does not imply that every field is used by the pinned backend. PyLabRobot's method-level defaults and implementation determine effective behavior, including which class fields are consumed. Native built-ins are supported here; importing an arbitrary local VENUS class or creating a full native Hamilton definition through Lab is not yet implemented. For a custom class beyond portable rates, first obtain its actual parameter table and method usage, then add a typed native representation and trace tests for the fields required.
+
+## CSV preparation
+
+The standalone [concentration-series example](../examples/concentration_series/) reads its class registry from the [protocol configuration TOML](../examples/concentration_series/config.toml) supplied with `--config`. Each stock, the medium, the balancing vehicle, and each culture names a class. Source and destination mixing name their classes separately: the final mixture is not interchangeable with its constituent stocks.
+
+`ProtocolConfig` is a Pydantic schema with the same nesting and field names as the TOML, validated once in `main()` before protocol construction. Its liquid-class and mixing schemas come from the optional [`lab.config`](configuration.md) module. `[liquid_classes.aqueous]` becomes `config.liquid_classes["aqueous"]`, a typed configuration entry. `config.medium.liquid_class` remains the string `"aqueous"`; the schema checks that this name exists. A Hamilton entry's TOML key is its local alias, and its `name` is the native STAR catalogue symbol.
+
+At the start of `protocol()`, a dictionary comprehension converts the entries to Lab's `LiquidClass` or `HamiltonLiquidClass` objects. Operations look them up explicitly, for example `liquid_class=liquid_classes[config.medium.liquid_class]`. Configuration loading does not substitute objects for names. The plan records `config.model_dump_json()` from the validated model used by the recipe.
+
+```toml
+[liquid_classes.culture]
+kind = "portable"
+aspiration_flow_rate = "20 uL/s"
+dispense_flow_rate = "20 uL/s"
+```
+
+For STAR, a class table can instead contain `kind = "hamilton"` and `name = "<exact built-in symbol>"`. The example numbers are development inputs. They are not measured performance data or reconstructed LMSF settings.
+
+## Establishing LMSF equivalence
+
+Ask for one matched run containing the destination CSV, source setup, resolved LMSF parameters, complete VENUS method export and dependencies, native liquid-class definitions, and a simulation trace plus a successful instrument trace. For each pipetting step, identify the selected class and any method overrides: tip/filter and channel/head, aspiration/dispense modes, LLD and heights, mixing, air/blowout, settling, and correction settings. Record VENUS, firmware, and instrument configuration versions.
+
+Compare the generated sequence and effective settings with that run before measuring delivery accuracy and precision over the actual volume range. A matching class name, nominal volume ledger, or software trace alone does not demonstrate the same physical result. These artifacts also establish whether direct PyLabRobot execution is suitable or whether LMSF needs to retain VENUS as its execution layer.

{lab_compiler-0.2.0 → lab_compiler-0.3.0}/docs/releasing.md

@@ -26,42 +26,50 @@ After a repository transfer or rename, update the publisher in PyPI before publi
 
 ## Validate a release
 
-Update `src/lab/_version.py` when preparing a new version, then run from the repository root:
+Update `src/lab/_version.py` and add the changes and migration guidance to `CHANGELOG.md` when preparing a new version, then run from the repository root:
 
 ```sh
 uv lock
-uv sync --locked --all-extras
+uv sync --locked --all-extras --python 3.12
 uv run --no-sync ruff check .
 uv run --no-sync mypy
 uv run --no-sync pytest -q
-uv build --no-sources
-uv run --no-sync twine check --strict dist/*
+uv build --no-sources --out-dir dist/0.3.0
+uv run --no-sync twine check --strict dist/0.3.0/*
 ```
 
-Build into an empty `dist/` directory so old releases are not included. `uv build` creates a source distribution and builds the wheel from it. Confirm both artifacts can be installed in fresh environments; for version `0.2.0`:
+Use an empty directory for the version being prepared so old releases are not included. `uv build` creates a source distribution and builds the wheel from it. Confirm both artifacts can be installed in fresh environments; for version `0.3.0`:
 
 ```sh
-uv venv /tmp/lab-compiler-wheel --python 3.12
-uv pip install --python /tmp/lab-compiler-wheel/bin/python dist/lab_compiler-0.2.0-py3-none-any.whl
-/tmp/lab-compiler-wheel/bin/python -I scripts/check_install.py
+uv venv /tmp/lab-compiler-0.3.0-wheel --python 3.12
+uv pip install --python /tmp/lab-compiler-0.3.0-wheel/bin/python dist/0.3.0/lab_compiler-0.3.0-py3-none-any.whl
+/tmp/lab-compiler-0.3.0-wheel/bin/python -I scripts/check_install.py
 
-uv venv /tmp/lab-compiler-sdist --python 3.12
-uv pip install --python /tmp/lab-compiler-sdist/bin/python dist/lab_compiler-0.2.0.tar.gz
-/tmp/lab-compiler-sdist/bin/python -I scripts/check_install.py
+uv venv /tmp/lab-compiler-0.3.0-sdist --python 3.12
+uv pip install --python /tmp/lab-compiler-0.3.0-sdist/bin/python dist/0.3.0/lab_compiler-0.3.0.tar.gz
+/tmp/lab-compiler-0.3.0-sdist/bin/python -I scripts/check_install.py
 ```
 
-The install check verifies distribution metadata, version agreement, the license and typing marker, and manual compilation without importing robot SDKs. `-I` ensures Python imports the installed package. CI runs the test suite with core dependencies and both optional SDKs on Python 3.11 and 3.12, then builds and checks both artifacts. PUDU equivalence tests skip unless the separate checkout is available at the path specified in `tests/test_ot2_equivalence.py`; CI does not fetch it. Robot tests use offline simulation and command recording.
+The install check verifies distribution metadata, version agreement, the license and typing marker, and worksheet rendering from the installed templates and assets without importing Pydantic or robot SDKs. `-I` ensures Python imports the installed package. CI runs the test suite with core dependencies and both optional SDKs on Python 3.11 and 3.12, then builds and checks both artifacts. Robot tests use offline simulation and command recording.
+
+CI also checks out PUDU at the revision pinned in `.github/workflows/ci.yml` and requires OT-2 equivalence before building distributions. To run the same comparison locally, check out that revision separately and set its source path explicitly:
+
+```sh
+PUDU_SOURCE=/path/to/pinned/PUDU/src uv run --no-sync pytest -q tests/test_ot2_equivalence.py
+```
+
+With `PUDU_SOURCE` set, missing reference source or a missing Opentrons SDK is an error. The ordinary local suite can skip these tests when no reference checkout is available. CI also validates the optional upstream LabOP integration in its separate environment.
 
 ## Publish
 
 1. Merge the release changes and confirm CI passes on the intended commit.
-2. Create a GitHub release for that commit with a tag matching the package version exactly, such as `v0.2.0`.
+2. Create a GitHub release for that commit with a tag matching the package version exactly, such as `v0.3.0`, and use the corresponding section of `CHANGELOG.md` as its release notes.
 3. Publish the GitHub release. Draft releases do not upload packages.
 4. The `Publish to PyPI` workflow runs CI again for the release, checks the tag against the package version, and uploads the validated artifacts through the `pypi` environment. Approve the environment deployment if required reviewers are configured.
 5. Confirm the version appears on [PyPI](https://pypi.org/project/lab-compiler/) and install it in a fresh environment:
 
    ```sh
-   python -m pip install "lab-compiler==0.2.0"
+   python -m pip install "lab-compiler==0.3.0"
    python -c "import lab; print(lab.__version__)"
    ```