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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK
This commit is contained in:
leonarski_fandClaude Fable committed 2026-11-10 16:55:48 +01:00
1 parent ec36cb8d3d
commit 14cb819f76
11 files changed
+41 -42

No files matched your search

+1 -1
View File
@@ -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
+25 -25
View File
@@ -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 <d>`**, 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 |
| --- | --- | --- | --- |
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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 `<prefix>_s<k>_*` (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)).
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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.
+1 -1
View File
@@ -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).
+1 -1
View File
@@ -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:
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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 |
|-------------|---------|
+6 -7
View File
@@ -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