Jungfraujoch/docs/RUGNUX_CALIBRATION.md

# Detector calibration from powder rings (`rugnux --mode calibration`)


The `calibration` mode determines the detector geometry — PONI *x*/*y*, the two tilts
rot1/rot2 and the distance — from the powder rings of a calibrant, and writes it as a
pyFAI **`<prefix>.poni`** file and a machine-readable **`<prefix>.json`**, alongside a printed
report of how far each parameter moved from the header. Bragg data pin the beam centre worst (it is gauge-coupled to the crystal orientation);
a powder ring has no orientation to be coupled to, so this is the measurement that fixes it.

```
rugnux --mode calibration --calibrant lab6 -o det LaB6_master.h5
```

## What it writes

`<prefix>.poni` is for pyFAI and the tools that read its format. `<prefix>.json` is for everything
else, and has two members:

* **`dataset_settings`** — the geometry under the property names
  [`dataset_settings`](https://jungfraujoch.readthedocs.io) gives them in `jfjoch_broker`'s OpenAPI
  schema, and nothing else. It is a valid `dataset_settings` body as it stands, so it can be POSTed
  or merged into one without translating a field:

  ```
  curl -X POST -H 'Content-Type: application/json' \
       -d "$(jq -c .dataset_settings det.json)" http://broker:5232/start
  ```

  `beam_x_pxl`/`beam_y_pxl` is the **PONI**, as everywhere in this system — on a tilted detector it
  is not where the direct beam lands. The three `poni_rot*_rad` are written whenever any of them is
  non-zero, and left out when all are zero: a body that omits them states a *flat* detector, so they
  travel together or not at all.

* **`calibration`** — what the run knows about that geometry: the residual, the fit's own sigmas and
  the correlation between the tilt and the beam centre, whether the tilt cleared its significance
  test or was declined and pinned, where the direct beam lands, and where the spots independently
  put the beam. A calibration that has gone wrong looks exactly like one that has not until those
  are read.

`--calibrant` takes `lab6`, `agbh` (silver behenate), `ceo2`, `si` or `ice`, case-insensitively.
**`ice`** calibrates a real experiment against its own ice rings — no calibrant exposure needed —
and is the reason a calibrant is a list of ring positions rather than a unit cell: hexagonal ice
is P6<sub>3</sub>/mmc, so rings enumerated from its cell would include systematically absent ones.

`--calibration` picks how the rings are measured, and **both aggregate over every processed image** — `-s`/`-e`/`-t`
select which images:

- **`rings`** (default) sums the (*q* × azimuth) azimuthal profile over every processed image into
  one map and fits the ring arcs in it. A powder ring is an arc, not a set of spots, and the summed
  profile measures it at every azimuth with all the run's counts behind it. It needs the profile to
  be binned in azimuth, so this mode defaults `--azim-phi-bins` to 32.
- **`spots`** pools the found spots of every processed image and fits those. It determines the
  centre from scratch (a Hough circle vote, which quantises it to a whole pixel) and then refines.

Both routes read the ring position out of a binned profile or a spot centroid, so the radial
sampling matters: at a long detector distance the default 0.01 Å⁻¹ *q* bin is several pixels wide
and quantises the `rings` route accordingly — pass a finer `--azim-q-spacing` there (the total
*q* × azimuth bin count must stay under 65534).

The report prints the fitted geometry, the scatter of the ring points about the fitted rings and the
standard error that implies on the centre. That error is *formal*: it measures the scatter of the
points, not whether the rings themselves are trustworthy, so it stays small when a fit goes wrong
for a structural reason — one visible ring, or ice that is textured rather than smooth.

A calibration is run because the header is in doubt, so a fit that quietly hands part of that header
back has answered nothing — and it looks exactly like a fit that worked, down to the residual and the
sigmas around it. **`calibration.converged`** in the JSON says which of the two a file is. It is false
when the tilt was declined and pinned at a *non-zero* header value — the rings said they could not tell
a tilt from a shift of the beam centre, and the angle written in its place has no more support than the
one refused — or when the fit's covariance never conditioned, so it cannot say what it determined. In
either case Rugnux prints the reason, writes the `.json` with `converged` false and
`not_converged_reason` beside it, exits non-zero, and writes **no `.poni`**: a PONI file states where
the detector is and has no field in which to say that it does not know. A declined tilt over a header
that states *no* tilt is not this — reporting no tilt is then exactly what the fit measured.

A `.poni` is refused for a second reason, whatever the fit found: a detector whose **image
orientation** is not the identity — the stored image mirrored in Y, or turned by a multiple of 90°
about the beam. That comes either from `--detector-mirror-y` / `--detector-quarter-turns` or from the
file itself (a PILATUS miniCBF axis table, an NXmx module's pixel directions). A PONI states the
detector in five numbers — two offsets, a distance and three rotations — and has no field for how the
image is stored, so one written here would describe a different geometry from the one that was
measured. The run says so and exits non-zero.

`--no-refine-tilt` holds rot1/rot2 where the header put them and fits only the centre and the
distance. The tilt is real and worth measuring, but a program that has nowhere to put one — XDS
takes a detector normal to the beam — is better given a geometry that was measured with the tilt
pinned than one that was measured tilted and then flattened, because in the tilted fit the centre
and the distance have already absorbed the tilt.

Both the PONI (the point of normal incidence, which is what a `.poni` file stores) and the direct
beam (where the beam lands, which is what most other programs call the beam centre) are printed.
They differ by *distance* × tan(rot) once the detector is tilted, which on a 0.3° tilt at 300 mm is
several pixels — enough to look like a disagreement with another program when there is none.