rugnux docs/usage: -C semantics in the usage, -z with several stills files and in --mode refine

- usage: -C without -S fixes the crystal system from the angles as typed, on the typed axes;
  RUGNUX_CLI.md says the axes as typed too.
- RUGNUX_ADVANCED.md: a reference -z lifts the group check of several _process.h5 files as
  well as the cell check (it fixes the space group too, rugnux_cli.cpp).
- RUGNUX_CLI.md: --mode refine refines against the input reflections; -z is not used there and
  a reflection file given only with -z does not select the mode.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK
This commit is contained in:
leonarski_fandClaude Opus 5.5 committed 2026-11-16 07:48:55 +01:00
1 parent b9a1cde246
commit 8bceabbde2
3 files changed
+8 -5

No files matched your search

+2 -2
View File
@@ -329,8 +329,8 @@ rocking curve merged with are the first file's; the ice-ring gate pools the fram
The files must be of one crystal: each file's cell the first's lattice (in its setting or another) and
the same space group. A run stops with a message naming both cells, or both groups, where they are not -
unless the cell is given (`-C`, or a reference `-z`) and, for the group, `-S`: then everything is merged
in what is given, and the crystals of a file not on that cell are left out. A mix of stills and rotation
unless the cell is given (`-C`, or a reference `-z`) and, for the group, `-S` (or the group of a reference
`-z` that states one): then everything is merged in what is given, and the crystals of a file not on that cell are left out. A mix of stills and rotation
files is refused, and so are several rotation files (`--mode scale` merges one sweep at a time; several
sweeps of one crystal are merged together from their masters by `--mode mx`). Under `--force-still` a
rotation file counts as stills. `-s`/`-e` select images of one file and are refused with several. The
+3 -2
View File
@@ -61,7 +61,8 @@ Refines a model against merged data that already exist - an MTZ or a structure-f
reads no images. The model is required, given among the inputs or with `--model`. Without `--mode`,
rugnux takes `--mode refine` when the inputs hold reflections and no images and a model is given -
among the inputs or with `--model` (`rugnux -o refined data.mtz model.cif`,
`rugnux -o refined --model model.cif data.mtz`). A restraint dictionary for a ligand can be given among the
`rugnux -o refined --model model.cif data.mtz`); the reflections are an input then, not `-z`, which `--mode refine`
does not use (a reflection file given only with `-z` does not select it). A restraint dictionary for a ligand can be given among the
inputs as well (`--restraints`)
([Refining a model against structure factors](RUGNUX_MODEL_AND_REFERENCE.md#refining-a-model-against-structure-factors-rugnux---mode-refine)).
@@ -282,7 +283,7 @@ For very long axes the direction grid's angular resolution binds well below 500
| `--force-still` | Treat a rotation (goniometer) dataset as independent stills instead of rotation; several masters are then read as one stills run |
| `-X, --indexing-algorithm <txt>` | `Auto` (default) \| `FFT` \| `cuFFT` \| `FFTW` \| `FFBIDX` \| `None`, case-insensitive. `FFT` is the de-novo FFT search, on the GPU (cuFFT) where there is one and `--no-gpu` is not given, otherwise on the CPU (FFTW); `cuFFT` and `FFTW` name one implementation each (`FFTW` keeps its old name: the CPU transforms are pocketfft's); `cuFFT` needs a GPU and is refused without one. `FFBIDX` (known cell, `-C`) runs on the GPU where there is one and otherwise on the CPU. `Auto` takes `FFBIDX` on stills with a known cell, and `FFT` otherwise. `FFBIDX` without a cell (`-C`, or one from `-z`) resolves to `None` and indexes nothing, with no error. On rotation data `-X` is not consulted: the FFT search runs on the GPU where there is one and on the CPU otherwise, so `Auto`, `FFT`, `cuFFT` (with a GPU) and `FFTW` (without one, or under `--no-gpu`) are accepted and any other value stops the run at indexing; `FFBIDX` and `None` are for stills |
| `-F` | Short for `-X FFT`, kept for old command lines |
| `-C, --unit-cell <cell>` | Reference unit cell `"a,b,c,alpha,beta,gamma"` (required by `ffbidx`). On rotation data it also widens the FFT search to cover the cell given, at both ends: the longest axis looked for is raised to reach it, and `--fft-min-unit-cell` is lowered to admit it. A candidate that is an integer supercell of the cell given (a twin's coincidence lattice, a row taken at a multiple of its length) is stepped down to it. On stills the run always uses it: the geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free), and the log warns - with both numbers - where the frames refine its shape more than 3 % / 3° away, or where a sample of frames indexed de novo puts materially more spots on the lattice than the cell given ([§7.7](CPU_DATA_ANALYSIS_INDEXING.md#77-stills-a-given-cell-and-the-detector-modules)). Without `-S` the cell fixes the crystal system, read from the angles as typed: an angle is 90° or 120° only where it is typed so (`90` or `90.00`, not `90.03`). Three 90s: orthorhombic, or tetragonal / cubic where the lengths are equal within tolerance; two 90s and a 120: hexagonal (or rhombohedral in hexagonal axes); two 90s: monoclinic; three equal angles: rhombohedral; anything else: triclinic, and the run behaves as with `-S P1`. The lattice is indexed in that system, never above or below it, and only the space group within it is searched |
| `-C, --unit-cell <cell>` | Reference unit cell `"a,b,c,alpha,beta,gamma"` (required by `ffbidx`). On rotation data it also widens the FFT search to cover the cell given, at both ends: the longest axis looked for is raised to reach it, and `--fft-min-unit-cell` is lowered to admit it. A candidate that is an integer supercell of the cell given (a twin's coincidence lattice, a row taken at a multiple of its length) is stepped down to it. On stills the run always uses it: the geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free), and the log warns - with both numbers - where the frames refine its shape more than 3 % / 3° away, or where a sample of frames indexed de novo puts materially more spots on the lattice than the cell given ([§7.7](CPU_DATA_ANALYSIS_INDEXING.md#77-stills-a-given-cell-and-the-detector-modules)). Without `-S` the cell fixes the crystal system, read from the angles as typed: an angle is 90° or 120° only where it is typed so (`90` or `90.00`, not `90.03`). Three 90s: orthorhombic, or tetragonal / cubic where the lengths are equal within tolerance; two 90s and a 120: hexagonal (or rhombohedral in hexagonal axes); two 90s: monoclinic; three equal angles: rhombohedral; anything else: triclinic, and the run behaves as with `-S P1`. The lattice is indexed in that system, never above or below it, on the axes of the cell as typed (an F- or R-centred one in its conventional setting), and only the space group within it is searched |
| `--fft-min-unit-cell <num>` | Shortest cell axis the FFT search accepts, Å (default: 10; accepted 5-40). A candidate with a shorter axis is discarded — but on rotation data a row shorter than the floor, down to 3 Å, is recognised under the multiple of it the search reports past the floor, so a small-molecule cell is indexed without this flag. `-C` lowers the floor on its own to cover the cell given. On stills a crystal below the floor cannot be indexed unless this is lowered |
| `--min-indexed-spots <num>` | Spots a frame must have on the lattice before it counts as indexed (default: 6, minimum 4). It sets the reported indexing rate and the count the rotation first pass ranks candidate lattices by; whether the run has a lattice at all is decided on the pooled spots instead ([§4.1](CPU_DATA_ANALYSIS_INDEXING.md#41-indexed-spot-decision-inlier-test)), and integration is not gated by it |
| `-S, --space-group <num\|symbol>` | Space group number (`96`) or Hermann-Mauguin symbol (`P43212`) — for indexing and scaling. On serial stills whose group admits two indexings, it also lets the crystals be put on one from the data ([the indexing ambiguity](RUGNUX_ADVANCED.md#the-indexing-ambiguity)). A fixed group fixes the lattice: indexing puts the crystal in the group's own Bravais class and nothing promotes, demotes, reduces or doubles it afterwards. A primitive group on a lattice with no primitive cell of its system (P2 on a C-centred monoclinic crystal, P3 on a rhombohedral one) is merged on the centred cell, and the positions the centring extinguishes are kept (they read about zero). With `-C` as well, the cell is written on the given cell's axes |
+3 -1
View File
@@ -184,7 +184,9 @@ Re-merging (--mode scale)
Basic options
-o, --output-prefix <txt> Prefix of every output file (default: output)
-C, --unit-cell <cell> Known unit cell a,b,c,alpha,beta,gamma (A, deg); helps stills
-C, --unit-cell <cell> Known unit cell a,b,c,alpha,beta,gamma (A, deg); helps stills.
Without -S its angles, read as typed (90 means exactly 90), fix
the crystal system, kept on the axes as typed
-S, --space-group <sg> Known space group, number or symbol: 96 or P43212
-A, --anomalous Merge Friedel pairs apart (anomalous statistics)
--scaling-high-resolution <A> High-resolution limit (default: from the CC1/2 fall-off)