Skip to content

Blog

Notes from building CORA: feature highlights, design decisions, and the occasional walk through how a part of the system actually works.

Every post here describes something already shipped and stable on main. When a capability is still in progress, it waits for its post until the capability is real. If a post mentions something that is authored but not yet runnable, it says so plainly.

Where CORA Fits: a system of record above the floor it stands on

Stewart Brand, describing how complex systems survive, compressed the whole idea into four words: "Fast learns, slow remembers." A healthy system is layered by speed. Its fast layers move, propose, and innovate in the moment; its slow layers hold steady underneath and keep the memory. A beamline is almost all fast layer. The motors move, the detector reads out, the control system acts, and the data lands, all at once. What it has rarely had is a slow layer, the one whose only job is to remember, faithfully and for a long time, what the fast layers did and why.

What It Leaves Behind: telling a Run from a Procedure

Two acts at the beamline can look identical from across the hutch. In the first, the sample rotates through a full turn while the camera fires hundreds of times. In the second, the sample rotates through a full turn while the camera fires hundreds of times. Same stage, same motion, same detector, same operator. Yet one of them is a tomography scan, and the other is a center-of-rotation alignment, and CORA records them as two different kinds of thing: the first as a Run, the second as a Procedure. If the motion does not tell them apart, what does?

  • in Safety
  • 5 min read

No Proof, No Resume: a machine may pause the beam, but it has to earn its way back

It is two in the morning and a fifteen-hundred-projection scan is half done when the storage ring drops its beam. Nobody is in the control room. On most setups one of two bad things happens: the acquisition grinds on, writing hundreds of dark, useless frames, or it sits there, technically running, until someone arrives at eight and finds the night wasted. What you want is the obvious human thing: pause when the beam goes, pick back up when it returns. What you do not want is a machine that picks back up at the wrong moment. CORA now does the first, automatically, precisely because it refuses to do the second.

What Actually Happened: a run is the record of reality, deviations and all

A tomography scan is fifteen hundred projections long, and it is seven hundred frames in when the storage ring dumps its beam. Another night, an overnight scan still reads "Running" the next morning, hours after a power cut, a dropped network link, and a dead laptop quietly killed it; the operator finds the corpse at the start of shift. A plan describes what was supposed to happen. A Run is the harder, more honest thing next to it: the record of what actually did, including the pause for the beam dump, the exposure that got nudged mid-scan, and the gap between the experiment as imagined and the experiment as it ran.

Undo Is a Lie: how you take something back on a log that cannot forget

You published a reconstruction at the end of a beamtime, marked it production-grade, and handed the dataset on to whoever needed it. A week later you realize it should never have carried that grade: the run behind it was off, or a calibration it leaned on was wrong. On almost any system, the reflex is obvious. Delete it. Roll it back. Press undo. But CORA is built on a log that physically cannot delete anything, where the database role the application runs as is granted exactly two rights on the event table, read and append, and is refused update, delete, and truncate at the boundary. So the undo button is not disabled. It does not exist. The question becomes interesting: what do you press instead?

  • in Safety
  • 7 min read

The Banner That Warns But Never Blocks: tribal knowledge that reaches the console without standing in the way

Every beamline runs on a second body of knowledge that never made it into a manual. The Aerotech rotary stage at 2-BM misses its index pulse on the first home after a power cycle, so you home it, wait five seconds, and home it again. After the hexapod controller reboots, every axis comes back correctly except Y, whose dial resets to zero while the encoder still reads 350, and if you command a Y move before fixing it by hand you earn a drive error and another reboot. None of this is a fault. None of it is in the vendor documentation. It is the stuff the last shift learned the hard way, and it usually lives in a sticky note on a monitor, a thread in a chat channel, or the head of whoever happens to be on shift. Which means that on the night the right person is not on shift, it does not exist at all.

  • in Safety
  • 8 min read

No Clearance, No Beam: what it means for a record to be able to say no

The operator has done everything right. The sample is mounted, the recipe ladder is defined, the beam is up, and the scan is one keystroke away. They press start, and the system says no. Not a yellow banner they can click past, not a checkbox to acknowledge and move on: a flat refusal, because the safety form covering this particular sample has not yet been activated. A few minutes later a reviewer walks the form through its last approval, the operator presses the very same start again, and this time it runs cleanly, with no edits and no workaround. Nothing about the experiment changed. What changed is that the paperwork became real, and the system was watching for exactly that.

What "Calibrated" Means: a dated fact, not a number you overwrite

"Calibrated" sounds like a settled property of an instrument, the way "two meters long" is settled. In daily practice it is something much softer: a number in a spreadsheet, or a field in a config, that someone measured once and that gets overwritten the next time the instrument is calibrated. The current value is easy to find. Everything around it is not. What was the center of rotation last March, when this dataset was taken? Who measured it, and was it a careful measurement or a quick estimate typed in to get a shift moving? Once the number has been overwritten, those questions have no answer, and the data that depended on the old value is quietly orphaned from the value it actually used.

The Metadata Problem, From the Other End: record the work, and let the labels be a read

Every facility runs on metadata, the labels and fields attached to data so that it can be found, understood, and reused after the people who took it have moved on. And almost everywhere, metadata disappoints. It is incomplete, because the field you need now is the one nobody thought to capture then. It is inconsistent, because two people labeled the same thing two ways. It is retrofitted, filled in long after the moment it was meant to describe, from memory. None of this is a failure of diligence. It is built into how metadata is usually produced, and the cause is worth naming plainly. At the moment of acquisition you are asked to anticipate every question a future reader might ask and stamp a label for each. You cannot, so there is always a missing field, and a missing field is usually gone for good. That is the metadata problem.

Derive, Don't Stamp: what a ledger lets you stop storing

Ask an ordinary system a simple question, is this detector active, and it usually answers by reading a column. Somewhere a row has a status field, and at some earlier moment a piece of code ran an update to set it. The answer is trustworthy exactly to the degree that every code path which should have set that column actually did. CORA answers the same question a different way: it has no status column to read. It looks at what happened to the detector and lets the most recent fact speak for itself. This is a small inversion with large consequences, and it is the quiet habit that an append-only log makes possible: derive the answer from the record of facts, rather than stamping the answer into a field of its own.