add: unbinned detector calibration, unit normalization, and tilt (3/4)

[pecomyint]

Stack 3 of 4. Base rsm/02-naxis-issue132 — retarget to main as the stack merges.

Draft: this is the beam-physics gate. The axis-0 mapping and the tilt/detrot sign conventions cannot be settled without a known reflection. Everything else is verified against xrayutilities directly.

Two silent assumptions removed

DETECTOR_SETUP.UNITS was in every profile and never read, so millimetres were assumed regardless of what the beamline declared. Energy was blindly × 1000, correct only for a keV source. Both produced a plausible-looking, wrong Q with no error.

New dashpva/utils/units.py is one table for length, energy and angle; internal geometry is always eV, mm, degrees. Unknown units raise rather than defaulting — a mis-declared unit is a calibration error, and guessing would reintroduce exactly what this removes. Per-field DISTANCE_UNITS / SIZE_UNITS / PIXEL_SIZE_UNITS override the section default. ENERGY_UNITS defaults to keV so existing profiles keep their scale.

Units are validated at parse time but converted only when the DetectorModel is built. Converting during normalization would leave the stored value and stored unit disagreeing, so a second pass would convert again — caught by the idempotence test.

The binning bug

pixel_width = SIZE / frame_shape silently absorbed binning into the pixel size: a 2×-binned scan produced a Q scale wrong by a factor of two, with no error raised.

center_channel, shape and pixel_width are now explicitly the unbinned full-frame calibration. ROI and binning go to xrayutilities as roi/Nav, which applies them itself — verified in QConversion._get_detparam_area, which does cch/nav, pwidth*nav, and maps an unbinned ROI into binned channels. Pre-shifting the centre here would double-apply that. The legacy SIZE/frame_shape derivation is now permitted only for full-frame unbinned data and rejected by name otherwise.

ROI is half-open in unbinned channels and its span must divide exactly by the binning — xrayutilities would otherwise ceil it and hand back a frame larger than the detector produced. require_frame_shape() rejects a calibration that disagrees with the data instead of yielding a plausible, wrongly-scaled volume.

New degrees of freedom

DETROT / TILT / TILTAZIMUTH, and FRAME_AXIS_ORDER making the detector axis-0 convention explicit and configurable — a transposed volume becomes a profile edit rather than a source change. Q is transposed to the acquired layout so intensity, mask and Q index identically.

detector_model_from_setup() is the single boundary where declared units become canonical; the offline converter and both live paths go through it, and a setup with none of the new keys reproduces the previous model exactly.

Verification

test_detector_physics.py — every Q assertion checked against a hand-built xu.HXRD, not a stored value, so it fails if we stop agreeing with xrayutilities rather than merely changing. Unit equivalence (keV/eV, cm/mm/µm give identical Q), ROI+binning parity at atol=0, exact-divisibility rejection, frame-axis transposition, tilt/detrot parity, and sampleor='det' continuity as detrot → 0 (detrot appends a beam-axis rotation as the innermost detector axis; 'det' ignores beam-parallel rotations, so the limit must be smooth). I also mutation-checked that tilt and detrot genuinely move Q, so the parity tests are not vacuous.

Calibration literals persist to HDF5 through a type-preserving writer — the plain string writer would have reintroduced the repr bug fixed in 687e943.

Blocked on beam

• Detector axis-0 mapping against a known Bragg peak
• Tilt / detrot sign conventions vs the beamline's own calibration

[pecomyint]

@Osayi-ANL when you get a chance — this one is still unreviewed and it's the beam-physics gate for the trip.

It's the PR whose correctness can't be settled from CI: the detector axis-0 mapping and the tilt/detrot sign conventions need a known reflection. A wrong axis-0 produces a transposed volume that still looks like a plausible diffraction pattern, so it needs a second pair of eyes on the reasoning before we rely on it at the beamline.

Everything else in it is checked against a hand-built xu.HXRD rather than stored values — unit equivalence, ROI+binning parity at atol=0, and sampleor='det' continuity as detrot → 0.

Rebased onto the fixed rsm/02, so git pull first.

[pecomyint]

Nudging — this one's still unreviewed and it's the beam-physics gate for the whole stack (unbinned detector calibration, unit normalization, tilt/detrot). #136 is approved, #137 and #139 have fixes in for your latest comments and are re-requested. Would appreciate a look here when you get a chance.