- Advanced
- 6 to 10 hours
- 15 min read
- You marked this lesson done
- Updated
After this lesson you can
- Build a closed loop that designs, writes a protocol, simulates it, reads a stand-in reader, learns and logs
- Check the simulator's volumes against the design before any result is used
- Show a reviewer a README, three protocols with simulator logs, a progress plot, an audit log and a short report
- Compare the loop with a random baseline and say what the result does and does not show
- Review someone else's loop against numbered acceptance criteria and a rubric
Read these first
Supports: the end of this track, the Developer path capstone habits (a repository a stranger can run and check) and the Master Developer Product Package. Time: about six to ten hours. Simulation only.
1. Why this matters
You now have every piece: a safety note, a protocol that simulates, a design, an optimiser and an audit log. A closed loop joins them so that each result becomes the next step, with nobody choosing recipes by hand.
The point is a loop that you and a stranger can both trust, not the colours. A loop whose volumes were never checked, whose reader was never labelled a stand-in and whose log can be edited without a trace has shown nothing.
Read your lesson 1 safety note first. Everything here runs in simulation. The plate reader is a stand-in, not real chemistry. Nothing in the result says how real dyes behave. Real lab work needs trained supervision and approval.
What the PDM decides here
| You decide | You may delegate to an agent | You verify | Other disciplines involved |
|---|---|---|---|
| The scope (simulation only), the acceptance criteria, three rounds and what the report may claim | The modules, tests, plot and a draft report, one module at a time, from written briefs | Every criterion below, by running the code, and every report sentence against the data | A reviewer or Sensei, statistics (baseline, noise), security (who can change protocols), the lab’s supervisor for anything real |
2. Key ideas
The loop
One round does these steps, in this order. Each one writes an entry to the audit log.
- Design. Ask the optimiser for 8 candidate recipes. Add a blank and two reference wells. Place all 11 in the inner wells with a seeded shuffle. Save
design.json. - Write the protocol. Generate it from
design.json. Nobody edits it by hand. - Simulate. Run
opentrons_simulateand save the log. A failure stops the loop. - Check. Rebuild from the log how much of each liquid went into each well. It must equal the design.
- Read. Ask the stand-in reader for a colour per well, correct by the blank and compute the distance to the target.
- Learn. Give the distances back to the optimiser.
- Log. Each step above writes an audit entry. After round three, add a finish entry.
Three rounds of 8 candidates make 24 recipes. Round one is space-filling. The next two use a model.
The stand-in plate reader
The reader is a Python function. It follows a simplified light-absorption law, the Beer-Lambert law: light through a well is 255 x exp(-A), where A adds up each dye’s absorbance by its share of the well. Cyan absorbs mostly red, magenta green and yellow blue. Each well holds 150 microlitres, and water fills what the dyes do not.
Noise is added on purpose, all seeded: 2 percent pipetting error on each dye, a lamp gain that drifts about 3 percent from plate to plate, 1.5 counts of reading noise and a 6 percent stronger reading in edge wells, as if water had evaporated. These numbers are invented, to make the problem need replicates, a blank and a good layout. They are not measurements.
The random draws depend only on the seed, the round and the well, not on the order of calls, so the loop is repeatable. The target colour comes from a recipe that the optimiser is never told. The distance is the straight-line distance in red-green-blue space between the blank-corrected reading and the target.
Generating a protocol
The protocol is a template. The recipes go in as a dictionary of wells and microlitres. One distribute per liquid sends it to every well that needs it, with a list of volumes.
for liquid in ["water", "cyan", "magenta", "yellow"]:
wells = [w for w, mix in RECIPES.items() if mix.get(liquid, 0) > 0]
if not wells:
continue
pipette.distribute(
volume=[RECIPES[w][liquid] for w in wells],
source=reservoir[SOURCES[liquid]],
dest=[plate[w] for w in wells],
)
Volumes are rounded to 0.1 microlitre, and water is 150 minus the dyes. A recipe over 150 raises an error. The rest is the Flex protocol from lesson 2, at API level 2.30.
Checking the simulator against the design
This step keeps a stand-in reader honest. The reader must not take dye volumes from the design. It takes them from what the simulator says the robot did. Parse the run log: each Aspirating line from a reservoir well sets the current liquid, and each Dispensing line into a plate well adds a volume to that well.
If the parsed volumes differ from the design in any well, the loop raises an error and does not read. A bug in protocol generation cannot hide behind a good-looking colour.
Three rounds, and what to expect
In the reference run for this lesson, the best distance after each round was 50.49, 24.07 and 11.66. The best recipe was 23.7 microlitres of cyan, 33.2 of magenta and 16.4 of yellow. The hidden target recipe was 22, 31 and 14. The audit log had 17 entries. Your numbers will differ unless you copy every detail. What must match is the shape: the best distance falls, the constraint holds and the checks pass.
The reference wells in that run read about 37 in round 1, 39 and 42 in round 2 and 44 in round 3. They drift because the lamp gain drifts per plate. A gap of a few counts between two recipes is inside the noise.
The baseline
One loop run is an anecdote. Compare it with random choice. In the test setup, 300 random campaigns of 24 recipes each, with the same constraint and reader, had a median best distance of 25.2. About 7 percent reached 11.7 or lower. So the loop’s 11.66 beats most random campaigns, yet luck could have produced it. One run cannot say more. Do this with your own code and say plainly what you find.
Honest hardware notes
- No GPU is needed. Ax and BoTorch run on the CPU for a problem this small. A GPU helps with large models and many parameters, which this loop does not have.
- Time. The loop took about a minute on the test laptop, and in other runs from half a minute to a few minutes. If it is much slower, set
OMP_NUM_THREADS=4. On one machine the model step took over two minutes without it. - Versions. Install all packages in one command (lesson 2). The reference run used Python 3.12,
opentrons10.1.0,ax-platform1.3.1 and BoTorch 0.18.1. - A real robot or reader. Nothing here is ready for real equipment. A real run needs a lab, a supervisor, a risk assessment and approval (lesson 1). That is a different project.
3. Step by step
Build in this order. Test and commit after each step.
- Set up the repository with the layout below and the safety note.
- Reader and its tests: repeatable, edge wells read darker, water fills the rest.
- Protocol generator, simulate function and log parser. Test that parsed volumes equal the recipe.
- Audit log from lesson 5, with its tamper tests.
- Optimiser setup from lesson 4, with the constraint and the full-batch loop.
- Layout function with a seeded shuffle of the inner wells.
run_roundandmain: the seven steps in order, three rounds, a start and a finish entry.- Report code, then the baseline.
- Run the loop, verify the audit log, anchor the last hash and commit.
- Write the README and the report, record the screen and ask for a review.
Repository layout
colour-lab/
README.md what it is, how to run it, the stand-in statement, AI disclosure
SAFETY.md the safety note from lesson 1
REPORT.md the short report
REVIEW.md the reviewer's notes (added by the reviewer)
pyproject.toml
requirements.txt pinned versions that you tested
src/colourlab/
reader.py the stand-in plate reader
protocol.py protocol template, simulate, log parser
audit.py hash-chained log and verify
loop.py optimiser setup, layout, run_round, main
report.py results.csv, progress.png, summary.json
baseline.py random campaigns for comparison
__main__.py python -m colourlab
tests/
test_colourlab.py reader, recipe, protocol and log, audit tamper tests
runs/
round-01/ design.json protocol.py simulator.log readings.json
round-02/
round-03/
ax_snapshot.json
audit/audit.jsonl
report/ results.csv progress.png summary.json
media/ a short recording or GIF
4. Worked example: acceptance criteria
A reviewer must be able to check each of these. The list is the heart of the capstone.
- Runs from a clean clone. After one install command,
python -m colourlabruns three rounds and exits with code 0. - Layout. Each round has 8 candidates, one blank and two reference wells, all in the inner wells (rows B to G, columns 2 to 11), placed by a seeded shuffle.
- Generated protocols. Each round’s protocol is written by code, declares
robotTypeandapiLevelinrequirementsonly, and simulates with exit code 0. The three protocols and three simulator logs are inruns/. - Simulator check. For every well in every round, the volumes parsed from the simulator log equal the design. A test proves that a mismatch raises an error.
- Stand-in reader. The reader is seeded, the same seed gives the same readings and the README and the report say it is a stand-in.
- Optimiser. It uses float parameters, the constraint and the minus-sign objective. A test shows that every proposal obeys the bounds and the constraint, and that short batches are handled.
- Audit log. A start entry, then design, protocol, simulated, read and learned entries for each round, then a finish entry.
verifyreturns no problems. Tests show that an edited entry, an edited file and a deleted file are each reported. The last hash is in the report and committed. - Results.
results.csv,progress.pngandsummary.jsonare produced by code. The plot shows each candidate and the best so far, with labelled axes. - Baseline and noise. The report compares the loop with random campaigns and uses the reference wells to say how large the noise is.
- Tests pass.
pytestpasses on a clean clone. - Honest claims. The README and report say what the work does not show. They claim no real chemistry, real equipment or regulatory compliance.
- Safety and disclosure.
SAFETY.mdexists and matches lesson 1. The README discloses AI use.
What to show
- A README that lets a stranger run the loop in five minutes, with the test results, date and versions.
- A short screen recording or GIF of the loop running in a terminal. Any screen recorder will do.
- The three protocols and simulator logs, the progress plot,
results.csv, the audit log and the output ofverify. - A one-page report. Use the structure in Write a technical report: the question, the method, the result, the limits and what you would do next. Add the baseline comparison and the reference-well noise. State the last audit hash.
The review rubric
| Criterion | Meets the bar | Needs work |
|---|---|---|
| Reproducible | Clean clone runs, tests pass, same seed gives same results | Fails to run, or results change |
| Checked | Simulator volumes are compared with the design, with a test | The reader trusts the design |
| Honest | Stand-in stated; no claim beyond the data | Claims of real chemistry, equipment or compliance |
| Recorded | Audit log verifies; tamper tests fail when they should | Missing steps, or only good-case tests |
| Judged | Baseline and noise in the report; no overclaim | One run presented as proof |
| Clear | A stranger can follow README, report and plot | Hard to follow, unlabelled plot |
| Safe | Safety note, nothing for hardware, AI use disclosed | Missing note, or hardware code |
Score each row. The first three rows and the last must meet the bar to pass.
5. Working with AI agents on this
What the PDM decides. The scope, the acceptance criteria, what the report may claim and which parts the agent may write. Write briefs module by module. Never hand over “build the whole lab”.
What you delegate, and the exact brief. One module at a time, at the delegate rung. Here is the brief for the loop module.
Task: write src/colourlab/loop.py for the project in README.md.
reader.py, protocol.py and audit.py exist with passing tests. Do not change them.
run_round(client, log, round_index, root) must, in order: design (8 Ax
candidates, a blank, 2 references, inner wells, seeded shuffle), write the
protocol, simulate, parse the simulator log, compare with the design, read,
complete the Ax trials, and write one audit entry per step.
Rules:
1. Float parameters 5 to 50 uL, constraint cyan + magenta + yellow <= 120,
objective "-distance". Loop until Ax returns a full batch.
2. The reader takes volumes from the parsed simulator log, never from the
design. If any well differs from the design, raise an error.
3. Write no code that talks to real equipment.
4. Use only functions in the installed ax-platform. Print its version.
5. Do not claim the result is optimal.
Output: loop.py and a test for the mismatch error.
How you verify. Run it yourself. Then break it: change a volume in a protocol and check that the loop stops. Edit a line of the audit log and check that verify complains. Find the evidence file for each claim in the README and report. Check the sign of the objective and the constraint on every proposal.
Which disciplines are involved. A statistician checks the baseline and the noise. A reviewer or Sensei checks the criteria. Security asks who can change a protocol. The lab’s supervisor decides if anything here ever goes near real equipment. Until then, the answer is no.
Where this sits on the ladder. One module at a time is delegate. Several agents writing modules in parallel is orchestrate: write the interfaces first and make the tests the contract. Govern is a pipeline that, on every merge request, installs from a clean checkout, runs the tests and the loop, verifies the audit log and refuses the merge if anything fails.
Disclose. Add to the README: “Parts of this code and report were drafted by AI agents from my briefs. I ran the loop and the tests, broke the checks on purpose and verified every claim against the data.” See Disclose AI use.
6. Common mistakes
- Reading the design instead of the simulator log. A bug in the protocol then never shows.
- Calling the reader real. It is a stand-in. Say so in the README and report.
- One run as proof. Use a baseline and the noise from the reference wells.
- Short batches. Ax may give fewer than 8. Loop until full.
- Editing a generated protocol by hand. Change the generator and generate again.
- Claims beyond the data. “Optimal”, “secure”, “validated” and “compliant” need evidence you do not have.
7. Practice: build, show and be reviewed
Deliverable: the complete repository colour-lab/ in your git repository, with REPORT.md, the README, the media and a passing test run.
- Build the loop in the order of the step list. Commit after each step.
- Check every acceptance criterion yourself and write the result of each in
REPORT.md. - Add the baseline comparison and a short screen capture in
media/. - Ask a Sensei or a peer to review it (next section) and keep their notes in
REVIEW.md. - Fix what the review found. Commit with a message such as
feat: closed-loop colour lab in simulation.
Check: can someone who has not seen the track run your README in five minutes?
How a Sensei or peer reviews it
The reviewer works from a fresh clone and does not rely on the author’s word.
- Read
SAFETY.mdand the README. Check the stand-in statement and the AI disclosure. - Install in a clean environment with one command. Note the versions.
- Run the tests, then the loop. Time it.
- Verify the audit log. Then edit one line in a copy and confirm that
verifyreports it. - Check the simulator step: change one volume in a copy of a generated protocol and confirm that the loop stops.
- Walk the twelve criteria, each with its evidence file.
- Read the report against the data. Does each claim follow from
results.csv, the plot and the baseline? - Score the rubric and write
REVIEW.md: what meets the bar, what needs work, one thing done well, and any AI help used.
A failed criterion is reported with how to see it. The author fixes it and asks again. See Team work with human review.
8. Checklist
-
SAFETY.mdexists, and everything runs in simulation. - The README says the reader is a stand-in.
- Three generated protocols simulate, and the logs are saved.
- Simulator volumes are checked against the design in every well.
- Every proposal obeys the constraint, and a short batch is handled.
- The audit log verifies, tamper tests fail when they should and the last hash is in the report.
- The report has the random baseline and the noise.
- Tests pass on a clean clone.
- A reviewer wrote
REVIEW.md. - I recorded my AI use.
9. Further learning
The Opentrons page on executing and simulating lists the simulator’s options. The Ax tutorial and the BoTorch site go deeper on the optimiser. The colour-matching paper describes a robotic version of this task, so you can see what a real setup adds. Reread the WHO manual and its risk assessment monograph before you ever think about a real run. Then try Bioinformatics, Robot software and Safety reports and review.
Finished this lesson?
This is only for you. It is saved in this browser, on this device, and nothing is sent anywhere. It is not a grade and not a certificate.
Go deeper
Further learning
Free or low-cost material from other publishers. We opened every link; check the cost label before you start.
Opentrons
Python API Reference: Executing and Simulating (opens the publisher's site in a new tab)
- Free
- Docs
- Intermediate
The Opentrons reference for running a protocol from the command line and for simulating it on a computer. It describes the simulate command and what its output shows. Use it to check a protocol before it goes near a robot.
Ax
Getting Started with Ax (opens the publisher's site in a new tab)
- Free
- Tutorial
- Intermediate
A tutorial from the Ax project, an open-source adaptive experimentation platform. It shows how to set up an experiment, ask for trials, report results and read the best result. It is the model for the ask-and-tell loop in this track.
BoTorch
BoTorch (opens the publisher's site in a new tab)
- Free
- Docs
- Advanced
The home of BoTorch, a library for Bayesian optimisation built on PyTorch. Its docs and tutorials cover Gaussian process models and acquisition functions such as expected improvement. Ax uses it underneath. Read it when you want to see the model rather than the wrapper.
arXiv
Exploring Benchmarks for Self-Driving Labs using Color Matching (opens the publisher's site in a new tab)
- Free
- Article
- Advanced
A paper that uses colour matching as a test case for self-driving labs. The task is to find the amounts of coloured pigments that match a target colour. The authors say it needs experiment proposal, sample creation and sample analysis. They describe a robotic solution that runs it without a person.
Git SCM
Pro Git book (opens the publisher's site in a new tab)
- Free
- Book
- Beginner
The free, full book on Git. Read the first three chapters on basics and branching. Use the rest as a reference.
World Health Organization
Laboratory biosafety manual, 4th edition (opens the publisher's site in a new tab)
- Free
- Book
- Beginner
The WHO manual on safe work in laboratories, built around risk assessment. Read its opening ideas to learn why real laboratory work needs training, a supervisor and institutional approval. Sequence analysis on public data is not a laboratory activity, but the habits carry over.



