docs(flomni): FZP calibration / range how-tos updated for the PREEMPT_RT loop (original text kept) #337

Merged
holler merged 1 commits from docs/flomni-fzp-howto-update into main 2026-10-20 23:21:46 +02:00
4 changed files with 164 additions and 0 deletions

No files matched your search

@@ -0,0 +1,128 @@
# How to calibrate the FZP scanner of flOMNI
Source of `local_contact_only-howto_calibrate_the_fzp_scanner.pdf`. The original text is kept unchanged; the
section "Update 2026-10-20" at the end lists what the present flOMNI loop (PREEMPT_RT, 100 µs, branch `rt_preemt`)
needs in addition.
```text
This is a description of how to calibrate the FZP scanner of flOMNI
Rmemeber to do all modifications for both directions x and y!
1. Align flOMNI without the FZP scanner. This implies disabling the
FZP scanner completely. To do so, in OrchestraHMI edit the parameters
of the FZP scanner as follows.
(a) Module PID_i_FZP: Set Param FAST_FZP_PID_LOOP(0) to 2. Then the FZP
will just remain
statically centered to the capacitive sensor position in closed loop.
(b) Module PID_i: Set Param FAST_FZP_PID_LOOP(0) to 0. If this is
negative, the FZP scanner will move ahead in a point-by-point scan by
that amount.
(c) Module PID_i: Set Param FAST_FZP_PID_LOOP(5) to 0. If this is
larger than zero the sample stage motion is stopped if the position is
reached by the FZP scanner (which is the case when the scanner is not
active). Zero means thus full compensation by the sample stage.
In this state the setup can be aligned, and the affine matrix for
ptychography can be found. This refers then purely to the alignment of
the interferometer and X-ray detector.
2. In the next step we perform a scan (with a small beam and small
range) such that only the FZP scanner is used and the sample stage
will not move.
Before we start ensure that the Correction Matrix for the capacitive
sensors is cleared.
To do this change the parameters of the flOMNI control
loop as follows:
(a) Module AnalogInput_6259: Set parameter MatrixCorr to 1 0 0 1
(b) Module PID_j_fzp: Set Param FAST_FZP_PID_LOOP(0) to 1 to re-activate
the FZP scanner.
(c) Module PID_i: Set Param FAST_FZP_PID_LOOP(5) to 10, so up to 10
volts output of the fast PID is accepted before starting a movement of
the sample stage.
(d) Module PID_i: Param FAST_FZP_PID_LOOP(4) 0
(e) Module PID_i: Param FAST_FZP_PID_LOOP(6) 1
with d and e it will now stabilize the sample stage position at zero
(f) Module PID_i: Param FAST_FZP_PID_LOOP(0) remains 0 (no move ahead
in a scan)
With these settings perform a scan. Use a field of view matching the
range of the FZP scanner. Watch the sample stage position in Orchestra
to ensure it does not change!
A good range should be 2.8 microns in x and 1.8 microns in y.
Reconstruct this scan with Michal's position refinement code and ask
for an update of the FZP matrix. This can then be put into the
AnalogInput_6259 module.
I guess one has to have the matrix found for the interferometer in the
reconsturction code, such that the new matrix of the FZP scanner will
adjust the coordinate system of the FZP scanner to the system of the
interferometer. Later these positions are used together and should
match in direction.
3. Back to default operating values:
(a) Module PID_i: Set Param FAST_FZP_PID_LOOP(0) to -0.5, for up to
0.5 microns move ahead in a scan.
All other parameters are already as supposed to be.
Default values for the sample stage pid, fast FZP parameter are "-
0.5,0,0,0,0.1,0.5,0"
Default values for the fzp pid, fast FZP parameter are "1,0.0001,0.1,-
4,0,0,0"
```
## Update 2026-10-20 (flOMNI loop on PREEMPT_RT, mpc2844)
The loop has new modules since the text above was written (flOMNI `FeedbackLoop/tuning_guide.md`,
`feedback_report.md` 5.6, 6n, 6o, 6q). Parameters are changed in the web HMI (`http://mpc2844:8080`, tab
Parameters) instead of OrchestraHMI. `i` = x or y, as above. Module names now: `PID_x`, `PID_y` (sample stage),
`PID_x_fzp`, `PID_y_fzp` (FZP scanner), `AnalogInput_6289` (was `AnalogInput_6259`).
**FAST_FZP_PID_LOOP has 7 elements** (`PID.cpp`). Sample stage PIDs: (0) move-ahead (negative, µm, point-by-point
scans only), (4) FZP error threshold (µm) and (5) FZP drive limit (V) for holding the sample stage while the FZP
takes the step (5 = 0: never held), (6) 1 = hold the sample stage at 0. FZP PIDs: (0) mode (1 operation, 2 FZP
centred on its cap sensor = disabled, 3 not commissioned, 4 debug), (1)–(3) min / max / gain of the old velocity
correction (−4 before 2026-10-19, now 0: replaced by the feedforward).
**In addition to step 1 (FZP disabled):**
- `Feedforward`: `enable` 0,0 — the static FZP feedforward adds its drive also in FZP mode 2.
- `AbbeCorrection`: `enable` 0 (default until the signs are known).
- `TargetSelect_x`, `TargetSelect_y`: `use_final` 0; `OnTargetTrigger`: `WaitForSlew` 1 (defaults).
- `FreqGen`: `enable` 0 (excitation for measurements; default).
**In addition to step 2 (FZP-only calibration scan):**
- FZP range: `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` are ±1.5 V in operation (the cap sensors are calibrated over
about ±2 V only). For the field of view above (2.8 × 1.8 µm) widen them, e.g. to ±10 V (FZP ≈ 0.13 µm/V in x,
≈ 0.05 µm/V in y). The feedforward stays off (`enable` 0,0) during this scan.
- The detector trigger (`OnTargetTrigger`) checks the relative error sample vs FZP (tolerance / hold time from the
ConstEmitter, BEC `interferometer_trigger_*`, default 10 nm / 3 ms) and waits `MinDelay_ms` (15 ms).
**Step 3, default operating values (replace the values in the text above):**
| Module | Parameter | Value |
|---|---|---|
| `PID_x`, `PID_y` | `FAST_FZP_PID_LOOP` | `0,0,0,0,0.1,0,0` (no move-ahead: −0.5 µm does not fit the ±1.5 V FZP range) |
| `PID_x_fzp` | `FAST_FZP_PID_LOOP`, `Ub` / `Lb` | `1,0.0001,0.1,0,0,0,0`, ±1.5 V |
| `PID_y_fzp` | `FAST_FZP_PID_LOOP`, `Ub` / `Lb` | `1,0.0005,0.02,0,0,0,0`, ±1.5 V |
| `Feedforward` | `enable`; `ff_limit`, `out_min` / `out_max` | 1,1; ±1.5 V (as the FZP `Ub` / `Lb`) |
| `OnTargetTrigger` | `WaitForSlew`, `MinDelay_ms` | 1, 15 |
| `TargetSelect_x`, `TargetSelect_y` | `use_final` | 0 |
| `AbbeCorrection` | `enable` | 0 (until the signs are known) |
| `AnalogInput_6289` | `MatrixCorr` | the new matrix from the calibration |
Check afterwards: web HMI tab **Loop check**, level 1 (it expects these values and lists live values that differ
from the `.xmp` files); save the new values as default (Parameters → Unsaved changes) or in the `.xmp`.
**After the calibration (per experiment): faster scans, exposure during the motion.** With the FZP calibrated
over a wider range the FZP can take the small steps alone (flOMNI `feedback_report.md` 6q, tested at ±7 V):
- `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` and the `Feedforward` limits to the calibrated range (e.g. ±7 V);
- `TargetSelect_x` / `_y` `use_final` 1 (the FZP aims at the new point at once, the sample stage follows its
S-curve) and `OnTargetTrigger` `WaitForSlew` 0 (trigger on the relative error only); optionally `MinDelay_ms` 0;
- optionally move-ahead, sized to the FZP range: `PID_x` (0) e.g. −0.5, `PID_y` (0) e.g. −0.2.
Measured with 101 ms exposures: 0.2–1 µm steps trigger after 4.5–5.8 ms instead of 17–32 ms; the error during the
exposure grows with the step (1 µm: ≈ 6 nm max instead of 2.5 nm), so the setting depends on the experiment.
@@ -0,0 +1,36 @@
# How to limit the FZP scanner range of flOMNI
Source of `local_contact_only-howto_limit_the_fzp_scanner_range.pdf`. The original text is kept unchanged; the
section "Update 2026-10-20" lists what the present flOMNI loop (PREEMPT_RT, 100 µs, branch `rt_preemt`) needs in
addition.
```text
to limit the fzp scanner ranges
in PID_ FAST FZP PID LOOP
0: reduce to small ahead movement range, such as -0.05
4: reduce error threshold, eg 0.01
5: inform PID that FZP range is small, such as 0.1
in PID_ _FZP
limit the analog output LB and UB
```
## Update 2026-10-20 (flOMNI loop on PREEMPT_RT, mpc2844)
The limited range is the present operating state: `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` = ±1.5 V because the cap
sensors are calibrated over about ±2 V only (flOMNI `feedback_report.md` 6n). FZP ≈ 0.13 µm/V in x, ≈ 0.05 µm/V in y,
so ±1.5 V ≈ ±0.19 µm (x) / ±0.08 µm (y). In the sample stage PIDs (`PID_x`, `PID_y`) `FAST_FZP_PID_LOOP` is
`0,0,0,0,0.1,0,0`: no move-ahead, (5) = 0 (the sample stage always compensates fully).
Changing the FZP range now involves, in addition to the text above:
- **`Feedforward`** (static FZP feedforward): `ff_limit`, `out_min` / `out_max` to the same values as the FZP `Ub` /
`Lb` (they limit drive + feedforward).
- **`FreqGen`** `out_min` / `out_max` (channels 0 / 1) limit the FZP drive only while an excitation is running
(measurements).
- **`OnTargetTrigger`** `WaitForSlew` and **`TargetSelect_x` / `_y`** `use_final`: keep the defaults (1 / 0) with a
small range. `use_final` 1 + `WaitForSlew` 0 ("exposure during the motion") only makes sense when the FZP range
covers the scan step; steps larger than the range then still wait for the sample stage.
- Move-ahead (0) must fit into the range: at ±1.5 V at most ≈ −0.05 µm (x) — so in operation it stays 0.
- After a change: web HMI tab **Loop check** level 1 (expected settings) and, with the beamline ready, the scan test
(level 4: positioning time, stability during the exposure per step size).