leonarski_fandClaude Fable 5
70c4d871b6
- Capitalize Rugnux as a proper noun throughout the prose; the command stays lowercase `rugnux` in code font. RUGNUX_OVERVIEW.md is retitled "What Rugnux does". - ACKNOWLEDGEMENT.md cites the raw-data repositories only: dataset counts and DOI prefixes moved out (EXTERNAL_TEST_DATA.md owns them), the ESRF data portal gains its citation (Dimper et al. 2019), and MXRDR remains name + link - it has no canonical citation paper. - RUGNUX_FORMATS.md: the CCD formats (marCCD, SMV) are supported as-is with very limited scope, and per-panel XFEL data is not read. - Fix wrong facts a reader would act on: nonexistent `make jfjoch` targets, invalid udev rules, PUSH sockets documented as PULL, swapped writer width/height, underload semantics, the transposed pixel-mask numpy example (the server checks width and height separately), the Durin/Neggia mask-bit table, FPGA threshold register addresses and the mailbox bit field, the I2C core's document number (PG090), an inverted MODEL_FIT_SIGMA formula, a self-inconsistent worked report example, and 11 cross-page anchors whose slugs carry MyST section numbers. - Unify CC1/2 spelling in prose; math notation and report keys unchanged. - Sweep grammar, typos and editing residue across the FPGA, deployment, streaming and analysis pages, including historical CHANGELOG typos. - rugnux_cli.cpp: the -S usage/error examples pair 96 with P43212; 92 names a different group. - Root THIRD_PARTY_NOTICES.md: scope the GPL-compatibility claim (CUDA EULA) and the vendored-table intro (traccc); the docs copy regenerates via update_version.sh. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
64 lines
4.1 KiB
Markdown
64 lines
4.1 KiB
Markdown
# 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)).
|