image_preprocessing: decode bitshuffle+LZ4 on the GPU

The pipeline decompressed each image on the host and uploaded the result. On
an 18 Mpx rotation dataset that made the host-to-device copy the bottleneck of
the whole per-image loop: nsys puts the copies at 78% of the loop against 39%
for every kernel combined - 3600 transfers of 72.4 MB - and they ran at only
12.5 GB/s of an available 27-28 because the host-side decompression was itself
saturating host memory bandwidth. The GPU was mostly waiting.

So the compressed chunk goes across instead, about 4 MB rather than 72 MB, and
is decoded on the device. That removes the transfer and the host decompression
that was throttling it, in one change. Measured on an idle machine, a run goes
from 45.11 s to 24.97 s - 1.81x - with the merged output unchanged.

THE APPROACH IS JON WRIGHT'S (ESRF): "Experiences with GPU decompression for
bitshuffle + LZ4 data", HDF5 User Group 2021, and github.com/jonwright/
bslz4decoders. The kernels here are ours, but the idea and the demonstration
that it is worth doing are his. Cited in docs/ACKNOWLEDGEMENT.md and in the new
section 0 of docs/CPU_DATA_ANALYSIS.md.

Two kernels mirror the CPU decoder. LZ4 runs one WARP per bitshuffle block:
every lane parses the same sequence stream (a broadcast read, no divergence)
and the literal and match copies are split across the 32 lanes so the stores
coalesce; an overlapping match is treated as a pattern of period offset sourced
from bytes that already precede the write position, which keeps it parallel
rather than a serial byte loop. One thread per block instead measured 13x
slower. The bitshuffle inverse then un-transposes each byte-plane through
shared memory and interleaves the planes back into elements.

Only BSHUF_LZ4 is decoded on the device. The zstd variants have no device
decoder, and neither has an uncompressed or float image; Supports() returns
false for those and the caller decompresses on the host exactly as before. The
fallback is explicit, so a format we cannot decode on the device is a slower
path and never a wrong answer.

Tests hold the device decoder against the CPU one byte for byte, on data from
the production compressor, for every element size the detectors emit -
including the 8-bit DECTRIS modes, which take bitshuf_decode_block's separate
elem_size == 1 branch - plus a many-block frame, the formats it must decline,
and malformed containers, which must throw rather than run off a buffer.

Battery: 37 crystals, no failures, identical to the host-decode run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

image_analysis/MXAnalysisWithoutFPGA.cpp

@@ -90,16 +90,30 @@ void MXAnalysisWithoutFPGA::Analyze(DataMessage &output,
         throw JFJochException(JFJochExceptionCategory::InputParameterInvalid,
                               "Mismatch in pixel size");
 
+    // Decompress on the device where the preprocessor can, so only the compressed chunk crosses PCIe
+    // and the host does no decompression at all. AnalyzeCompressed says whether it took the image;
+    // when it declines (a CPU preprocessor, or an algorithm with no device decoder) fall through to
+    // the host route unchanged. The two produce the same preprocessed image.
     const auto compression_start_time = std::chrono::steady_clock::now();
-    const uint8_t *image_ptr = Decompress(output.image);
+    ImageStatistics ret{};
+    const bool decoded_on_device = preprocessor->AnalyzeCompressed(*preprocessor_buffer, output.image, ret);
     const auto compression_end_time = std::chrono::steady_clock::now();
-    if (output.image.GetCompressionAlgorithm() != CompressionAlgorithm::NO_COMPRESSION)
-        output.compression_time_s = std::chrono::duration<float>(compression_end_time - compression_start_time).count();
 
-    const auto preprocessing_start_time = std::chrono::steady_clock::now();
-    auto ret = preprocessor->Analyze(*preprocessor_buffer, image_ptr, output.image.GetMode());
-    const auto preprocessing_end_time = std::chrono::steady_clock::now();
-    output.preprocessing_time_s = std::chrono::duration<float>(preprocessing_end_time - preprocessing_start_time).count();
+    if (!decoded_on_device) {
+        const uint8_t *image_ptr = Decompress(output.image);
+        const auto decompressed_time = std::chrono::steady_clock::now();
+        if (output.image.GetCompressionAlgorithm() != CompressionAlgorithm::NO_COMPRESSION)
+            output.compression_time_s = std::chrono::duration<float>(decompressed_time - compression_start_time).count();
+
+        const auto preprocessing_start_time = std::chrono::steady_clock::now();
+        ret = preprocessor->Analyze(*preprocessor_buffer, image_ptr, output.image.GetMode());
+        const auto preprocessing_end_time = std::chrono::steady_clock::now();
+        output.preprocessing_time_s = std::chrono::duration<float>(preprocessing_end_time - preprocessing_start_time).count();
+    } else {
+        // Decode and preprocess are one device operation here, so they are reported together rather
+        // than split into a decompression time that no longer exists on the host.
+        output.preprocessing_time_s = std::chrono::duration<float>(compression_end_time - compression_start_time).count();
+    }
 
     // The fused GPU engine (rugnux offline, GPU, adaptive detection) produces the azimuthal profile as
     // a byproduct of spot finding, so the separate azint pass is skipped in that case and the profile is