From 8bceabbde2450980fc898ef36fca9fb29cab3b71 Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Mon, 16 Nov 2026 07:48:55 +0100 Subject: [PATCH] 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 Claude-Session: https://claude.ai/code/session_01UqXYdJDrM65gxsCn2PrbfK --- docs/RUGNUX_ADVANCED.md | 4 ++-- docs/RUGNUX_CLI.md | 5 +++-- rugnux/rugnux_cli.cpp | 4 +++- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/RUGNUX_ADVANCED.md b/docs/RUGNUX_ADVANCED.md index 586f316f0..53ec4405c 100644 --- a/docs/RUGNUX_ADVANCED.md +++ b/docs/RUGNUX_ADVANCED.md @@ -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 diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 6a5237e7a..ee0e18498 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -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 ` | `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 ` | 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 ` | 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 ` | 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 ` | 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 ` | 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 | diff --git a/rugnux/rugnux_cli.cpp b/rugnux/rugnux_cli.cpp index 701de869d..f78afddc3 100644 --- a/rugnux/rugnux_cli.cpp +++ b/rugnux/rugnux_cli.cpp @@ -184,7 +184,9 @@ Re-merging (--mode scale) Basic options -o, --output-prefix Prefix of every output file (default: output) - -C, --unit-cell Known unit cell a,b,c,alpha,beta,gamma (A, deg); helps stills + -C, --unit-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 Known space group, number or symbol: 96 or P43212 -A, --anomalous Merge Friedel pairs apart (anomalous statistics) --scaling-high-resolution High-resolution limit (default: from the CC1/2 fall-off)