diff --git a/docs/CPU_DATA_ANALYSIS_INDEXING.md b/docs/CPU_DATA_ANALYSIS_INDEXING.md index ca5cd6cf9..51ba35fc7 100644 --- a/docs/CPU_DATA_ANALYSIS_INDEXING.md +++ b/docs/CPU_DATA_ANALYSIS_INDEXING.md @@ -412,7 +412,7 @@ The extraction window around a ring is capped at half the gap to its neighbour, ### 7.7 Stills: a given cell and the detector modules -**A given cell is a prior, and a hypothesis.** On stills a cell and a distance are degenerate near the +**A given cell is a prior.** On stills a cell and a distance are degenerate near the beam - a spot's radius fixes only their ratio - and are told apart only by the curvature of $r=D\tan2\theta$ against $\sin\theta$ at high angle. The stills geometry refinement therefore refines the beam centre, the distance and the cell together over the strong frames: the cell lengths and the @@ -426,17 +426,14 @@ from (scale, each length, each angle) and how far the distance moved. A distance `--detector-distance` is held, and the cell alone takes up its error. Frames are matched to the given cell in any setting of the same lattice, and are described on its axes. -With `-C` the cell given is also tested as a hypothesis against the cell the frames index to de novo. -The frames are first fitted de novo from the file's geometry, as without `-C`, and the cell given is then fitted -from the detector distance, centre and module placement that fit found: from a start several percent off, a fit -can settle as far off as it started, and the de novo fit, whose cell takes up the start's error, is the nearer -start for any cell of the sample. Each, with its refined cell and geometry, then indexes the same sample of -frames. The cell given is kept where -it puts at least 0.9 times as many of the sample's spots on the lattice as the de novo cell does. A cell given -that does not describe the frames - the same lattice in a shape they do not have, which the fit cannot leave -because the frames were indexed on it - fails this, and the run is then processed as without `-C`, with a warning. So does a minority crystal form -given with `-C` where the frames' de novo cell describes the majority well enough to index materially more of -the sample's spots. +With `-C` the run always uses the cell given; the frames' own evidence is reported, never acted on. Two +warnings say where it disagrees with them, each with both numbers. Where the geometry refinement moves the cell's +shape (a length beyond the common scale, which trades with the distance) more than 3 % or an angle more than 3° +from what was given. And where, at the centre and distance the stills geometry trial decides (§1.4), the trial's +96-frame sample indexed de novo puts more than 1/0.9 times as many spots on the lattice as the cell given: the cell +given may then be another crystal form than most of the frames, or a shape they do not have - the same lattice in a +shape it does not have still indexes the frames, at a distance of its own, and merges far worse than the run +without `-C`. **One crystal form.** A sample can hold two crystal forms, and a known-cell indexer fits both to the given cell's orientation search; their refined cells then fall into two volume populations, and diff --git a/docs/RUGNUX_CLI.md b/docs/RUGNUX_CLI.md index 040f230a3..8b9f33fc6 100644 --- a/docs/RUGNUX_CLI.md +++ b/docs/RUGNUX_CLI.md @@ -264,7 +264,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 | | `-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; `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; rotation data always use the FFT search | | `-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 geometry refinement takes it as a prior (1 % on the lengths, 1° on the angles the crystal system leaves free) and tests it against the cell the frames index to de novo: a cell that, refined from the geometry the de novo fit found, puts fewer than 0.9 times as many sampled spots on the lattice as the de novo cell is dropped with a warning, and the run is processed as without `-C` ([§7.7](CPU_DATA_ANALYSIS_INDEXING.md#77-stills-a-given-cell-and-the-detector-modules)) | +| `-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)) | | `--fft-min-unit-cell ` | Shortest cell axis the FFT search accepts, Å (default: 10). 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)) | diff --git a/docs/RUGNUX_MODEL_AND_REFERENCE.md b/docs/RUGNUX_MODEL_AND_REFERENCE.md index 4e3cb3766..d1acede9d 100644 --- a/docs/RUGNUX_MODEL_AND_REFERENCE.md +++ b/docs/RUGNUX_MODEL_AND_REFERENCE.md @@ -58,7 +58,7 @@ the rest walks through a run step by step. | `--reference-column