docs(aerotech): measured comparison default vs minimal run-up, position plots

Both series of 2026-10-29 (8486-8494 default, 8501-8509 minimal_run_up):
timing and positioning per case, why the saving is about half the shorter
travel (Y step no longer hidden in the run-out), the constant direction
offset after the velocity transient and the 20 mm/s oscillation, deviation
and zoom plots, and the split of the line period with the next levers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M8zoDzDfsCTY2o5bT3J7Wv

docs/user/saxs/aerotech_stages/aerotech_stages.md

@@ -158,53 +158,119 @@ centres from the nominal cells, backward minus forward offset, and the line time
 
 ## Timing and positioning
 
-Measured 2026-10-29 (scans 8486-8494, default run-up, PandABox as trigger, readout
-0.2 ms, X acceleration 500 mm/s^2). Positions in um; "rms" is the scatter of the
-measured exposure centres around the nominal cells (forward and backward lines
-alike), "bwd - fwd" the offset between neighbouring lines with its slope along X
-and its peak-to-peak over the line.
+Measured 2026-10-29 with the PandABox as trigger (readout 0.2 ms), X acceleration
+500 mm/s^2, X centred at 123.25, and the same nine scans in both run-up modes:
+scans 8486-8494 with the default run-up, 8501-8509 with `minimal_run_up=True`.
+The target resolution is about 20 um; the positioning accuracy should be well below
+that.
 
-| Field of view (mm) | Step / exposure (speed) | Points x lines | rms | bwd - fwd | slope (um/mm) | peak-to-peak | Line period | Exposure per line | Positioning overhead per line | Scan time | Estimate with uneven positions (line, scan) |
-|---|---|---|---|---|---|---|---|---|---|---|---|
-| 0.8 x 1.2 | 100 um / 5 ms (20 mm/s) | 9 x 13 | 2.9 | +1.2 | +3.4 | 11.4 | 0.79 s | 0.04 s | 0.74 s (94 %) | 0.2 min | 0.45 s, 0.1 min |
-| 0.8 x 1.2 | 40 um / 20 ms (2 mm/s) | 21 x 31 | 1.0 | +3.6 | +0.2 | 2.9 | 1.03 s | 0.42 s | 0.61 s (59 %) | 0.6 min | 0.73 s, 0.4 min |
-| 0.8 x 1.2 | 10 um / 20 ms (0.5 mm/s) | 81 x 121 | 0.2 | +0.1 | 0.0 | 0.8 | 2.21 s | 1.62 s | 0.59 s (27 %) | 4.5 min | 1.95 s, 3.9 min |
-| 2 x 2 | 100 um / 5 ms (20 mm/s) | 21 x 21 | 5.6 | +2.3 | +0.2 | 25.6 | 0.83 s | 0.10 s | 0.72 s (87 %) | 0.4 min | 0.49 s, 0.2 min |
-| 2 x 2 | 40 um / 20 ms (2 mm/s) | 51 x 51 | 0.6 | +2.8 | 0.0 | 2.4 | 1.64 s | 1.02 s | 0.62 s (38 %) | 1.5 min | 1.34 s, 1.1 min |
-| 1 x 1 | 10 um / 20 ms (0.5 mm/s) | 101 x 101 | 0.2 | 0.0 | 0.0 | 0.8 | 2.61 s | 2.02 s | 0.59 s (23 %) | 4.5 min | 2.35 s, 4.0 min |
-| 3.5 x 3.0 | 100 um / 5 ms (20 mm/s) | 36 x 31 | 5.7 | +0.8 | +0.1 | 30.6 | 0.91 s | 0.18 s | 0.73 s (80 %) | 0.6 min | 0.57 s, 0.3 min |
-| 3.5 x 3.0 | 40 um / 20 ms (2 mm/s) | 89 x 76 | 0.5 | +2.8 | 0.0 | 2.9 | 2.40 s | 1.78 s | 0.62 s (26 %) | 3.1 min | 2.10 s, 2.7 min |
-| 3.5 x 3.0 | 10 um / 20 ms (0.5 mm/s) | 351 x 301 | 0.1 | -0.7 | 0.0 | 0.9 | 7.75 s | 7.02 s | 0.73 s (9 %) | 38.9 min | 7.49 s, 37.6 min |
+Terms used below (positions in um):
+
+- **rms:** scatter of the measured exposure centres around the nominal cells.
+- **bwd - fwd:** offset between neighbouring backward and forward lines, with its
+  slope along X and its peak-to-peak over the line. A constant offset only shifts the
+  field of view; a slope would distort it.
+- **Line period:** time from the start of one line to the start of the next.
+- **Positioning overhead:** line period minus the exposure per line (points times
+  `exp_time`), per line and as a fraction of the scan time. It contains the run-up and
+  run-out, the turnaround, the Y step, and the readout of the captured positions.
+
+### Default run-up
+
+| Field of view (mm) | Step / exposure (speed) | Points x lines | rms | bwd - fwd | slope (um/mm) | peak-to-peak | Line period | Exposure per line | Positioning overhead per line | Scan time |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 0.8 x 1.2 | 100 um / 5 ms (20 mm/s) | 9 x 13 | 2.9 | +1.2 | +3.4 | 11.4 | 0.79 s | 0.04 s | 0.74 s (94 %) | 0.2 min |
+| 0.8 x 1.2 | 40 um / 20 ms (2 mm/s) | 21 x 31 | 1.0 | +3.6 | +0.2 | 2.9 | 1.03 s | 0.42 s | 0.61 s (59 %) | 0.6 min |
+| 0.8 x 1.2 | 10 um / 20 ms (0.5 mm/s) | 81 x 121 | 0.2 | +0.1 | 0.0 | 0.8 | 2.21 s | 1.62 s | 0.59 s (27 %) | 4.5 min |
+| 2 x 2 | 100 um / 5 ms (20 mm/s) | 21 x 21 | 5.6 | +2.3 | +0.2 | 25.6 | 0.83 s | 0.10 s | 0.72 s (87 %) | 0.4 min |
+| 2 x 2 | 40 um / 20 ms (2 mm/s) | 51 x 51 | 0.6 | +2.8 | 0.0 | 2.4 | 1.64 s | 1.02 s | 0.62 s (38 %) | 1.5 min |
+| 1 x 1 | 10 um / 20 ms (0.5 mm/s) | 101 x 101 | 0.2 | 0.0 | 0.0 | 0.8 | 2.61 s | 2.02 s | 0.59 s (23 %) | 4.5 min |
+| 3.5 x 3.0 | 100 um / 5 ms (20 mm/s) | 36 x 31 | 5.7 | +0.8 | +0.1 | 30.6 | 0.91 s | 0.18 s | 0.73 s (80 %) | 0.6 min |
+| 3.5 x 3.0 | 40 um / 20 ms (2 mm/s) | 89 x 76 | 0.5 | +2.8 | 0.0 | 2.9 | 2.40 s | 1.78 s | 0.62 s (26 %) | 3.1 min |
+| 3.5 x 3.0 | 10 um / 20 ms (0.5 mm/s) | 351 x 301 | 0.1 | -0.7 | 0.0 | 0.9 | 7.75 s | 7.02 s | 0.73 s (9 %) | 38.9 min |
 
 - **Positioning:** at 0.5 and 2 mm/s the exposure centres are within about 1 um
   rms of the nominal cells, and the snake is symmetric (no slope). A constant
   backward minus forward offset of up to ~4 um remains; it only shifts the field of
-  view. At 20 mm/s an oscillation of X after the acceleration ramp reaches into the
-  line: up to 25-30 um peak-to-peak on the larger fields. That is small compared with
-  the 100 um cells of these quick scans, but above the 20 um resolution target.
-- **Overhead:** about 0.6-0.75 s per line at every speed: run-up and run-out,
-  turnaround, the Y step (during the run-out of X), and the readout of the captured
-  positions (0.03-0.3 s, growing with the points per line). It dominates the quick
+  view. At 20 mm/s a ~10 Hz oscillation of X after the acceleration ramp reaches into
+  the line: up to 25-30 um peak-to-peak on the larger fields. That is small compared
+  with the 100 um cells of these quick scans, but above the 20 um resolution target.
+- **Overhead:** about 0.6-0.75 s per line at every speed. It dominates the quick
   scans (80-94 % at 20 mm/s) and is small for the long high resolution lines.
-- **Uneven positions:** the last column is an estimate, not a measurement: the line
-  period minus the run-up and run-out that could be saved if the frames did not have
-  to sit on an even grid (see below). It will be replaced by measured values of the
-  same scans with `minimal_run_up=True`.
 
-The target resolution is about 20 um; the positioning accuracy should be well below
-that. Columns of the result table:
+### Minimal run-up (`minimal_run_up=True`)
 
-- **Positioning accuracy:** measured exposure centres minus nominal cell centres
-  (rms), and the backward minus forward offset between neighbouring lines. A constant
-  offset only shifts the field of view; a slope along the line would distort it.
-- **Line period:** time from the start of one line to the start of the next.
-- **Exposure per line:** points per line times `exp_time`.
-- **Positioning overhead:** line period minus exposure per line, as an absolute
-  time per line and as a fraction of the scan time. It contains the run-up and
-  run-out, the turnaround, the Y step (done during the run-out of X), and the
-  readout of the captured positions.
-- **Estimate with uneven positions:** if the data analysis could place frames at
-  unevenly spaced positions, the exposures would not have to wait for X to settle at
-  constant velocity, and the run-up could shrink to the braking distance. That saves
-  about `v / a + 2 * settle_time` per line (0.30-0.34 s at 0.5-20 mm/s), on top of
-  any reduction of the other overheads.
+With the minimal run-up X only accelerates to the scan velocity before the first
+exposure (at least 10 um), without the settling distance. The exposures are then
+less evenly spaced, which is acceptable if the data analysis uses the measured
+positions.
+
+| Field of view (mm) | Step / exposure (speed) | Line period default -> minimal | Saved per line | Scan time default -> minimal | rms default -> minimal | bwd - fwd default -> minimal | max deviation default -> minimal |
+|---|---|---|---|---|---|---|---|
+| 0.8 x 1.2 | 100 um / 5 ms (20 mm/s) | 0.78 -> 0.61 s | 0.17 s (22 %) | 0.2 -> 0.2 min | 2.9 -> 7.0 | +1.2 -> +5.6 | 5.8 -> 17.1 |
+| 0.8 x 1.2 | 40 um / 20 ms (2 mm/s) | 1.02 -> 0.88 s | 0.15 s (14 %) | 0.6 -> 0.5 min | 1.0 -> 3.1 | +3.6 -> +13.3 | 4.6 -> 15.9 |
+| 0.8 x 1.2 | 10 um / 20 ms (0.5 mm/s) | 2.20 -> 2.09 s | 0.11 s (5 %) | 4.5 -> 4.3 min | 0.2 -> 1.1 | +0.1 -> -8.9 | 1.0 -> 5.5 |
+| 2 x 2 | 100 um / 5 ms (20 mm/s) | 0.84 -> 0.65 s | 0.19 s (22 %) | 0.4 -> 0.3 min | 5.6 -> 10.0 | +2.3 -> -11.1 | 15.6 -> 24.7 |
+| 2 x 2 | 40 um / 20 ms (2 mm/s) | 1.63 -> 1.48 s | 0.16 s (10 %) | 1.5 -> 1.3 min | 0.6 -> 2.1 | +2.8 -> +13.6 | 4.5 -> 15.9 |
+| 1 x 1 | 10 um / 20 ms (0.5 mm/s) | 2.60 -> 2.50 s | 0.10 s (4 %) | 4.5 -> 4.3 min | 0.2 -> 1.0 | 0.0 -> -9.1 | 1.1 -> 5.4 |
+| 3.5 x 3.0 | 100 um / 5 ms (20 mm/s) | 0.91 -> 0.74 s | 0.17 s (19 %) | 0.6 -> 0.5 min | 5.8 -> 14.0 | +0.8 -> -42.9 | 17.5 -> 44.9 |
+| 3.5 x 3.0 | 40 um / 20 ms (2 mm/s) | 2.39 -> 2.23 s | 0.15 s (6 %) | 3.1 -> 2.9 min | 0.5 -> 1.7 | +2.8 -> +12.8 | 3.9 -> 16.6 |
+| 3.5 x 3.0 | 10 um / 20 ms (0.5 mm/s) | 7.75 -> 7.55 s | 0.19 s (2 %) | 38.9 -> 38.0 min | 0.1 -> 0.6 | -0.7 -> -10.2 | 0.8 -> 5.6 |
+
+- **Time:** 0.10-0.19 s less per line, 19-22 % of the quick 20 mm/s scans, 6-14 %
+  at 2 mm/s, 2-5 % at 0.5 mm/s. About half of what the shorter travel alone would
+  give: with the default run-up the Y step is hidden in the run-out of X; with the
+  minimal run-up X turns around almost at once and waits for Y.
+- **Positions, 0.5 and 2 mm/s:** the first exposure of each line is still at its
+  nominal position (the line trigger is a position), but within the next 2-3 cells
+  the exposures jump to a constant offset, then stay evenly spaced along the line.
+  This is the velocity transient of X after the ramp: the gates are timed, so a
+  velocity below (2 mm/s) or above (0.5 mm/s) the scan velocity right after the
+  trigger shifts all later exposures. The offset has opposite signs in the two
+  directions, so backward and forward lines are 9-14 um apart, without a slope.
+- **Positions, 20 mm/s:** the ~10 Hz oscillation after the ramp is now in the whole
+  line: up to 25 um deviation on 2 mm and 45 um on 3.5 mm fields, with backward
+  minus forward offsets up to 43 um. Well above the 20 um resolution target.
+- **For the data analysis:** use the measured exposure centres, not the nominal
+  grid. In the first 2-3 cells of each line the cells are compressed or stretched,
+  and the centre estimate (start of the gate plus half a gate at the scan velocity)
+  is less accurate there, since X is not yet at constant velocity.
+
+Measured minus nominal X centre along the line, all lines thin, the mean bold
+(left: default run-up, right: minimal run-up):
+
+![2 x 2 mm, 100 um / 5 ms (20 mm/s): the oscillation after the ramp](run_up_deviation_2x2_100um_5ms.png)
+
+![3.5 x 3.0 mm, 100 um / 5 ms (20 mm/s)](run_up_deviation_3p5x3_100um_5ms.png)
+
+![2 x 2 mm, 40 um / 20 ms (2 mm/s): constant offset after the first cells](run_up_deviation_2x2_40um_20ms.png)
+
+![1 x 1 mm, 10 um / 20 ms (0.5 mm/s)](run_up_deviation_1x1_10um_20ms.png)
+
+Measured exposure centres of the first cells of the first lines against the nominal
+cell centres (crosses), forward lines blue, backward lines orange:
+
+![2 x 2 mm, 100 um / 5 ms (20 mm/s)](run_up_zoom_2x2_100um_5ms.png)
+
+![2 x 2 mm, 40 um / 20 ms (2 mm/s)](run_up_zoom_2x2_40um_20ms.png)
+
+![1 x 1 mm, 10 um / 20 ms (0.5 mm/s)](run_up_zoom_1x1_10um_20ms.png)
+
+### Where the time per line goes
+
+Split of the line period, measured by the scan (`motion` = X through the line and the
+trigger check, `between lines` = waiting for Y and switching the trigger window):
+
+| Case | Run-up | Line period | Motion | Capture readout | Between lines |
+|---|---|---|---|---|---|
+| 0.8 mm, 20 mm/s | default -> minimal | 0.77 -> 0.58 s | 0.60 -> 0.29 s | 0.03 s | 0.14 -> 0.26 s |
+| 0.8 mm, 2 mm/s | default -> minimal | 1.03 -> 0.88 s | 0.87 -> 0.62 s | 0.04-0.05 s | 0.12 -> 0.21 s |
+| 2 x 2 mm, 2 mm/s | default -> minimal | 1.64 -> 1.48 s | 1.47 -> 1.21 s | 0.05-0.06 s | 0.12 -> 0.21 s |
+
+The next levers to reduce the overhead:
+
+- **Y step:** Y moves with 10 mm/s^2, so a 100 um step takes ~0.2 s, plus a 0.1 s
+  hold within the tolerance before the next line starts.
+- **Software latency:** roughly 0.15-0.2 s per line in the motion phase for the end
+  of the move, the trigger check and the communication.
+- **Capture readout:** 0.03-0.3 s per line, growing with the points per line.