Run Your First Scan#

Ask the agent for a scan in plain words, watch the form fill itself in, press two buttons, and watch the points land — all against the Virtual Accelerator, a simulated machine, so nothing real can move.

Step 1: Ask#

Open the Web Terminal (osprey web) and ask for the scan the way you would say it out loud — in setpoints and monitors, not in software terms:

Set up a 2-D grid scan: sweep the horizontal steering correctors in
sectors 1 and 2 from -0.5 to 0.5 A in 5 steps each, reading the BPMs
either side of them at every point.

The agent turns this into a grid_scan plan and stages it as a shared draft — a plan-in-progress that you and the agent both see and can both edit. Composing a draft never moves anything and never needs permission.

Step 2: Watch it fill#

Switch to the PLAN tab. If the draft is on the plan you are looking at, a small button appears — “Draft is now on grid_scan — click to view”. Click it, and the form fills with the agent’s draft. From here every field the agent sets glows briefly as it lands, with a short note naming what changed.

The form is yours too: change a step count, swap a monitor — your edit flows back into the same draft the agent sees. Nobody’s version wins by surprise, because there is only one draft. That also means the Discard shared draft button deletes it for everyone — the agent included — so save it for a real fresh start.

Step 3: Add it to the queue#

Click Add to queue, then confirm. This puts exactly the plan on your screen into the scan queue — if anyone changed the draft in the meantime, the panel refuses and shows you the current version to review instead.

Nothing is running yet. The scan just got in line — and the panel offers an Open BLUESKY button that takes you straight to it.

Step 4: Start the queue#

Click that button, or switch to the BLUESKY tab. Your scan is listed under Queue. Click Start queue — this is the moment things move, and it runs everything in the queue, in order, not only your item. Glance at the list before you click.

Note

Starting is the guarded step. On a deployment that has not been armed for execution, the start is refused with a plain-language explanation in the panel — composing and queueing stay free precisely because starting is not. Scans and the Queue explains what “armed” means here.

Step 5: Watch the results#

Stay on the BLUESKY tab. The lower half follows the selected run, and the run’s figure leads it — one plot per panel, with real axis labels and units, filling in as the scan goes. A 5 × 5 grid settles fast on the Virtual Accelerator — all 25 points should land within a few seconds.

The raw numbers are underneath, behind a Data table disclosure that names the run’s row count and stays closed until you open it. These tables run to thousands of rows on a real scan, which is why they are not in your way by default. What the table shows is a preview — a bounded window, labelled with how much of the run it is holding back. Export CSV, on the same row, is how you get the whole run: one click opens your browser’s save dialog, and the file that lands carries every row the run recorded, at full precision.

What you are watching is grid_scan’s own view of the scan. A two-axis grid draws one heatmap per monitor — the fast axis across, the slow axis up, one cell per grid position — and a cell the scan has not reached yet is left empty rather than filled with a zero. Sweep a single axis instead and the same plan draws lines: one panel per monitor, against that axis. The orm plan brings its own view too: a trace per corrector while the sweep runs, then the fitted response matrix and per-device scores.

A short note above the plots says where the data came from and whether it is still arriving — live data · still filling in while the scan runs. A run you come back to later, read from durable storage, shows stored data instead.

A plan does not have to bring a view. For one that does not, the panel draws the default view instead: every numeric column the run recorded, plotted against the scan’s own axis, with the note line adding a few words about why you are seeing it. None of that is an error — the default view is real data, and for many measurements it is exactly the right picture.

Ask the agent “how does that scan look?” and it reads the same figure you have on screen, so you are both describing one picture rather than two.

If you need to stop#

Two buttons on the BLUESKY tab, and they always work — no permission, no token, no switch can disable them:

Stop after current item — gentle. The running scan finishes, then the queue stops.
Abort running plan — immediate. It takes a second, confirming click, because its cost is real: the rest of the scan is discarded, the data already taken is kept, and the hardware stays wherever the scan left it — nothing is driven back to a starting position.