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:
1 parent
ec36cb8d3d
commit
14cb819f76
11 files changed
+41
-42
No files matched your search
@@ -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
@@ -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 |
|
||||
| --- | --- | --- | --- |
|
||||
|
||||
@@ -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
@@ -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,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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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:
|
||||
|
||||
|
||||
@@ -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.
|
||||

|
||||
|
||||
**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
|
||||
|
||||
@@ -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 |
|
||||
|-------------|---------|
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user