Jungfraujoch/docs/RUGNUX_OVERVIEW.md

# What Rugnux does

The map of a run, in the order it happens — one paragraph per stage, each linking into the
[data-analysis reference](CPU_DATA_ANALYSIS.md) where the algorithm lives. The walk-through is a
rotation run with the defaults; stills differences are at the end.

**Open the dataset.** The geometry, wavelength and goniometer come from the file
([What Rugnux reads](RUGNUX_FORMATS.md)). A goniometer axis makes it a rotation run, none makes it
serial stills — nothing is asked of the user.

**Pre-scan.** A projection of the first frames (60 by default) finds the beam-stop shadow and masks
it ([§1.5](CPU_DATA_ANALYSIS_IMAGE.md)), measures the beam centre from the isotropy of the
scattered background and compares it with the file's ([§1.4](CPU_DATA_ANALYSIS_IMAGE.md)), and
reads how wide this crystal's spots are, which sets the integration radius
([§9.5](CPU_DATA_ANALYSIS_INTEGRATION.md)).

**Spots.** Every image is decoded — on the GPU straight from the compressed chunk
([§0](CPU_DATA_ANALYSIS_IMAGE.md)) — and one fused pass computes the azimuthal profile and finds
the spots against each image's own per-resolution-ring noise
([§2–§3](CPU_DATA_ANALYSIS_IMAGE.md)). The ice-ring score is read off the same profile.

**Indexing.** The spots of a sample of frames are rotated back to a common crystal frame and the
FFT search looks for periodicity over thousands of directions; candidate cells are
Niggli-reduced, classified by Bravais lattice, refined both constrained and triclinic, and decided
on how many validation frames each actually indexes
([§4–§7](CPU_DATA_ANALYSIS_INDEXING.md)). A failed pass triggers the discrete rescues — the
rotation-axis sign, the beam-centre search — before anything is given up on.

**First integration pass.** At the geometry in the file, every frame is predicted
([§8](CPU_DATA_ANALYSIS_INTEGRATION.md)) and profile-fit integrated
([§9](CPU_DATA_ANALYSIS_INTEGRATION.md)); partials are combined into fulls, scaled and merged
([§10](CPU_DATA_ANALYSIS_INTEGRATION.md)).

**Geometry post-refinement.** From those reflections the detector distance, beam centre and the
cell scale / rotation axis are refined over all frames at once, each step committed only if it
improves a held-out residual ([§7.5](CPU_DATA_ANALYSIS_INDEXING.md)).

**Second pass.** The sweep is re-indexed de novo and re-integrated at the refined geometry; this
pass is the canonical output, and a guard compares the two passes and keeps the better one
(reported as `PASS=` / `PASS_DECISION=` in [the report](RUGNUX_REPORT.md)).

**Space group.** On the P1 merge of the final pass, the point group is scored operator by operator
on resolution-normalised intensities and the screw axes, glide planes and centring are read from the
systematic absences ([§13.1](CPU_DATA_ANALYSIS_DECISIONS.md)); twinning and translational
pseudo-symmetry are checked beside it ([§13.2](CPU_DATA_ANALYSIS_DECISIONS.md)). `CANNOT_DETERMINE` and an enantiomorphic pair are real
answers here, not evasions.

**Scale and merge.** In the determined group: per-frame scales, the cross-validated correction
surfaces (decay, absorption, modulation), the error model and ISa, outlier rejection, the
CC1/2-based resolution cut, the anisotropy description, French–Wilson amplitudes and the R-free
flags ([§10](CPU_DATA_ANALYSIS_INTEGRATION.md),
[§13.3–§13.5](CPU_DATA_ANALYSIS_DECISIONS.md)).

**Write.** The merged `.mtz` / `.cif` / `.hkl`, the unmerged MTZ, the P1 cross-check and the
results report land next to each other ([Output files](RUGNUX_TUTORIAL.md#output-files)); with
`--model`, validation runs first and the maps and the placed model are written too
([§14](CPU_DATA_ANALYSIS_DECISIONS.md)).

**Stills instead.** Serial data skip the two-pass machinery: each image is indexed independently
(with the known-cell `ffbidx` indexer where a cell is given), partiality comes from a per-crystal
orientation-tilt post-refinement rather than a rocking curve, and a merohedral indexing ambiguity
has to be broken per image, at integration time, against a reference or a model
([Advanced ▸ the indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity)).