v1.0.0-rc.164 (#74)

* rugnux now tells you whether a crystal diffracts anisotropically and how far it reaches in each direction, without a second program: a new `9. DIFFRACTION ANISOTROPY` section in `<prefix>_report.txt` and matching `_reflns.pdbx_aniso_B_tensor_*` / `_reflns.jfjoch_aniso_*` items in the merged mmCIF report the anisotropic deltaB, the diffraction limit along each principal direction, and a `NOT DETECTED` / `DETECTED` / `CANNOT DETERMINE` verdict measured against the data set's own systematic error. It is a description only - no intensity is corrected, no reflection is removed, and the merged data do not depend on direction.
* rugnux can hand its integrated observations to another scaling program: `--export-unmerged` writes `<prefix>_unmerged.mtz`, an unmerged MTZ readable by aimless, pointless, careless and `iotbx.merging_statistics`, in `--mode mx` and `--mode scale` alike. Each rotation reflection's partials are summed into one full; `--export-unmerged-partials` writes one row per image instead. Intensities carry the Lorentz-polarization factor and nothing else, since those programs scale the data themselves. Lattice-centring absences are not written; screw and glide absences are.
* rugnux integrates crystals with broad spots better - where it changes anything, per-shell mean I/sigma improves by up to 31% and R_meas by up to 24% - because on rotation data the integration signal radius is now taken from the crystal's own measured spot width instead of a fixed 4 px. `--adaptive-integration-radius=off` restores the fixed radius and an explicit `--integration-radius` still overrides both. The widened radius applies to the final integration pass only, and a pattern too dense for it is re-integrated at 4 px with a note in the log.
* rugnux discards fewer stills reflections for want of a background ring, improving per-shell R_meas over most of the signal-bearing range: the stills background ring now runs to 14 px instead of 12. The gain reverses in shells below a mean I/sigma of about 4.
* rugnux determines the space group with thresholds that mean the same thing on a weak crystal as on a strong one: symmetry operators are scored on resolution-normalised intensities (E squared) instead of raw merged intensities, and a reflection counts as genuinely present on its counting significance instead of on the merged I/sigma, which saturates at the merge's own ISa. The search resolution cut is no longer able to move the answer, and the twin-law H bound moves from 1.70 to 1.85, which stops one class of correct high-symmetry assignment being refused as twinning.
* rugnux says what the space-group search tested and what it could not: the twin-law disagreement H is printed for every operator together with the adopted point group's H ratio and its bound; alternatives that are not on the reported lattice are named with how their cell differs; and a lattice centring the data could not test - the crystal having been integrated on the primitive sub-cell, so the reflections it extinguishes were never measured - is marked `UNTESTED` and warned about where it is adopted, as coming from the lattice metric rather than from the intensities.
* rugnux `--mode scale` re-merges a `_process.h5` in the right symmetry without being told it: the file now records the space group on every run - a two-pass rotation run wrote none before, so re-merging defaulted to P1 - together with the change of basis under `/entry/MX/reindexMatrix` where the lattice was re-seated, and `--mode scale` also reports the Wilson B-factor estimate instead of `WILSON_B= nan`. A file written before this stops with a message naming the two cells and the override to use, instead of failing inside the merge. A third-party reader of a `_process.h5` must apply `reindexMatrix` where it is present.
* rugnux installs on its own, as a package called `rugnux` - `dnf install rugnux` or `apt install rugnux` - instead of arriving inside `jfjoch-viewer`. It pulls in none of the acquisition stack, so a machine that only processes data no longer has to carry the broker, the detector libraries or Qt to get it. Installing it over a `jfjoch-viewer` from rc.163 or earlier, which still owns `/usr/bin/rugnux`, upgrades cleanly rather than failing on the duplicate file.
* rugnux is also a standalone download, built for arm64 as well as x86_64: `rugnux-<version>-linux-{x86_64|aarch64}-cuda<major>.tgz` and `rugnux-<version>-win64-cuda<major>.zip` on the release page, for machines that are not managed by a package manager. The aarch64 build targets GH200 and DGX Spark, and is untested on hardware.
* Every portable Linux binary is now a single self-contained file: cuFFT is linked statically instead of being shipped beside the executable and found through an rpath, so `rugnux` and `jfjoch_viewer` need nothing but an NVIDIA driver, and only to use the GPU. The `.rpm`/`.deb` continue to take cuFFT from the distribution. The developer utilities `jfjoch_extract_hkl` and `jfjoch_recompress` are no longer packaged anywhere.
* Jungfraujoch needs six fewer shared libraries on the machine - libopenblas and libmetis, and libgfortran, libquadmath, libgomp and libz behind them - because the Ceres LAPACK, METIS and SuiteSparse back-ends are no longer built. Nothing in the code ever selected them, and results are unchanged.
* The PCIe driver DKMS package builds for the kernel it is being installed for instead of the running one, so a module built while a kernel update is being applied loads after the reboot.
* The PCIe driver builds on RHEL 9.5 and later, and on their CentOS Stream, Rocky and AlmaLinux equivalents, where the `vm_flags` kernel interface was backported into the 5.14 kernel.
* A data collection started with `async_start` that fails to start - a writer refusing to overwrite an existing file, for instance - is reported as an error by `/wait_until_running` and `/wait_till_done` instead of as a timeout and a successful collection respectively. The error message is the one the writer gave.
* A calibration that is cancelled or that fails to collect its pedestals is no longer reported as a successful one. The broker goes to `Inactive` with an error message and has to be initialized again, instead of sitting in `Idle` looking ready to measure while holding partial pedestals - data collected in that state was silently mis-converted.
* A failed `/initialize` is reported to `/wait_until_running` and `/wait_till_done` as soon as it happens, instead of when their timeout expires.
* `space_group_number` accepts space groups up to 230 in the API schema, so cubic space groups can be recorded. The broker always accepted them; the generated clients rejected them before the request was sent.
* The results report's `REPORT_VERSION` is 3, two sections having been added. Existing key names and table columns are unchanged.
* The merged statistics table has **9** resolution shells instead of 10, which is what XDS reports. The bins were already XDS's - equal steps in 1/d^2 between the lowest- and the highest-resolution reflection the merge kept - so at the same resolution limits the two tables now have the same shell boundaries and can be read row for row. `--resolution-shells` sets a different count.
* `rugnux --model` now settles the frame the merged reflections are written in, not only the frame the R-factors and the maps are computed in: the `.mtz`/`.cif`/`.hkl` come out in the model's indexing, and where the data were merged in the model's enantiomorph they take the model's hand and space group - which on anomalous data puts I(+) and I(-) the right way round. The indexing choice is logged with the winning R-free and the runner-up, so a decision made within noise is visible.
* `rugnux --model` can resolve the indexing ambiguity of a **serial stills** run, which a model could not do before: structure factors computed from the model become the per-image reference, the same role a reference MTZ plays. It needs the cell and space group up front (`-C` / `-S`). Without one or the other, a merohedral serial run still merges both hands together and says so.
* The rugnux documentation opens with a quick start - the default run, and runs with a reference MTZ, with a model, or with the space group and cell pinned - and explains the indexing ambiguity: what it costs on rotation and on serial data, and which of `-z` / `--model` resolves it in each case. The long reference pages now carry a table of contents.

Reviewed-on: #74
Co-authored-by: Filip Leonarski <filip.leonarski@psi.ch>

tests/JFJochReaderTest.cpp

@@ -2479,6 +2479,117 @@ TEST_CASE("JFJochReader_ReadReflections_VDS", "[HDF5][Full]") {
     REQUIRE(H5Fget_obj_count(H5F_OBJ_ALL, H5F_OBJ_ALL) == 0);
 }
 
+// The per-image reflections and lattices are written in the setting the images were indexed in, but
+// the space group - and with it the conventional setting the cell beside them is in - is only settled
+// after the merge, so the two can differ by an integral change of basis. /entry/MX/reindexMatrix
+// carries it, and the reader applies it, so what comes out is in the cell's setting. A file without
+// the dataset (every file written before it existed) is read as the identity, which is what the
+// round-trip tests above check.
+TEST_CASE("JFJochReader_ReadReflections_Reindex", "[HDF5][Full]") {
+    DiffractionExperiment x(DetJF(1));
+
+    x.FilePrefix("read_reflections_reindex")
+     .ImagesPerTrigger(2)
+     .ImagesPerFile(1)
+     .OverwriteExistingFiles(true)
+     .BitDepthImage(16)
+     .PixelSigned(true)
+     .SetFileWriterFormat(FileWriterFormat::NXmxVDS)
+     .IndexingAlgorithm(IndexingAlgorithmEnum::FFT)
+     .Compression(CompressionAlgorithm::NO_COMPRESSION);
+
+    // hkl_cell = M . hkl_written, det 2 - the size of step a primitive-to-centred re-seat takes.
+    const std::array<int32_t, 9> M = {1, 1, 0,
+                                      0, 1, 1,
+                                      1, 0, 1};
+
+    std::vector<int16_t> image(x.GetPixelsNum(), 0);
+
+    RegisterHDF5Filter();
+
+    {
+        StartMessage start_message;
+        x.FillMessage(start_message);
+
+        FileWriter writer(start_message);
+        ScanResultGenerator scan_result(x);
+
+        for (int i = 0; i < x.GetImageNum(); i++) {
+            DataMessage message{};
+            message.image = CompressedImage(image, x.GetXPixelsNum(), x.GetYPixelsNum());
+            message.number = i;
+
+            if (i == 1) {
+                message.integrated_reflections = 2;
+                message.reflections = {MakeTestReflection(i, 0), MakeTestReflection(i, 1)};
+                message.indexing_result = true;
+                message.indexing_lattice = CrystalLattice({100,0,0}, {0,50,0}, {0,0,30});
+            }
+
+            REQUIRE_NOTHROW(writer.WriteHDF5(message));
+            scan_result.Add(message);
+        }
+
+        EndMessage end_message;
+        end_message.max_image_number = x.GetImageNum();
+        end_message.reindex_matrix = M;
+        scan_result.FillEndMessage(end_message);
+
+        writer.WriteHDF5(end_message);
+        writer.Finalize();
+    }
+
+    // hkl and the lattice come back in the cell's setting; every other field is untouched.
+    const auto check = [&](const Reflection &got, int j) {
+        const Reflection want = MakeTestReflection(1, j);
+        INFO("reflection " << j);
+        CHECK(got.h == M[0] * want.h + M[1] * want.k + M[2] * want.l);
+        CHECK(got.k == M[3] * want.h + M[4] * want.k + M[5] * want.l);
+        CHECK(got.l == M[6] * want.h + M[7] * want.k + M[8] * want.l);
+        CHECK(got.I == Catch::Approx(want.I));
+        CHECK(got.d == Catch::Approx(want.d));
+        CHECK(got.image_number == Catch::Approx(want.image_number));
+    };
+
+    {
+        JFJochHDF5Reader reader;
+        REQUIRE_NOTHROW(reader.ReadFile("read_reflections_reindex_master.h5"));
+
+        REQUIRE(reader.GetDataset()->reindex_matrix.has_value());
+        CHECK(reader.GetDataset()->reindex_matrix.value() == M);
+
+        auto reflections = reader.ReadReflections();
+        REQUIRE(reflections.size() == 2);
+        REQUIRE(reflections[1].reflections.size() == 2);
+        check(reflections[1].reflections[0], 0);
+        check(reflections[1].reflections[1], 1);
+
+        // latt = M . latt_written, row by row: (100,0,0)+(0,50,0), (0,50,0)+(0,0,30), (100,0,0)+(0,0,30).
+        CHECK(reflections[1].latt.Vec0().x == Catch::Approx(100.0f));
+        CHECK(reflections[1].latt.Vec0().y == Catch::Approx(50.0f));
+        CHECK(reflections[1].latt.Vec1().y == Catch::Approx(50.0f));
+        CHECK(reflections[1].latt.Vec1().z == Catch::Approx(30.0f));
+        CHECK(reflections[1].latt.Vec2().x == Catch::Approx(100.0f));
+        CHECK(reflections[1].latt.Vec2().z == Catch::Approx(30.0f));
+        CHECK(reflections[1].latt.CalcVolume() == Catch::Approx(2.0 * 100 * 50 * 30));
+
+        // The per-image message path (the viewer's) is re-seated the same way.
+        auto reader_image = reader.LoadImage(1);
+        REQUIRE(reader_image);
+        REQUIRE(reader_image->ImageData().reflections.size() == 2);
+        check(reader_image->ImageData().reflections[0], 0);
+        REQUIRE(reader_image->ImageData().indexing_lattice);
+        CHECK(reader_image->ImageData().indexing_lattice->CalcVolume()
+              == Catch::Approx(2.0 * 100 * 50 * 30));
+    }
+
+    remove("read_reflections_reindex_master.h5");
+    remove("read_reflections_reindex_data_000001.h5");
+    remove("read_reflections_reindex_data_000002.h5");
+
+    REQUIRE(H5Fget_obj_count(H5F_OBJ_ALL, H5F_OBJ_ALL) == 0);
+}
+
 static std::vector<SpotToSave> MakeTestSpots(int i) {
     return {
         SpotToSave{