From 8505f9c85e31e37085f9f3fe3cbafae1ccac8e8c Mon Sep 17 00:00:00 2001 From: Filip Leonarski Date: Sun, 8 Nov 2026 11:27:57 +0100 Subject: [PATCH] docs: several sweeps in README and RUGNUX_FORMATS, marked experimental README gets a line and a short paragraph in "Running rugnux": several rotation sweeps of one crystal can be given at once (masters, or one frame of each frame-file sweep), merged as one dataset by default, --sweeps separate for each alone; marked experimental and not fully tested, pointing at RUGNUX_CLI's Inputs. RUGNUX_FORMATS said rugnux does not combine sweeps in a run, which contradicts the usage and RUGNUX_CLI. Its input paragraph now states the multi-sweep input per format with the same experimental mark, keeps the downstream-merge pointer for sweeps processed separately, and names the Bruker SFRM reader the page omitted (a bullet beside the other one-frame-per-file formats, and the as-is note widened to it). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01HVeDQsU5a8AJUdJPgWevAK --- README.md | 6 ++++++ docs/RUGNUX_FORMATS.md | 24 ++++++++++++++++++------ docs/RUGNUX_INTEGRATION.md | 4 ++-- 3 files changed, 26 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 3360fe480..7a2369e71 100644 --- a/README.md +++ b/README.md @@ -46,8 +46,14 @@ output files (default `output`). rugnux -o myrun dataset_master.h5 # HDF5 master; for a CBF/marCCD/SMV sweep name one frame rugnux -o myrun -C "a,b,c,alpha,beta,gamma" -S P212121 dataset_master.h5 # with a known cell and space group rugnux -o myrun dataset_master.h5 model.cif # with a model (or --model model.cif) +rugnux -o myrun a_master.h5 b_master.h5 # several sweeps of one crystal, merged as one (experimental) ``` +Several rotation sweeps of one crystal can be given at once - several masters, or one frame of each +CBF/marCCD/SMV sweep - and are merged as one dataset by default (`--sweeps separate` processes each on +its own). **Multi-sweep processing is experimental and not fully tested**; what it does is described +under [Inputs](docs/RUGNUX_CLI.md#inputs). + **Serial stills** (synchrotron or XFEL) ``` diff --git a/docs/RUGNUX_FORMATS.md b/docs/RUGNUX_FORMATS.md index b8eb34cbf..113fddd50 100644 --- a/docs/RUGNUX_FORMATS.md +++ b/docs/RUGNUX_FORMATS.md @@ -1,15 +1,21 @@ # What Rugnux reads 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 or an SMV sweep (ADSC or Rigaku d\*TREK), and +DECTRIS, from any facility), a PILATUS miniCBF sweep, a marCCD sweep, an SMV sweep (ADSC or Rigaku d\*TREK) or a +Bruker SFRM sweep, and for serial stills the files of the XFEL pipelines ([below](#serial-xfel-inputs)) — nothing else is read, so any other format has to be converted to one of these first. An atomic model and a reference reflection file may be given among the inputs too, told from the images by their contents. -**Input** is files, never a directory: an HDF5 master file, or one frame of a PILATUS miniCBF, marCCD -or SMV sweep. For rotation data one input is **one sweep of one crystal** — Rugnux does not combine sweeps or crystals in a run; process each -sweep to its own `_unmerged.mtz` and merge them downstream -(see [Taking the data onward](RUGNUX_INTEGRATION.md#taking-the-data-onward)). +**Input** is files, never a directory: an HDF5 master file, or one frame of a PILATUS miniCBF, marCCD, +SMV or SFRM sweep. For rotation data one input is **one sweep of one crystal**. Several sweeps of one +crystal may be given at once — several rotation masters, or one frame of each frame-file sweep, all of +one format and at one wavelength — and are then merged as one dataset by default: each sweep is processed +on its own first and the sweeps are scaled and merged together, into `.*`; `--sweeps separate` +processes each alone instead, into `_s_*`. **Multi-sweep processing is experimental and not +fully tested**; how the sweeps are told apart and joined is described under +[Inputs](RUGNUX_CLI.md#inputs). Sweeps processed separately are merged downstream from their own +`_unmerged.mtz` files (see [Taking the data onward](RUGNUX_INTEGRATION.md#taking-the-data-onward)). Stills are given as all the files of the dataset, which the shell expands from a glob and which are read in the order given: `rugnux run1_master.h5 run2_master.h5` (or `rugnux *_master.h5`) for @@ -67,8 +73,14 @@ directory is refused. circles, including a swung **2θ arm**, from the detector goniometer, the spindle and its angles from the rotation record, and the wavelength from the scan record. Pixel values above 32767 are the format's encoded overflows and are expanded with the header's compression ratio. +* **Bruker SFRM sweep** — what SMART, PROTEUM and APEX write (`.sfrm`, header formats 86 and 100): one + frame per file, read natively, the sweep selected as above; a Bruker collection directory holds one + run per scan, and each run is its own sweep. The scan axis and the other circles (2θ, ω, φ, χ), the + distance, beam centre, pixel size, wavelength and saturation come from the header; the overflow and + underflow tables are expanded and the baseline offset subtracted. Like the other raw frames it + carries no analysis results and `--mode scale` does not accept one. -Support for the two CCD formats — marCCD and SMV — is **very limited and provided as-is**; they +Support for the CCD formats — marCCD, SMV and Bruker SFRM — is **very limited and provided as-is**; they are read so that a CCD sweep does not need a conversion step to be processed. Only the header fields named above are read, and the headers vary by site and vintage, so no promise is made that every writer's dialect opens. The HDF5 and miniCBF paths are the maintained ones. diff --git a/docs/RUGNUX_INTEGRATION.md b/docs/RUGNUX_INTEGRATION.md index 963450005..bdc1a579b 100644 --- a/docs/RUGNUX_INTEGRATION.md +++ b/docs/RUGNUX_INTEGRATION.md @@ -114,7 +114,7 @@ regression battery, or a throughput pipeline — turns it off with `--no-export- Use it to scale the data with a different program, to have pointless give an independent opinion on the space group, or to compare Rugnux's merge against another one on identical input. Each sweep's file is self-contained, so several of them can be handed to pointless and aimless as separate -`HKLIN`s to merge sweeps Rugnux does not combine itself. +`HKLIN`s to merge sweeps Rugnux processed separately (`--sweeps separate`). > **Trap when combining a wild-carded series.** For an `HKLIN` given with wild-cards, POINTLESS > accepts the files in order and **terminates acceptance at the first file out of chronological @@ -272,7 +272,7 @@ aimless HKLIN sorted.mtz HKLOUT scaled.mtz ``` Several sweeps of one crystal form go in as separate `HKLIN`s to the same pointless run — that is -how sweeps Rugnux does not combine itself are merged. +how sweeps Rugnux processed separately (`--sweeps separate`) are merged. **careless** wants unmerged, unscaled intensities carrying only the deterministic per-reflection corrections, with the partiality reported and not divided out - on a rotation merge that is