From 64182bb2959cb21aa08f7289f599a2fd4ce4b7d8 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Wed, 2 Sep 2026 09:05:54 +0200 Subject: [PATCH] docs: an overview page - what a rugnux run does, in order The page that did not exist: one paragraph per stage from opening the file to the written reflections, each linking into the data-analysis reference part that carries the depth, with the stills differences at the end. First entry after the landing page, and the landing page says to read it first. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01EFEJG6WBQv8th4UJFNe53N --- docs/RUGNUX.md | 2 ++ docs/RUGNUX_OVERVIEW.md | 63 +++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 66 insertions(+) create mode 100644 docs/RUGNUX_OVERVIEW.md diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index 63b74c4ed..2013cdc35 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -113,6 +113,8 @@ A few things worth knowing before reaching for more flags: One page per job, so the answer needed is near the top of a short page: +- [What a rugnux run does](RUGNUX_OVERVIEW.md) — the pipeline from images to merged reflections, + in order. Read this one first. - [Installing rugnux](RUGNUX_INSTALL.md) — packages, the release archive, GPU drivers, building from source, hardware. - [What rugnux reads](RUGNUX_FORMATS.md) — will it open your data: NXmx / EIGER masters, PILATUS diff --git a/docs/RUGNUX_OVERVIEW.md b/docs/RUGNUX_OVERVIEW.md new file mode 100644 index 000000000..d2b31deeb --- /dev/null +++ b/docs/RUGNUX_OVERVIEW.md @@ -0,0 +1,63 @@ +# What a rugnux run 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 and centring are read from the systematic +absences ([§13.1](CPU_DATA_ANALYSIS_DECISIONS.md)); twinning is 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 +CC½-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 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)). diff --git a/docs/index.rst b/docs/index.rst index e1916889d..66b7d45be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,6 +19,7 @@ Jungfraujoch is distributed under the GPLv3 license. :caption: rugnux — data processing RUGNUX + RUGNUX_OVERVIEW RUGNUX_INSTALL RUGNUX_FORMATS RUGNUX_TUTORIAL