From 14cb819f76b38b364009f13b0a7ddae7e43ea04b Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Tue, 10 Nov 2026 16:38:52 +0100 Subject: [PATCH] docs: plain wording and headings on the Rugnux pages Rewrite ten passages of the Rugnux pages in plain, direct sentences and rename the headings written in the "What X does" style: Output files, Terminal output, Manual pages, The three analysis tools (RUGNUX.md), Overview (RUGNUX_OVERVIEW.md), Input formats (RUGNUX_FORMATS.md), Out of host memory (RUGNUX_INSTALL.md), Reference data (RUGNUX_ADVANCED.md), The model and the space group (RUGNUX_MODEL_AND_REFERENCE.md), The disposition column (RUGNUX_REPORT.md), with every link text and anchor that named them. Co-Authored-By: Claude Fable Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- docs/JFJOCH_VIEWER.md | 2 +- docs/RUGNUX.md | 50 +++++++++++++++--------------- docs/RUGNUX_ADVANCED.md | 2 +- docs/RUGNUX_CLI.md | 2 +- docs/RUGNUX_FORMATS.md | 2 +- docs/RUGNUX_INSTALL.md | 2 +- docs/RUGNUX_INTEGRATION.md | 2 +- docs/RUGNUX_MODEL_AND_REFERENCE.md | 2 +- docs/RUGNUX_OVERVIEW.md | 4 +-- docs/RUGNUX_REPORT.md | 2 +- docs/RUGNUX_TUTORIAL.md | 13 ++++---- 11 files changed, 41 insertions(+), 42 deletions(-) diff --git a/docs/JFJOCH_VIEWER.md b/docs/JFJOCH_VIEWER.md index 03824237b..7103a42e2 100644 --- a/docs/JFJOCH_VIEWER.md +++ b/docs/JFJOCH_VIEWER.md @@ -26,7 +26,7 @@ newer on an Apple Silicon Mac** (M1 and newer; Intel Macs are not supported) and `*_process.h5` files produced by [`rugnux`](RUGNUX.md). It also opens NXmx files written by DECTRIS detectors, though that path has had only limited testing. - Opens PILATUS miniCBF, marCCD and SMV rotation sweeps (the formats listed under - [What Rugnux reads](RUGNUX_FORMATS.md)). These store one frame per file, so naming any frame opens + [Input formats](RUGNUX_FORMATS.md)). These store one frame per file, so naming any frame opens the whole sweep it belongs to. A raw frame carries the images and the geometry but no analysis results, so the spot, reflection and per-image plot panels stay empty until something is computed. A processing job on such a sweep writes the images into its `_process.h5`, and its run is shown from diff --git a/docs/RUGNUX.md b/docs/RUGNUX.md index 01b18a096..cc2cfb3d2 100644 --- a/docs/RUGNUX.md +++ b/docs/RUGNUX.md @@ -32,9 +32,9 @@ name); a directory is refused. Rotation sweeps are not read together. Given the URL of a `jfjoch_broker` (`http://host:port/`) and the path the master file *will* have, `rugnux` follows the broker's current collection while it is being written: the data files are read as the broker reports them closed, processing starts on the first images, and the run ends with the -images the collection delivered. A choice made early on a near tie is checked again on every frame -once all are in, and the run is made again where that check ends elsewhere, so the answer is the one -the whole sweep gives. This is for rotation data and `--mode mx`; the collection's token is read from +images the collection delivered. A decision made early on a near tie is re-checked on all frames +once the collection is complete. If the check gives a different answer, the run is repeated, so +the result is that of the whole sweep. This is for rotation data and `--mode mx`; the collection's token is read from `JUNGFRAUJOCH_HTTP_TOKEN` and sent only to the broker. With the master file already on disk, the URL is ignored. @@ -114,7 +114,7 @@ consistently but in an arbitrary one of the two. A reference reflection file (`- also accepted as a positional input) does the same, and steers the processing from the start (see [Models and reference data](RUGNUX_MODEL_AND_REFERENCE.md)). -### What comes out +### Output files A rotation run that merges — the default — leaves these files next to each other: @@ -147,13 +147,13 @@ detector of several modules, `serial_module_placement.json` with where each modu `serial_modules.h5` where the refinement moved some). [Output files](RUGNUX_TUTORIAL.md#output-files) lists every file a run can write. -Parallelism needs no asking for: a run already uses the machine's threads. `-N` is there to *limit* -that, or to lift the per-image loop's default ceiling of 16 workers per GPU. +A run uses all the machine's threads by default. `-N` limits the thread count, or raises the +per-image loop's default ceiling of 16 workers per GPU. Read `myrun_report.txt` first: it says which space group was chosen and on what evidence, how far the data go, and anything that needs attention. -### What the terminal shows +### Terminal output The terminal shows the run as numbered steps, each with one-line results and the time it took, the warnings among them, and a summary at the end; everything else goes to `myrun_log.txt`. A note's @@ -197,25 +197,25 @@ the whole log on the terminal in place of the steps. The log file carries what i question about a run without the data: version, build, GPU, threads, the command line, the header geometry, every decision with its numbers, and a timestamp on every line. -A few things worth knowing before reaching for more flags: +Notes on the defaults: -- **The written reflections stop where CC1/2 falls through 0.30.** Every reflection file is +- **The reflection files are cut at the resolution where CC1/2 drops below 0.30.** Every reflection file is resolution-trimmed automatically (`--resolution-cutoff cc-logistic`, one shell past the crossing); `--resolution-cutoff off` keeps the full measured range, `--scaling-high-resolution` fixes the - limit by hand. A Rugnux file reaching less far than another program's on the same data is usually - this default at work, not lost data. -- **Rotation data are best left de novo.** Pinning the cell and space group (`-C`, `-S`) is the - normal thing to do for **serial stills**, where the `ffbidx` indexer needs a cell; on a rotation - sweep it tends to *degrade* low-symmetry cases, so give the images alone and let the run determine both + limit by hand. If a Rugnux file reaches lower resolution than another program's on the same data, + this cutoff is usually the reason, not missing data. +- **Do not give `-C` or `-S` for rotation data.** A known cell and space group are useful for + serial data, where the `ffbidx` indexer needs a cell. On rotation data they often make + low-symmetry cases worse. Let the cell and space group be determined from the data (see [Rotation data](RUGNUX_TUTORIAL.md#rotation-data)). `-S` takes a Hermann-Mauguin symbol (`P43212`) or a space-group number (`96`), whichever is to hand. -- **Anomalous data are there without `-A`.** A rotation merge always keeps the Bijvoet split: a +- **`-A` is not needed to keep the anomalous signal.** A rotation merge always keeps the Bijvoet split: a default run's `.mtz` carries `I(+)`/`I(-)` beside `IMEAN`, and its `.hkl` every observation at the index it was measured at — `FRIEDELS_LAW= TRUE` in the report says how the *statistics* were counted, not that the signal was averaged away. What `-A` changes is the counting basis and the error model: each hand becomes a merged observation of its own, so multiplicity, completeness and ⟨I/σ⟩ are counted anomalously and - the sigmas are refitted on the Bijvoet-separated merge. Reach for it for anomalous statistics; the - signal itself is in the file either way. (Stills merges carry no split by default — there `-A` is + the sigmas are refitted on the Bijvoet-separated merge. Use `-A` when anomalous statistics are wanted. + The signal is in the file in either case. (Stills merges carry no split by default — there `-A` is what creates one.) - **A model names the enantiomorph.** Where the data accept the model — it is tested against a null of the same model in random orientations, and `MODEL_FIT=` in the report says the verdict — @@ -231,8 +231,8 @@ A few things worth knowing before reaching for more flags: [indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity) in its own indexing. On serial data the ambiguity decides whether the merged intensities are usable at all; there the space group (`-S`) alone already lets the run make the crystals consistent from the data. -- **Small molecules need no flag either.** Short axes, spots wider than the integration disk and - glide-plane space groups are handled by the default run, and `myrun.hkl` goes straight to SHELXT / +- **Small-molecule data need no extra options.** Short axes, spots wider than the integration disk + and glide-plane space groups are handled by default. `myrun.hkl` can be given directly to SHELXT / SHELXL ([Small-molecule data](RUGNUX_TUTORIAL.md#small-molecule-data)). - **`--scaling-high-resolution `**, where the resolution is already known, sharpens both the space-group search and the error model. @@ -247,23 +247,23 @@ A few things worth knowing before reaching for more flags: nothing most often has a wrong header: the beam centre is measured on every run, but the distance and the wavelength are indexed at the values stated — `--detector-distance` and `--wavelength` override them (`--beam-x`/`--beam-y` the centre); serial stills that index poorly want the cell (`-C`). A run that ends - with `Killed` ran out of memory ([When host memory runs out](RUGNUX_INSTALL.md#when-host-memory-runs-out)). + with `Killed` ran out of memory ([When host memory runs out](RUGNUX_INSTALL.md#out-of-host-memory)). With any question about a run, send `myrun_report.txt` and `myrun_log.txt`. - Everything else is in [Running Rugnux](RUGNUX_TUTORIAL.md#running-rugnux) and the full [Command-line options](RUGNUX_CLI.md). -## The rest of the manual +## Manual pages -One page per job, so the answer needed is near the top of a short page: +The manual is split into one page per topic: -- [What Rugnux does](RUGNUX_OVERVIEW.md) — the pipeline from images to merged data and, with a model, a refined structure, +- [Overview](RUGNUX_OVERVIEW.md) — the pipeline from images to merged data and, with a model, a refined structure, in order. Read this one first. - [Download Rugnux](RUGNUX_DOWNLOAD.md) — the archive for Linux, macOS and Windows, and the three commands that run it. - [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 +- [Input formats](RUGNUX_FORMATS.md) — will it open your data: NXmx / EIGER masters, PILATUS miniCBF, marCCD and SMV (ADSC, Rigaku d\*TREK) sweeps, one sweep per input, and serial XFEL stills from SACLA (Cheetah HDF5), Cheetah CXI single-panel files and LCLS-I XTC. - [Running Rugnux](RUGNUX_TUTORIAL.md) — a first run in detail, rotation, serial and small-molecule @@ -285,7 +285,7 @@ One page per job, so the answer needed is near the top of a short page: benchmark, and how to take timings on another machine that compare with ours. - [CPU/GPU data analysis](CPU_DATA_ANALYSIS.md) — the algorithms behind all of it. -## Where it fits among the three analysis tools +## The three analysis tools | Tool | Mode | Driven by | Output | | --- | --- | --- | --- | diff --git a/docs/RUGNUX_ADVANCED.md b/docs/RUGNUX_ADVANCED.md index 07fa4d413..1787a7d4b 100644 --- a/docs/RUGNUX_ADVANCED.md +++ b/docs/RUGNUX_ADVANCED.md @@ -10,7 +10,7 @@ validation and re-merging without re-integration; the option tables are on [Comm ## Reference data and the indexing ambiguity -### What a reference does (`-z`) +### Reference data (`-z`) `-z reference.mtz` supplies **known intensities of the same crystal form** — a previously merged dataset, or `F-model` amplitudes computed from a structure. The reference can equally be a PDB diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 01969c72a..fef62bf79 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -128,7 +128,7 @@ merge's scaled observations in the batches of their own sweeps (sweep `s` of the sweep's own run wrote; the report names each sweep in section `1b. SWEEPS`. `--sweeps separate` processes each sweep alone instead, as if it were the only input, into `_s_*` (k = 1, 2, ... in the order given). -What each format needs is in [What Rugnux reads](RUGNUX_FORMATS.md); serial XFEL stills are read +What each format needs is in [Input formats](RUGNUX_FORMATS.md); serial XFEL stills are read without a geometry file where their own metadata places the detector ([Serial XFEL inputs](RUGNUX_FORMATS.md#serial-xfel-inputs)). diff --git a/docs/RUGNUX_FORMATS.md b/docs/RUGNUX_FORMATS.md index 113fddd50..5b6b0052d 100644 --- a/docs/RUGNUX_FORMATS.md +++ b/docs/RUGNUX_FORMATS.md @@ -1,4 +1,4 @@ -# What Rugnux reads +# Input formats Which data `rugnux` opens, before anything is typed. The short answer: an HDF5 master (NXmx or DECTRIS, from any facility), a PILATUS miniCBF sweep, a marCCD sweep, an SMV sweep (ADSC or Rigaku d\*TREK) or a diff --git a/docs/RUGNUX_INSTALL.md b/docs/RUGNUX_INSTALL.md index 219d61a87..33a971732 100644 --- a/docs/RUGNUX_INSTALL.md +++ b/docs/RUGNUX_INSTALL.md @@ -197,7 +197,7 @@ keeps in host RAM what a GPU build keeps on the card, so it is the one that need When such a set is too large for GPU scaling on the card, the run scales and merges it on the CPU instead, with a warning in the log — and then wants that much host memory for that step. -### When host memory runs out +### Out of host memory Nothing estimates the host memory a run will need before it starts, so a set that does not fit runs until the memory is gone, and then ends in one of two ways. diff --git a/docs/RUGNUX_INTEGRATION.md b/docs/RUGNUX_INTEGRATION.md index 757001760..d6cb1ccf8 100644 --- a/docs/RUGNUX_INTEGRATION.md +++ b/docs/RUGNUX_INTEGRATION.md @@ -426,7 +426,7 @@ END or inorganic elements needs the real `SFAC` first: with the placeholder, SHELXT cannot place a metal it has no scattering factor for, and on one inorganic set it ran for twenty minutes without finishing where the right `SFAC` solved it in a second. -- `TEMP` is the sample temperature the data file records, in °C (see [What Rugnux reads](RUGNUX_FORMATS.md)); +- `TEMP` is the sample temperature the data file records, in °C (see [Input formats](RUGNUX_FORMATS.md)); SHELXL takes its starting U values and the CIF's `_diffrn_ambient_temperature` from it. Where the file records none (CBF, the CCD formats) a `REM` line stands in its place, and SHELXL assumes 20 °C: add `TEMP` after `UNIT` by hand for a cooled crystal (`TEMP -173` for 100 K). diff --git a/docs/RUGNUX_MODEL_AND_REFERENCE.md b/docs/RUGNUX_MODEL_AND_REFERENCE.md index ec91d7a29..9741014f7 100644 --- a/docs/RUGNUX_MODEL_AND_REFERENCE.md +++ b/docs/RUGNUX_MODEL_AND_REFERENCE.md @@ -201,7 +201,7 @@ determined by the run, after the merge - nothing resolves it, and the run warns. that same resolution runs and the reference fixes the indexing the merge is written in: `AMBIGUITY_DATA_DISAGREES=` in the report counts the crystals the data and their cells put into another indexing than the reference alone would. -## Where a model can touch the space group +## The model and the space group Spelled out, because this is the question that matters most: diff --git a/docs/RUGNUX_OVERVIEW.md b/docs/RUGNUX_OVERVIEW.md index 168e67a3c..477c0322d 100644 --- a/docs/RUGNUX_OVERVIEW.md +++ b/docs/RUGNUX_OVERVIEW.md @@ -1,4 +1,4 @@ -# What Rugnux does +# Overview 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 @@ -7,7 +7,7 @@ rotation run with the defaults; stills differences are at the end. ![The rotation pipeline: pass 1 integrates half the sweep at the file's geometry, pass 2 the whole sweep at the refined one, and the better of the two goes on to the space group and the written merge; with a model, the placement and the refinement follow, deciding nothing](images/rugnux_pipeline.svg) **Open the dataset.** The geometry, wavelength and goniometer come from the file -([What Rugnux reads](RUGNUX_FORMATS.md)). A goniometer axis that turns makes it a rotation run; none, or one +([Input formats](RUGNUX_FORMATS.md)). A goniometer axis that turns makes it a rotation run; none, or one that stands still from frame to frame, makes it serial stills — nothing is asked of the user. **Pre-scan.** A projection of frames (60 by default) spread over the first part of the sweep, the part the geometry pre-pass integrates, finds the beam-stop shadow and masks diff --git a/docs/RUGNUX_REPORT.md b/docs/RUGNUX_REPORT.md index 0b6d299ac..0e9b07775 100644 --- a/docs/RUGNUX_REPORT.md +++ b/docs/RUGNUX_REPORT.md @@ -564,7 +564,7 @@ keeping it costs the merged intensities, and how precisely that is known. Every a `WARNING:` sentence in the SUMMARY, with the same cost in words. A range is split where its disposition changes, so each row is wholly kept or wholly rejected. -### What the disposition means, and what decides it +### The disposition column | Disposition | Meaning | |-------------|---------| diff --git a/docs/RUGNUX_TUTORIAL.md b/docs/RUGNUX_TUTORIAL.md index b93ab4fc5..3ac49479e 100644 --- a/docs/RUGNUX_TUTORIAL.md +++ b/docs/RUGNUX_TUTORIAL.md @@ -14,7 +14,7 @@ rugnux -o myrun /path/to/dataset_master.h5 ``` `-o myrun` is the prefix every output file is named from and the last argument is the **master** file -of the dataset — any of the formats under [What Rugnux reads](RUGNUX_FORMATS.md), not only one written +of the dataset — any of the formats under [Input formats](RUGNUX_FORMATS.md), not only one written by Jungfraujoch; `-N` would set the worker-thread count, which otherwise follows the machine. Nothing is assumed about the crystal — the goniometer axis in the file tells Rugnux this is a rotation sweep, the unit cell comes from @@ -69,9 +69,8 @@ rugnux -o myrun --no-export-unmerged dataset_master.h5 rugnux -o myrun --model model.pdb dataset_master.h5 ``` -Re-merging is cheap and does not re-read the images. Ask the full run to keep its per-image file -with `--write-process-h5`, and `--mode scale` will then re-scale and re-merge the reflections -already integrated in it — seconds rather than minutes: +Re-merging does not re-read the images and takes seconds. Run once with `--write-process-h5` +to keep the per-image file. `--mode scale` then re-scales and re-merges the reflections in it: ``` rugnux -o myrun --write-process-h5 dataset_master.h5 # integrate and merge once @@ -205,14 +204,14 @@ goniometer axis but you want per-frame stills processing anyway, add `--force-st ## Small-molecule data -A rotation sweep of a small-molecule crystal is processed with the same command as any other, and -needs no flag to say what it is: +A small-molecule rotation sweep is processed with the same command. No option marks it as +small-molecule data: ``` rugnux -o xtal sweep_master.h5 ``` -What differs from a protein is handled by the run itself: +The differences from protein data are handled automatically: - **Short cell axes.** The FFT search's floor is 10 Å, but on a rotation run a row shorter than that, down to 3 Å, is recognised under the multiple of it the search reports, so a cell with short axes is